Подчистил архитектуру приложения v1 работает

.analysis/README.md

@@ -0,0 +1,14 @@
+# Analysis Assets
+
+Этот каталог содержит служебные артефакты для аналитической и генеративной работы агента.
+
+## Структура
+
+- `rules/` — правила построения документации, frontmatter и шаблоны документов.
+
+## Назначение
+
+Каталог `.analysis/` отделен от `docs/`, чтобы:
+- хранить служебные policy- и template-материалы вне пользовательской документации;
+- передавать правила в LLM как отдельный policy-context;
+- не смешивать документацию проекта и внутренние артефакты анализа.

.analysis/rules/documentation-rules.md

@@ -0,0 +1,32 @@
+# Documentation Rules
+
+## Назначение
+
+Этот файл фиксирует общие правила формирования, обновления и поддержки технической документации проекта.
+
+Документация проекта должна создаваться как система атомарных, связанных между собой документов, пригодных:
+- для чтения человеком;
+- для сопровождения командой;
+- для индексирования в RAG;
+- для автоматического обновления агентом на основе кода и существующих артефактов.
+
+Этот файл задает:
+- общие принципы документационной архитектуры;
+- правила декомпозиции документации;
+- правила размещения файлов;
+- требования к связям между документами;
+- требования к качеству markdown-документов;
+- правила генерации и обновления документации агентом.
+
+Детальные шаблоны документов и правила frontmatter описываются отдельно:
+- `.analysis/rules/frontmatter-rules.md`
+- `.analysis/rules/templates/*.md`
+
+---
+
+## Область действия
+
+Правила из этого файла применяются ко всей проектной документации, размещаемой в:
+
+```text
+docs/documentation/

.analysis/rules/frontmatter-rules.md

@@ -0,0 +1,60 @@
+# Frontmatter Rules
+
+## Назначение
+
+Этот файл фиксирует правила YAML frontmatter для документов в `docs/documentation/`.
+
+Frontmatter обязателен для каждого markdown-документа и нужен для:
+- идентификации документа;
+- определения типа документа;
+- фиксации связей с кодом и другими документами;
+- выделения сущностей, тегов и домена;
+- поддержки индексирования в RAG.
+
+Общие правила построения документации описаны в:
+- `.analysis/rules/documentation-rules.md`
+
+Шаблоны markdown body описаны в:
+- `.analysis/rules/templates/*.md`
+
+---
+
+## Общие правила
+
+1. Frontmatter размещается в начале файла.
+2. Формат — YAML между двумя строками `---`.
+3. Все документы в `docs/documentation/` должны содержать frontmatter.
+4. Поля должны быть стабильными и заполняться единообразно.
+5. Не использовать произвольные поля без необходимости.
+6. Если значение неизвестно и его нельзя уверенно вывести из evidence, поле лучше не заполнять, кроме обязательных полей.
+7. Списковые поля должны оформляться как YAML-массивы.
+8. Идентификаторы и ссылки должны быть стабильными и пригодными для машинной обработки.
+
+---
+
+## Базовый frontmatter
+
+Каждый документ должен начинаться с frontmatter вида:
+
+```yaml
+---
+id: api-orders-create
+title: Метод создания заказа
+doc_type: api_method
+domain: orders
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - ui-order-create-page
+  - logic-order-validation
+related_code:
+  - src/orders/api/create_order.py
+entities:
+  - Order
+  - CreateOrder
+tags:
+  - api
+  - orders
+  - create
+---

.analysis/rules/legacy/rule_templates_path.md

@@ -0,0 +1,29 @@
+# Rule: Use Document Templates From Fixed Paths
+
+Агент должен создавать и обновлять техническую документацию только с опорой на шаблоны документов, расположенные в `.analysis/rules`.
+
+Если агент формирует новый документ, он обязан:
+
+- определить тип документа;
+- выбрать соответствующий шаблон по фиксированному пути;
+- сохранить структуру секций и базовых метаданных из шаблона;
+- заполнять только те секции, которые подтверждены кодом и артефактами;
+- не придумывать новые произвольные форматы, если для типа уже существует шаблон.
+
+Пути к базовым шаблонам:
+
+- `.analysis/rules/legacy/template_ui_page.md`
+- `.analysis/rules/legacy/template_api_method.md`
+- `.analysis/rules/legacy/template_logic_block.md`
+
+Правило выбора шаблона:
+
+- для документа типа `ui_page` использовать `.analysis/rules/legacy/template_ui_page.md`
+- для документа типа `api_method` использовать `.analysis/rules/legacy/template_api_method.md`
+- для документа типа `logic_block` использовать `.analysis/rules/legacy/template_logic_block.md`
+
+Если для нужного типа шаблон отсутствует, агент должен:
+
+1. использовать ближайший подходящий существующий шаблон как временную основу;
+2. явно сохранить тип документа в `YAML frontmatter`;
+3. не смешивать в одном документе несколько независимых сущностей.

.analysis/rules/legacy/template_api_method.md

@@ -0,0 +1,89 @@
+# Template: api_method
+
+```md
+---
+id: api-<stable-id>
+title: <Human-readable title>
+doc_type: api_method
+status: draft
+source_of_truth: code
+domain: <domain-name>
+owner: system-analyst
+endpoint: <METHOD /path>
+auth: <auth-mode-or-unknown>
+idempotent: <true-or-false>
+related_docs:
+  - <doc-id>
+related_code:
+  - <path/to/file>
+entities:
+  - <EntityName>
+tags:
+  - api
+---
+
+# <API Method Title>
+
+## Purpose
+
+Кратко опиши, какую системную задачу решает метод.
+
+## Endpoint Summary
+
+- Endpoint: `<METHOD /path>`
+- Auth: `<auth-mode>`
+- Idempotent: `<true/false>`
+- Triggered by: `<ui/system/integration if known>`
+
+## Technical Use Case
+
+Опиши пошагово обработку запроса:
+
+- вход в endpoint;
+- ключевые проверки;
+- вызовы логики;
+- обращения к БД и внешним системам;
+- формирование ответа.
+
+## Functional Requirements
+
+Вынеси сюда подтвержденные правила, которые дополняют основной сценарий:
+
+- валидации;
+- branching logic;
+- побочные эффекты;
+- ограничения по данным;
+- условия ошибок.
+
+## Request and Response Contract
+
+Опиши контракт в кратком виде или дай ссылку на OpenAPI / контрактный файл.
+
+## Related Logic Blocks
+
+- [<Logic block title>](<path-or-doc-link>)
+
+## Data Access and Integrations
+
+- Reads DB: `<if known>`
+- Writes DB: `<if known>`
+- Integrates with: `<if known>`
+
+## Non-Functional Requirements
+
+Укажи только подтвержденные НФТ:
+
+- timeout;
+- audit;
+- monitoring;
+- security;
+- idempotency rules.
+
+## Related Code
+
+- `<path/to/file>`
+
+## Related Documents
+
+- [<Related document>](<path-or-doc-link>)
+```

.analysis/rules/legacy/template_logic_block.md

@@ -0,0 +1,71 @@
+# Template: logic_block
+
+```md
+---
+id: logic-<stable-id>
+title: <Human-readable title>
+doc_type: logic_block
+status: draft
+source_of_truth: code
+domain: <domain-name>
+owner: system-analyst
+related_docs:
+  - <doc-id>
+related_code:
+  - <path/to/file>
+entities:
+  - <EntityName>
+tags:
+  - logic
+---
+
+# <Logic Block Title>
+
+## Purpose
+
+Кратко опиши, какую переиспользуемую или устойчивую логику реализует блок.
+
+## Where Used
+
+- Called from: `<ui/api/jobs/services if known>`
+- Used by: `<list of known callers>`
+
+## Technical Use Case
+
+Опиши пошагово, как работает логический блок:
+
+- входные данные;
+- ключевые проверки;
+- преобразования;
+- обращения к данным;
+- результат работы.
+
+## Functional Requirements
+
+Вынеси сюда устойчивые правила и ограничения:
+
+- бизнес-правила;
+- проверки;
+- ветвления;
+- ограничения на вход и выход;
+- условия отказа.
+
+## Dependencies
+
+- Uses logic: `<other logic blocks if known>`
+- Reads DB: `<if known>`
+- Writes DB: `<if known>`
+- Integrates with: `<if known>`
+
+## Error Cases
+
+Опиши значимые ошибки и условия их возникновения, если они подтверждены кодом.
+
+## Related Code
+
+- `<path/to/file>`
+
+## Related Documents
+
+- [<Related document>](<path-or-doc-link>)
+```

.analysis/rules/legacy/template_ui_page.md

@@ -0,0 +1,82 @@
+# Template: ui_page
+
+```md
+---
+id: ui-<stable-id>
+title: <Human-readable title>
+doc_type: ui_page
+status: draft
+source_of_truth: code
+domain: <domain-name>
+owner: system-analyst
+related_docs:
+  - <doc-id>
+related_code:
+  - <path/to/file>
+entities:
+  - <EntityName>
+tags:
+  - ui
+---
+
+# <Page Title>
+
+## Purpose
+
+Кратко опиши, какую пользовательскую задачу решает страница.
+
+## Route and Entry Points
+
+- Route: `<route-if-known>`
+- Entry points: `<where user comes from>`
+
+## Technical Use Case
+
+Опиши пошаговый сценарий работы страницы как поток действий и системных реакций.
+
+## UI Structure
+
+Перечисли основные UI-элементы и для каждого укажи:
+
+- назначение;
+- источник данных;
+- значение по умолчанию или placeholder;
+- условия доступности или активации;
+- поведение при взаимодействии;
+- правила валидации.
+
+## Functional Requirements
+
+Вынеси сюда детальные правила, которые не стоит перегружать в use case:
+
+- вызовы API;
+- обработку ответов;
+- локальные правила отображения;
+- условия переходов;
+- feature toggles.
+
+## Related APIs
+
+- [<API document title>](<path-or-doc-link>)
+
+## Related Logic Blocks
+
+- [<Logic block title>](<path-or-doc-link>)
+
+## Non-Functional Requirements
+
+Укажи НФТ, если они подтверждены:
+
+- analytics events;
+- observability;
+- feature toggles;
+- security constraints.
+
+## Related Code
+
+- `<path/to/file>`
+
+## Related Documents
+
+- [<Related document>](<path-or-doc-link>)
+```

.analysis/rules/templates/api_method.md

@@ -0,0 +1,115 @@
+# {{title}}
+
+## Summary
+- Purpose:
+- Actor:
+- Trigger:
+- Endpoint:
+- Main entities:
+- Main logic:
+- Main errors:
+- Source of truth:
+
+## Назначение
+
+## Контекст
+
+## Технический use case
+
+### Основной сценарий
+
+1.
+2.
+3.
+
+### Альтернативные ветки
+
+- 
+- 
+
+## Функциональные требования
+
+### Request validation
+- 
+
+### Processing rules
+- 
+
+### State changes
+- 
+
+### Side effects
+- 
+
+## Contract
+
+### Endpoint
+- Method:
+- Path:
+- Auth:
+- Idempotent:
+- Timeout:
+- Retry:
+
+### Request
+| Field | Type | Required | Constraints | Description |
+|------|------|----------|-------------|-------------|
+|      |      |          |             |             |
+
+### Response
+| Field | Type | Description |
+|------|------|-------------|
+|      |      |             |
+
+### External contract refs
+- OpenAPI:
+- Schema:
+- DTO / serializer:
+- Additional refs:
+
+## Errors
+
+| error_id | http_code | when | client_behavior | retry |
+|----------|-----------|------|-----------------|-------|
+|          |           |      |                 |       |
+
+## Нефункциональные требования
+
+### Security
+- 
+
+### Observability
+- Logs:
+- Metrics:
+- Traces:
+- Audit:
+
+### Reliability
+- 
+- 
+
+### Performance
+- 
+
+## Связанные блоки логики
+- 
+
+## Связанные сущности
+- 
+
+## Связанный код
+
+### Files
+- 
+
+### Symbols
+- 
+
+## Связанные документы
+- 
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+|      |        |         |

.analysis/rules/templates/architecture_overview.md

@@ -0,0 +1,105 @@
+# {{title}}
+
+## Summary
+- Scope:
+- Purpose:
+- Main modules:
+- Main domains:
+- Main integrations:
+- Key entrypoints:
+- Key data flows:
+- Source of truth:
+
+## Назначение
+
+## Контекст
+
+## Границы системы
+
+### In scope
+- 
+
+### Out of scope
+- 
+
+## Архитектурная схема
+
+## Основные модули
+
+| module | responsibility | depends_on | key_code_refs |
+|--------|----------------|------------|---------------|
+|        |                |            |               |
+
+## Основные доменные области
+
+- 
+- 
+
+## Основные интеграции
+
+| integration | direction | purpose | protocol / transport | related_docs |
+|-------------|-----------|---------|----------------------|--------------|
+|             |           |         |                      |              |
+
+## Основные потоки
+
+### Flow 1
+1.
+2.
+3.
+
+### Flow 2
+1.
+2.
+3.
+
+## Архитектурные решения и ограничения
+
+### Key decisions
+- 
+
+### Constraints
+- 
+
+### Risks
+- 
+
+## Нефункциональные аспекты
+
+### Security
+- 
+
+### Reliability
+- 
+
+### Observability
+- Logs:
+- Metrics:
+- Traces:
+- Audit:
+
+### Performance
+- 
+
+### Scalability
+- 
+
+## Связанные сущности
+- 
+
+## Связанный код
+
+### Files
+- 
+
+### Symbols
+- 
+
+## Связанные документы
+- 
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+|      |        |         |

.analysis/rules/templates/domain_entity.md

@@ -0,0 +1,92 @@
+# {{title}}
+
+## Summary
+- Domain:
+- Purpose:
+- Entity role:
+- Main attributes:
+- Lifecycle:
+- Invariants:
+- Related APIs:
+- Related logic:
+- Source of truth:
+
+## Назначение
+
+## Контекст
+
+## Роль в доменной модели
+
+## Атрибуты
+
+| attribute | type | required | description | constraints |
+|-----------|------|----------|-------------|-------------|
+|           |      |          |             |             |
+
+## Состояния и жизненный цикл
+
+### Основные состояния
+- 
+
+### Переходы состояний
+1.
+2.
+3.
+
+## Инварианты и ограничения
+
+- 
+- 
+
+## Связи с другими сущностями
+
+| entity | relation | description |
+|--------|----------|-------------|
+|        |          |             |
+
+## Использование в системе
+
+### Related API
+- 
+
+### Related UI
+- 
+
+### Related logic
+- 
+
+### Related integrations
+- 
+
+## Функциональные требования
+
+- 
+- 
+
+## Нефункциональные требования
+
+### Audit / history
+- 
+
+### Security
+- 
+
+### Observability
+- 
+
+## Связанный код
+
+### Files
+- 
+
+### Symbols
+- 
+
+## Связанные документы
+- 
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+|      |        |         |

.analysis/rules/templates/logic_block.md

@@ -0,0 +1,93 @@
+```md
+# {{title}}
+
+## Summary
+- Purpose:
+- Trigger:
+- Inputs:
+- Outputs:
+- Main entities:
+- Main dependencies:
+- Side effects:
+- Source of truth:
+
+## Назначение
+
+## Контекст
+
+## Технический use case
+
+### Основной сценарий
+
+1.
+2.
+3.
+
+### Альтернативные ветки
+
+- 
+- 
+
+## Функциональные требования
+
+### Preconditions
+- 
+
+### Processing rules
+- 
+
+### Validation rules
+- 
+
+### Output / result rules
+- 
+
+### Side effects
+- 
+
+## Ограничения и условия вызова
+
+- 
+- 
+
+## Нефункциональные требования
+
+### Security
+- 
+
+### Observability
+- Logs:
+- Metrics:
+- Traces:
+- Audit:
+
+### Reliability
+- 
+- 
+
+### Performance
+- 
+
+## Связанные API / UI / integration points
+- 
+
+## Связанные сущности
+- 
+
+## Связанный код
+
+### Files
+- 
+
+### Symbols
+- 
+
+## Связанные документы
+- 
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+|      |        |         |
+```

.analysis/rules/templates/ui_page.md

@@ -0,0 +1,97 @@
+# {{title}}
+
+## Summary
+- Purpose:
+- Actor:
+- Trigger:
+- Route:
+- Main API:
+- Main entities:
+- Main logic:
+- Main states:
+- Source of truth:
+
+## Назначение
+
+## Контекст
+
+## Технический use case
+
+### Основной сценарий
+
+1.
+2.
+3.
+
+### Альтернативные ветки
+
+- 
+- 
+
+## Описание UI
+
+## UI Elements
+
+| id | type | label | data_source | default / placeholder | validation | behavior |
+|----|------|-------|-------------|------------------------|------------|----------|
+|    |      |       |             |                        |            |          |
+
+## Функциональные требования
+
+### Input rules
+- 
+
+### State rules
+- 
+
+### Navigation rules
+- 
+
+### Client-side validation
+- 
+
+## Нефункциональные требования
+
+### Security
+- 
+
+### Observability
+- Logs:
+- Metrics:
+- Traces:
+- Analytics:
+
+### Accessibility
+- 
+
+### Performance
+- 
+
+### Feature toggles
+- 
+
+## Связанные API
+- 
+
+## Связанные блоки логики
+- 
+
+## Связанные сущности
+- 
+
+## Связанный код
+
+### Files
+- 
+
+### Symbols
+- 
+
+## Связанные документы
+- 
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+|      |        |         |

.cursor/rules/documentation.mdc

@@ -0,0 +1,15 @@
+---
+alwaysApply: true
+---
+
+При задачах на создание или обновление документации всегда:
+1. Читай .analysis/rules/documentation-rules.md, .analysis/rules/frontmatter-rules.md и нужный шаблон из .analysis/rules/templates/.
+2. Создавай и обновляй документы только в docs/documentation/.
+3. Не создавай дублей: сначала ищи существующий документ, потом обновляй его.
+4. Соблюдай принцип: один документ = одна сущность / один устойчивый аспект.
+5. Каждый документ должен иметь YAML frontmatter, обязательные разделы Summary и Details и структуру по шаблону.
+6. Все связи фиксируй явно: related_docs, related_code, entities, tags и typed-поля.
+7. Используй только подтвержденный evidence из кода, контрактов, конфигов и существующей документации.
+8. Не дублируй содержание между документами — используй ссылки.
+9. Явно указывай связанный код и связанные документы.
+10. Не выдумывай факты, если evidence недостаточно.

.vscode/launch.json

@@ -0,0 +1,25 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Agent Backend: Uvicorn (Debug)",
+      "type": "python",
+      "request": "launch",
+      "module": "uvicorn",
+      "args": [
+        "app.main:app",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "15000"
+      ],
+      "cwd": "${workspaceFolder}",
+      "envFile": "${workspaceFolder}/.env",
+      "env": {
+        "PYTHONPATH": "${workspaceFolder}/src"
+      },
+      "console": "integratedTerminal",
+      "justMyCode": false
+    }
+  ]
+}

Dockerfile

@@ -3,12 +3,13 @@ FROM python:3.12-slim
 WORKDIR /app
 
 ENV PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app/src
 
 COPY requirements.txt ./
 RUN pip install --no-cache-dir -r requirements.txt
 
-COPY app ./app
+COPY src ./src
 
 EXPOSE 15000
 

_process/01. Process.md

@@ -0,0 +1,126 @@
+# Процессы работы с документацией (AS IS / TO BE)
+
+
+## Основные артефакты системной аналитики
+Системные аналитики работают с 3 артефактами:
+
+- бизнес-требованиями
+- системной аналитикой
+- технической документацией
+
+
+### Бизнес требования
+Описывает бизнес и пользовательские требования, пользователькие use case, макеты экранов.
+Сейчас не всегда оформляется как отдельный документ, часто этот шаг пропускается и требования фиксируются сразу в документе системной аналитики.
+
+
+### Системная аналитика
+Документ описыватет изменения в автоматизированной системе. Пишется системными аналитиками для разработчиков и тестировщиков. Так же этот документ проходит согласование с экспертами по архитектуре, безопасности, сопровождению. 
+
+Может описывать как целиком процесс (в случае реализации с нуля), так и инкремент, который вносит небольшие изменения в существующие процессы.
+
+В данном документе содкржится вся информация по сути вносимых изменений, но отсутствует контекст о текущей реализации системы.
+
+Состоит из разделов:
+- Цели - короткое описание какую проблему и для кого решаем.
+- Процесс AS IS и TO BE - фокус на изменения с точки зрения бизнес функций, без технической детализации.
+- Ограничения - ограничения и допущения в реализации.
+- Архитектура - описывает схему уровня контейнеров, основной фокус на интеграции между контейнерами и интеграционные сценарии.
+- Функциональные требования - описывают изменения в системе.
+- Нефункциональные требования - требования к аудиту, мониторингу, фичетоглам, пользовтелькой аналитике.
+
+
+### Техническая документация
+Техническая документация описывает реализацию системы. Эта информация используется командой разработки при проектировании и реализации новых фичей, понимании как работает система. Артефакт живет чуть впереди кода
+Представялет из себя иерархическую модель документов, сейчас реализованную в конфлюенсе.
+
+Есть несколько типов страниц, каждая из которы описывает определенный тип функциональности
+
+- UI страницы
+- API методы
+- БД
+- Логические блоки
+
+#### UI страницы
+Описывают экран на UI. 
+**Декомпозиция**
+Как правило на страницу с описанием выносится целый макет/страница фронтального приложения, с одной основной интеграцией и опционально вспомогательными интеграциями. 
+Например - форма создания сущности. Есть вспомогательгные методы для полученяи правочников, использующихся при заполнении полей на форме, и вызов оснвного метода создания сущности.
+
+Таким образом приложение декомпозируется на отдельные экраны, коотры свызываются между собой последовательно, но сами по себе являются независимыми
+
+**Состав описания**
+Все разделы обязательны.
+Страница с описанием содержит:
+ - Краткое описание
+ - Технический use case
+ - Описание макета с декомпозицией на компоненты + их поведение 
+ - Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
+ - Нефункциональные требования - фичетоглы и события пользовательской аналитики
+
+
+#### API методы
+**Декомпозиция**
+На каждый метод API заводится отдельная страница.
+**Состав описания**
+Все разделы обязательны.
+Страница с описанием содержит:
+ - Краткое описание
+ - Технический use case
+ - Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
+ - Нефункциональные требования - фичетоглы и события пользовательской аналитики
+ - Контракт метода - описание запроса и ответа. Для ответа так же приводится описание как заполнять поля.
+
+#### БД
+**Декомпозиция**
+Сейсас это только странциа с описанием таблица. На каждую таблицу заводится отдельная страница.
+**Состав описания**
+Все разделы обязательны.
+Страница с описанием содержит:
+ - Краткое описание
+ - Таблица с офисанием физической модели данных
+
+#### Логические блоки
+**Декомпозиция**
+На отдельную страницу может быть вынесен общий переиспользуемый блок логики. Это позволяет не дублировать его на страницах документации. Как правило соответствует реализации общего компонента в коде.
+**Состав описания**
+Часть разделов в описании может отсутствовать.
+ - Краткое описание
+ - Технический use case
+ - Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
+ - Нефункциональные требования - фичетоглы и события пользовательской аналитики
+
+#### Прочие особенности процесса
+##### Описание технических use cases
+Сценарий описывает основные шаги процесса в разрезе участников, все технические детали, если их нельзя описать одним предложением, выносятся в разделы функциональных требований, нефункциональных требований, или даются ссылки на другие страницы (как правило это страницы с логическими блоками).
+
+В технических use cases приводятся ссылки на страницы с описнаием вызываемых методов API. Особенно это актуально для страниц фронта, т.к. он использует наши методы API, которые есть в документации. Для интеграций с другими АС как правило приводистя ссылка на описание конфлюенса.
+
+
+
+## AS IS
+Сейчас все артефакты ведутся в конфлюенс. Одна страница содержит описанием одного аретфакта (бизнес требования, системная аналитика, страница документации), страницы организованы иерархически, используюстя ссылки для обозначения связей.
+
+Проблемы:
+- документация со временем теряет актуальность
+- отсутствие автоматизации
+- ручное ведение
+---
+
+## TO BE
+
+Целевое состояние:
+- аналитик продолжает писать артефакты бизнес-требований и системной аналитики
+- агент генерирует и обновляет документацию по странице системной аналитики
+- документация становится инженерным артефактом, который ведется в GIT
+
+### Форматы
+- Markdown
+- OpenAPI
+- Mermaid / PlantUML
+
+### Роль агента
+- использование документации как базы знаний - как для ответов на вопросы, так и для проектирования изменений в системе.
+- внесение изменений в документацию по артефактам системной аналитики
+- генерация из документации спецификаций OPENAPI и JSON-schema
+

_process/02. Agent architecture.md

@@ -0,0 +1,235 @@
+Ниже обновленная версия с учетом гибридной модели интент роутера.
+
+---
+
+## 1. Концепция агента
+
+Агент проектируется как intent-driven система для работы с кодом и документацией, где пользовательский запрос сначала нормализуется и интерпретируется, затем по нему извлекается релевантный контекст из многослойного RAG, после чего специализированный task workflow выполняет целевую задачу. Агент не является единым “умным чатом”: логика разделена на маршрутизацию, retrieval и специализированные execution workflows. Проверка evidence, вызовы LLM и правила сборки ответа находятся внутри task workflows и зависят от типа задачи.
+
+---
+
+## 2. Компонентная модель
+
+```mermaid
+flowchart LR
+    IDE[IDE Plugin / Client] --> API[API Layer]
+    API --> IR[IntentRouter V3]
+    IR --> RAG[Retrieval RAG]
+
+    RAG --> TW1[Task Workflow: Documentation Explain]
+    RAG --> TW2[Task Workflow: OpenAPI Generation]
+    RAG --> TW3[Task Workflow: Documentation Generation]
+    RAG --> TWN[Other Specialized Task Workflows]
+
+    TW1 --> OUT[Response / Artifact]
+    TW2 --> OUT
+    TW3 --> OUT
+    TWN --> OUT
+```
+
+---
+
+## 3. Основной flow процесса
+
+### Основной процесс
+
+1. Пользователь отправляет запрос через IDE plugin или другой клиент.
+2. `API Layer` принимает запрос и передает его в агент.
+3. `IntentRouter V3`:
+
+   * нормализует запрос;
+   * детерминированно извлекает ключевые артефакты;
+   * с помощью LLM определяет тип задачи и параметры обработки;
+   * формирует параметры retrieval.
+4. Выполняется извлечение данных из `Retrieval RAG`.
+5. Извлеченный контекст передается в соответствующий `Task Workflow`.
+6. Внутри workflow выполняется:
+
+   * подготовка контекста;
+   * evidence-проверки;
+   * вызовы LLM;
+   * формирование результата.
+7. Результат возвращается пользователю.
+
+### Sequence diagram
+
+```mermaid
+sequenceDiagram
+    participant User as User / IDE Plugin
+    participant API as API Layer
+    participant Router as IntentRouter V3
+    participant RAG as Retrieval RAG
+    participant WF as Task Workflow
+
+    User->>API: request
+    API->>Router: agent call
+    Router->>Router: normalize + extract artifacts
+    Router->>Router: LLM routing (task / intent)
+    Router->>RAG: retrieval request
+    RAG-->>Router: retrieved context
+    Router->>WF: route result + context
+    WF->>WF: evidence logic + LLM calls
+    WF-->>API: final result
+    API-->>User: response
+```
+
+---
+
+## 4. Описание компонентов
+
+### 4.1. IDE Plugin / Client
+
+**Задача**
+Точка входа пользователя в агент.
+
+**Как устроен**
+Любой внешний клиент (IDE plugin, web UI и др.), который отправляет запрос и получает результат.
+
+**Почему так**
+Агент изначально проектируется как backend-система, независимая от интерфейса.
+
+---
+
+### 4.2. API Layer
+
+**Задача**
+Обеспечивает внешний интерфейс взаимодействия с агентом.
+
+**Как устроен**
+Принимает запрос, валидирует его и передает во внутренний pipeline, затем возвращает результат.
+
+**Почему так**
+Позволяет изолировать транспортный слой от логики агента.
+
+---
+
+### 4.3. IntentRouter V3
+
+**Задача**
+Определяет, как должен обрабатываться пользовательский запрос и какой сценарий выполнения применить.
+
+**Как устроен**
+
+Гибридная модель из двух частей:
+
+#### 1. Детерминированный слой
+
+Выполняет:
+
+* нормализацию запроса;
+* извлечение ключевых артефактов:
+
+  * домены;
+  * типы сущностей (API, entity, component и т.д.);
+  * явные ссылки (endpoint, путь, имя);
+* выделение базовых сигналов (например: explain / list / generate).
+
+Этот слой задает **жесткие рамки интерпретации запроса**.
+
+#### 2. LLM-роутинг
+
+Использует:
+
+* нормализованный запрос;
+* извлеченные артефакты;
+* описание доступных типов задач;
+
+и определяет:
+
+* тип задачи;
+* общий сценарий обработки;
+* параметры retrieval;
+* ожидаемую форму ответа.
+
+#### Итог
+
+Router формирует:
+
+* параметры retrieval;
+* тип task workflow;
+* контекст для дальнейшего выполнения.
+
+**Почему решение такое**
+
+Ранее использовался более детерминированный подход с фиксированными сценариями, который хорошо работал в узком наборе задач, но плохо масштабируется. Полностью LLM-based роутинг, наоборот, дает гибкость, но теряет предсказуемость и управляемость.
+
+Поэтому выбран гибридный подход:
+
+* детерминированный слой фиксирует ключевые артефакты и ограничения;
+* LLM выполняет гибкую интерпретацию задачи.
+
+Это позволяет:
+
+* сохранить управляемость и стабильность;
+* избежать взрывного роста количества сценариев;
+* поддерживать сложные и нетиповые запросы.
+
+---
+
+### 4.4. Retrieval RAG
+
+**Задача**
+Извлечь релевантный контекст для выполнения задачи.
+
+**Как устроен**
+Многослойная система хранения знаний (код, документация, факты, связи), из которой извлекается структурированный контекст в зависимости от параметров, заданных роутером.
+
+**Почему так**
+Разные задачи требуют разных типов данных, поэтому используется слойная модель вместо плоского поиска.
+
+---
+
+### 4.5. Task Workflows
+
+**Задача**
+Реализуют прикладную логику выполнения конкретного типа задачи.
+
+**Как устроены**
+Набор специализированных workflows, например:
+
+* объяснение по документации;
+* генерация OpenAPI;
+* генерация документации;
+* другие сценарии.
+
+Внутри workflow находятся:
+
+* обработка контекста;
+* evidence-проверки;
+* вызовы LLM;
+* сборка результата.
+
+**Почему так**
+Логика проверки данных и генерации сильно зависит от задачи, поэтому она инкапсулируется в отдельных workflows, а не в одном универсальном слое.
+
+---
+
+### 4.6. Output / Artifact
+
+**Задача**
+Вернуть результат пользователю.
+
+**Как устроен**
+Может быть:
+
+* текстовый ответ;
+* структурированный список;
+* OpenAPI спецификация;
+* документация;
+* иной артефакт.
+
+**Почему так**
+Агент должен поддерживать не только ответы, но и генерацию инженерных артефактов.
+
+---
+
+## Итог
+
+Обновленная архитектура строится на следующем принципе:
+
+* **детерминированное извлечение ключевых артефактов** задает рамки;
+* **LLM выполняет гибкий роутинг внутри этих рамок**;
+* **retrieval обеспечивает данные**;
+* **task workflows реализуют прикладную логику и контроль качества**.
+
+Это позволяет одновременно сохранить управляемость системы и обеспечить масштабируемость под новые типы задач.

_process/04. Analitycs artefacts.md

@@ -0,0 +1,790 @@
+## 1. Формат ведения технической документации агентом
+
+## 1.1. Общие принципы
+
+Техническая документация, формируемая агентом, должна строиться как **система атомарных, не пересекающихся по смыслу документов**, связанных между собой явными ссылками.
+
+Ключевые принципы:
+- один документ описывает одну сущность или один устойчивый технический аспект;
+- документ не должен дублировать соседние документы;
+- общая система знаний должна собираться через ссылки, а не через копипасту;
+- структура документации должна быть пригодна как для чтения человеком, так и для индексирования в RAG.
+
+## 1.2. Базовые типы документных единиц
+
+На первом этапе логично сохранить текущую семантику типов документов, но перенести ее в файловую модель.
+
+Базовые типы:
+- `ui_page`
+- `api_method`
+- `logic_block`
+
+Позже могут добавиться:
+- `architecture_overview`
+- `integration_doc`
+- `domain_entity`
+- `glossary_item`
+- `index_page`
+
+## 1.3. Принцип декомпозиции страниц / файлов
+
+### Один устойчивый объект — один документ
+Если объект можно переиспользовать или на него могут ссылаться другие документы, его надо выносить в отдельный файл.
+
+Примеры:
+- отдельная UI-страница;
+- отдельный API endpoint;
+- отдельный блок логики;
+- отдельный интеграционный сценарий.
+
+### Документы не должны пересекаться по смыслу
+Если описание повторяется в нескольких местах, нужно выделять общий документ и ссылаться на него.
+
+Примеры:
+- фронтальная страница не должна заново описывать логику API;
+- документ по API не должен заново раскрывать общую логику переиспользуемого блока;
+- вместо дублирования должен быть переход по ссылке.
+
+### Use case и детальные правила живут раздельно
+Сценарий описывает поток работы, а детали выносятся в функциональные требования, отдельные блоки логики или контрактные описания.
+
+Это важно и для RAG-индексации:
+- сценарии индексируются как workflows;
+- отдельные правила — как facts;
+- сущности и блоки — как entities.
+
+## 1.4. Иерархическая организация документации
+
+Документация должна быть организована как иерархическое дерево каталогов и файлов, а не как набор неструктурированных страниц.
+
+Пример верхнего уровня:
+
+```text
+docs/
+  ui/
+  api/
+  logic/
+  domains/
+  integrations/
+  architecture/
+  glossary/
+  errors/
+```
+
+Пример организации:
+
+```text
+docs/
+  ui/
+    order-create-page.md
+    order-edit-page.md
+  api/
+    orders-create.md
+    orders-get.md
+  logic/
+    order-validation.md
+    order-enrichment.md
+  architecture/
+    system-overview.md
+    integration-landscape.md
+  errors/
+    catalog.yaml
+```
+
+## 1.5. Учет связей между документами
+
+Связи должны быть **явными и поддерживаемыми агентом**.
+
+Примеры:
+- UI-страница ссылается на API, который она вызывает;
+- API-документ ссылается на переиспользуемые логические блоки;
+- логический блок ссылается на связанные интеграции;
+- архитектурный обзор ссылается на набор конкретных модулей и документов;
+- документ по коду может ссылаться на системную аналитику, которая инициировала изменение.
+
+Именно эта сеть ссылок затем индексируется в слоях:
+- `D1_DOCUMENT_CATALOG`
+- `D3_ENTITY_CATALOG`
+- `D4_WORKFLOW_INDEX`
+- `D5_REFERENCE_GRAPH`
+- `D6_DOC_CODE_LINKS`
+
+## 1.6. Формат markdown-документов
+
+Основной формат технической документации — `Markdown`.
+
+Каждый документ состоит из двух частей:
+1. **YAML frontmatter** — структурные метаданные;
+2. **Markdown body** — основное содержимое по шаблону.
+
+## 3.7. YAML frontmatter
+
+Frontmatter нужен для:
+- определения типа документа;
+- идентификации документа;
+- определения его места в иерархии;
+- фиксации связей с кодом и другими документами;
+- выделения сущностей и тегов;
+- упрощения построения слоев `D1`, `D3`, `D5`, `D6`.
+
+### Базовый frontmatter
+
+```yaml
+---
+id: ui-order-create-page
+title: Страница создания заказа
+doc_type: ui_page
+domain: orders
+status: draft
+related_docs:
+  - api-orders-create
+  - logic-order-validation
+entities:
+  - Order
+  - CreateOrder
+tags:
+  - ui
+  - orders
+  - creation
+#owner: system-analyst
+#source_of_truth: code
+#related_code:
+#  - src/orders/ui/create_page.tsx
+#  - src/orders/api/orders_controller.py
+---
+```
+
+### Обязательные поля
+
+- `id` — стабильный уникальный идентификатор документа;
+- `title` — человекочитаемый заголовок;
+- `doc_type` — тип документа;
+- `related_docs` — ссылки на связанные документы;
+- `status` — статус документа;
+- `domain` - домен фичи (Карточка клиента, Задачи, Сделки, Предложения)
+- `sub_domain` - поддомен внутри основной сущности (Счета, ЗДА, ECM)
+
+### Рекомендуемые поля
+- `owner`
+- `entities`
+- `tags`
+- `parent`
+- `children`
+- `feature`
+- `system_analytics_refs`
+- `business_refs`
+- `updated_from`
+- `reviewers`
+- `source_of_truth`
+- `related_code`
+
+### Допустимые значения `doc_type`
+- `ui_page`
+- `api_method`
+- `logic_block`
+- `architecture_overview`
+- `integration_doc`
+- `domain_entity`
+- `glossary_item`
+- `index_page`
+
+### Допустимые значения `status`
+- `draft`
+- `in_review`
+- `approved`
+- `outdated`
+- `generated`
+- `active`
+
+### Допустимые значения `source_of_truth`
+- `code`
+- `doc`
+- `system_analysis`
+- `business_requirements`
+- `mixed`
+
+## 1.8. Typed frontmatter для разных типов документов
+
+У каждого типа документа есть:
+- **общие поля**;
+- **тип-специфичные поля**.
+
+### Пример для `api_method`
+
+```yaml
+---
+id: api.create_invoice
+doc_type: api_method
+domain: billing
+title: Создание инвойса
+
+endpoint: POST /api/v1/invoices
+auth: USER
+idempotent: false
+timeout_ms: 3000
+
+links:
+  called_by:
+    - ui.invoice_form
+  uses_logic:
+    - logic.invoice_validation
+  writes_db:
+    - db.invoices
+    - db.invoice_items
+  integrates_with:
+    - int.crm_sync
+
+related_docs:
+  - ui.invoice_form
+  - logic.invoice_validation
+related_code:
+  - services/billing/api/create_invoice.py
+entities:
+  - Invoice
+  - CreateInvoice
+
+tags:
+  - invoice
+  - create
+  - billing
+status: active
+version: 1.3
+source_of_truth: code
+---
+```
+
+### Для `api_method` полезно поддерживать
+
+- `endpoint`
+- `sup_parameters`
+- `role_model_actions`
+- `monitoring_actions`
+- `audit_actions`
+- `idempotent`
+- `timeout_ms`
+- `links.called_by`
+- `links.uses_logic`
+- `links.writes_db`
+- `links.integrates_with`
+
+### Для `ui_page` позже полезно поддерживать
+- `calls_api`
+- `user_analitycs_actions`
+- `sup_parameters`
+- `role_model_actions`
+- `entry_points`
+- `uses_logic`
+
+### Для `logic_block` полезно поддерживать
+
+- `called_from`
+- `uses_logic`
+- `reads_db`
+- `writes_db`
+- `integrates_with`
+
+## 1.9. Двухслойная структура документа: `Summary` + `Details`
+
+LLM не должна каждый раз тонуть в полном документе. Поэтому каждый документ должен содержать два уровня представления.
+
+### `Summary`
+Короткая, строго структурированная спецификация. Это слой **быстрого контекста**.
+
+Рекомендуемый объем:
+- примерно 30–60 строк;
+- без длинных пояснений;
+- только ключевые факты.
+
+Пример:
+
+```md
+## Summary
+- Purpose: создание инвойса из формы
+- Actor: пользователь
+- Trigger: Submit
+- Main API: POST /api/v1/invoices (api.create_invoice)
+- Validation: required fields, amount > 0, date <= today
+- Errors: 400(field errors), 409(duplicate), 503(retryable)
+- Analytics: event invoice_submit, invoice_error
+```
+
+### `Details`
+Полное раскрытие объекта:
+- use case;
+- функциональные требования;
+- UI;
+- API;
+- ошибки;
+- НФТ;
+- связи;
+- кодовые привязки.
+
+## 1.10. Общие требования к markdown body
+
+1. В документе должен быть один `H1`, совпадающий с `title`.
+2. Основные разделы используют `H2`.
+3. Подразделы внутри разделов используют `H3`.
+4. Не должно быть хаотической вложенности заголовков.
+5. Один раздел должен описывать одну смысловую часть.
+6. Текст не должен дублировать соседние документы.
+7. Вместо дублирования должны использоваться явные ссылки на связанные документы.
+8. Сценарии, правила, ограничения и ссылки на код должны быть отделены друг от друга.
+
+## 1.11. Базовый каркас markdown-документа
+
+```md
+---
+id: api-orders-create
+title: Метод создания заказа
+doc_type: api_method
+domain: orders
+status: draft
+source_of_truth: code
+related_docs:
+  - logic-order-validation
+  - ui-order-create-page
+related_code:
+  - src/orders/api/create_order.py
+entities:
+  - Order
+  - CreateOrder
+tags:
+  - api
+  - orders
+---
+
+# Метод создания заказа
+
+## Summary
+- Purpose: создание заказа
+- Actor: пользователь
+- Trigger: submit формы
+- Main API: POST /orders
+
+## Details
+### Описание
+### Технический use case
+### Функциональные требования
+### Нефункциональные требования
+### Контракт
+
+
+## 3.13. Специализированные шаблоны документов
+
+### UI Page
+
+```md
+# <Название страницы>
+
+## Summary
+## Назначение
+## Контекст
+## Технический use case
+## Описание UI
+## UI Elements
+## Функциональные требования
+## Нефункциональные требования
+## Связанные API
+## Связанные блоки логики
+## Связанный код
+## Связанные документы
+## История изменений
+```
+
+#### Требования к разделу `Описание UI`
+Для каждого элемента желательно описывать:
+- тип элемента;
+- назначение;
+- источник данных;
+- default / placeholder;
+- правила активации;
+- поведение при взаимодействии;
+- валидацию.
+
+#### Требования к разделу `UI Elements`
+UI-элементы должны храниться в **табличном** или **полуструктурированном** виде.
+
+Пример:
+
+```md
+## UI Elements
+
+| id     | type   | label   | data_source | validation | behavior |
+|--------|--------|---------|------------|------------|----------|
+| amount | input  | Amount  | local      | >0         | enables submit |
+| submit | button | Create  | -          | -          | calls api.create_invoice |
+```
+
+Если модель UI сложная, допустим sidecar-файл `ui_elements.yaml` или `ui_elements.json` рядом с основным документом.
+
+### API Method
+
+```md
+# <Название API метода>
+
+## Summary
+## Назначение
+## Контекст
+## Технический use case
+## Функциональные требования
+## Contract
+## Errors
+## Нефункциональные требования
+## Связанные блоки логики
+## Связанный код
+## Связанные документы
+## История изменений
+```
+
+#### Требования к разделу `Contract`
+Контракт может:
+- быть кратко описан прямо в документе;
+- ссылаться на OpenAPI;
+- ссылаться на отдельный контрактный файл.
+
+Для REST API целевым источником истины должен становиться `OpenAPI`.
+
+### Reusable Logic Block
+
+```md
+# <Название блока логики>
+
+## Summary
+## Назначение
+## Контекст
+## Технический use case
+## Функциональные требования
+## Ограничения и условия вызова
+## Нефункциональные требования
+## Связанные API / UI / integration points
+## Связанный код
+## Связанные документы
+## История изменений
+```
+
+## 3.14. Машинно-читаемые API-контракты
+
+Для API контрактов **источником истины** должен становиться:
+- `OpenAPI` — предпочтительно;
+- либо временно строгий markdown/yaml-контракт, если OpenAPI еще нет.
+
+Минимальный набор для API-контракта:
+- `endpoint`
+- `method`
+- `request fields`
+- `required / optional`
+- `constraints`
+- `response`
+- `errors`
+- `idempotency`
+- `retry`
+- `timeout`
+- `auth`
+
+## 3.15. Каталог ошибок
+
+Ошибки, HTTP-коды, retry-правила и клиентское поведение не должны размазываться по разным документам.
+
+Нужен единый каталог ошибок, например `docs/errors/catalog.yaml`.
+
+Пример:
+
+```yaml
+errors:
+  - error_id: invoice_validation_failed
+    http_code: 400
+    internal_code: BILLING_400_01
+    when: invalid request fields
+    client_behavior: show field errors
+    retry: false
+    owner: billing
+
+  - error_id: invoice_duplicate
+    http_code: 409
+    internal_code: BILLING_409_01
+    when: duplicate invoice detected
+    client_behavior: show duplicate warning
+    retry: false
+    owner: billing
+
+  - error_id: crm_sync_unavailable
+    http_code: 503
+    internal_code: BILLING_503_02
+    when: downstream CRM unavailable
+    client_behavior: retry later
+    retry: true
+    owner: billing
+```
+
+В API- и logic-документах лучше ссылаться на `error_id`, а не заново подробно описывать каждую ошибку.
+
+## 3.16. Требования к качеству документа для RAG
+
+1. **Явные заголовки** — не использовать безымянные блоки текста.
+2. **Атомарные утверждения** — не смешивать несколько правил в одном пункте, если их можно разделить.
+3. **Явные сущности** — использовать стабильные названия компонентов, API, модулей, страниц.
+4. **Явные ссылки** — не писать «этот метод», если можно указать конкретную ссылку или идентификатор.
+5. **Минимум дублирования** — повторяющийся контент должен заменяться ссылками.
+6. **Привязка к коду** — если документ описывает кодовый объект, это должно быть явно указано.
+7. **Разделение сценариев и правил** — workflow и fact-like требования должны быть отделены.
+
+## 3.17. Как структура markdown помогает RAG
+
+- `frontmatter` + заголовки → `D1_DOCUMENT_CATALOG`
+- `entities`, `tags`, устойчивые термины → `D3_ENTITY_CATALOG`
+- атомарные функциональные и нефункциональные требования → `D2_FACT_INDEX`
+- `Технический use case` → `D4_WORKFLOW_INDEX`
+- `related_docs`, явные ссылки → `D5_REFERENCE_GRAPH`
+- `related_code`, упоминания symbols и файлов → `D6_DOC_CODE_LINKS`
+- `Summary` → быстрый retrieval и short-form context для LLM
+
+## 3.18. Принципы генерации документации агентом
+
+Когда документ пишет агент, он должен:
+- сначала извлечь evidence из кода, системной аналитики и существующих документов;
+- определить тип документа;
+- заполнить frontmatter;
+- построить markdown body по шаблону;
+- явно указать связи с кодом и другими документами;
+- не дублировать уже существующее описание, если можно сослаться на него.
+
+---
+
+
+## 4.4. Layered RAG
+
+RAG строится как система специализированных слоев для двух основных доменов:
+- `CODE RAG`
+- `DOCS RAG`
+
+Каждый graph извлекает контекст не из одного общего индекса, а из нужного набора слоев в зависимости от intent.
+
+## 4.5. Evidence gate
+
+Перед синтезом ответа или документа агент должен проверять, хватает ли опоры.
+
+Примеры:
+- найден ли symbol;
+- найдено ли достаточное количество code chunks;
+- есть ли supporting relations;
+- есть ли document evidence;
+- есть ли docs ↔ code mapping.
+
+Если опоры недостаточно, агент должен:
+- деградировать в упрощенный режим;
+- честно фиксировать неполноту ответа;
+- при необходимости уходить в fallback.
+
+## 4.6. Synthesis layer
+
+На этом этапе LLM:
+- агрегирует найденные артефакты;
+- формирует объяснение;
+- пишет документ;
+- структурирует результат под нужный шаблон.
+
+LLM не должна быть основным источником фактов. Фактическая основа должна приходить из RAG и диагностируемого pipeline.
+
+## 4.7. Diagnostics
+
+Система должна сохранять диагностический след:
+- какой graph был выбран;
+- какие слои использовались;
+- что было найдено;
+- где retrieval был слабым;
+- почему был выбран fallback;
+- какие evidence стали основой ответа.
+
+## 4.8. Сценарии: Target Architecture vs MVP-now
+
+### 4.8.1. Target Architecture
+
+#### CODE
+- `OPEN_FILE` — открыть конкретный файл;
+- `OPEN_SYMBOL` — открыть класс / функцию / метод;
+- `EXPLAIN` — объяснить, как работает сущность или фрагмент;
+- `FIND_TESTS` — найти релевантные тесты;
+- `FIND_ENTRYPOINTS` — найти основные точки входа;
+- `RELATED_CODE` — найти связанные сущности и ближайший контекст.
+
+#### DOCS
+- `DOC_SEARCH` — найти релевантный фрагмент документации;
+- `DOC_EXPLAIN` — кратко объяснить, что сказано в документации по теме;
+- `DOC_ENTITY_LOOKUP` — найти разделы, связанные с сущностью или компонентом;
+- `GENERATE_DOCS_FROM_CODE` — сформировать документацию по коду с нуля для модуля, класса, функции, компонента или сценария.
+
+#### CROSS-DOMAIN
+- `FIND_IMPLEMENTATION_BY_DOC` — найти реализацию по описанию;
+- `FIND_DOC_BY_CODE` — найти документацию по коду;
+- `COMPARE_DOCS_AND_CODE` — базовое сопоставление документации и реализации.
+
+#### GENERAL / FALLBACK
+- `GENERAL_QA` — общий сценарий ответа на вопрос, если домен или интент не удалось определить уверенно.
+
+### 4.8.2. MVP-now
+
+В текущем цикле фокус на сценариях:
+
+- `OPEN_FILE`
+- `EXPLAIN`
+- `FIND_TESTS`
+- `FIND_ENTRYPOINTS`
+- `GENERAL_QA`
+
+DOCS и CROSS_DOMAIN остаются частью target architecture; в текущем цикле они не являются обязательной частью test-first MVP.
+
+---
+
+## 5. Структура слоев RAG
+
+## 5.1. CODE RAG
+
+### C0 — Source Chunks
+**Назначение:** базовые фрагменты исходного кода.  
+**Единица:** chunk кода.  
+**Как формируется:** исходные файлы обходятся и режутся на chunk’и с учетом структурных границ.  
+**Статус в MVP:** да.
+
+### C1 — Symbol Catalog
+**Назначение:** каталог модулей, классов, функций, методов и других значимых сущностей.  
+**Единица:** symbol.  
+**Как формируется:** из AST и синтаксического разбора кода.  
+**Статус в MVP:** да.
+
+### C2 — Symbol Relations
+**Назначение:** связи между symbols.  
+**Единица:** relation.  
+**Как формируется:** вторым проходом по AST и структурным зависимостям.  
+**Статус в MVP:** да, в ограниченном виде.
+
+### C3 — Entrypoints
+**Назначение:** каталог точек входа системы.  
+**Единица:** entrypoint.  
+**Как формируется:** специализированными детекторами entrypoint-паттернов.  
+**Статус в MVP:** да, минимально.
+
+### C4 — Execution Paths
+**Назначение:** типовые пути исполнения.  
+**Единица:** path.  
+**Как формируется:** поверх `C2` и `C3` через производную трассировку.  
+**Статус в MVP:** нет.
+
+### C5 — Test Mappings
+**Назначение:** связи production code ↔ tests.  
+**Единица:** mapping.  
+**Как формируется:** по путям, именам, импортам и конвенциям проекта.  
+**Статус в MVP:** да, минимально.
+
+### C6 — Code Facts
+**Назначение:** нормализованные факты из кода.  
+**Единица:** fact.  
+**Как формируется:** поверх `C1–C3` как производный слой.  
+**Статус в MVP:** нет.
+
+## 5.2. DOCS RAG
+
+### D0 — Document Chunks
+**Назначение:** базовые фрагменты документации.  
+**Единица:** document chunk.  
+**Как формируется:** документы нормализуются и режутся на chunk’и с сохранением `section path`.  
+**Статус в MVP:** да.
+
+### D1 — Document Catalog
+**Назначение:** каталог документов и разделов.  
+**Единица:** `document node / section node`.  
+**Как формируется:** из структуры документов и их заголовков.  
+**Статус в MVP:** да.
+
+### D2 — Fact Index
+**Назначение:** атомарные факты из документации.  
+**Единица:** fact.  
+**Как формируется:** из `D0/D1` через правила, шаблоны и при необходимости LLM extraction с валидацией.  
+**Статус в MVP:** частично.
+
+### D3 — Entity Catalog
+**Назначение:** каталог сущностей и понятий документации.  
+**Единица:** entity / concept.  
+**Как формируется:** из устойчивых терминов, заголовков, словарей и нормализации повторяющихся сущностей.  
+**Статус в MVP:** да, минимально.
+
+### D4 — Workflow Index
+**Назначение:** процедуры, сценарии, последовательности шагов.  
+**Единица:** workflow.  
+**Как формируется:** из use case, процессных разделов и последовательных описаний шагов.  
+**Статус в MVP:** нет.
+
+### D5 — Reference Graph
+**Назначение:** граф ссылок между документами, секциями, сущностями и фактами.  
+**Единица:** reference link.  
+**Как формируется:** из явных и неявных cross-links между документами.  
+**Статус в MVP:** нет.
+
+### D6 — Doc-Code Links
+**Назначение:** мост между документацией и кодом.  
+**Единица:** `doc artifact ↔ code artifact link`.  
+**Как формируется:** из имен, aliases, путей, устойчивых терминов и других надежных соответствий.  
+**Статус в MVP:** да, минимально.
+
+## 5.3. Layer scope: Target Architecture vs MVP-now
+
+### 5.3.1. Target Architecture
+
+Полная карта слоёв:
+
+- **CODE:** C0–C6 (Source Chunks, Symbol Catalog, Symbol Relations, Entrypoints, Execution Paths, Test Mappings, Code Facts)
+- **DOCS:** D0–D6 (Document Chunks, Document Catalog, Fact Index, Entity Catalog, Workflow Index, Reference Graph, Doc-Code Links)
+
+### 5.3.2. MVP-now
+
+**Обязательные сейчас:**
+
+- `C0_SOURCE_CHUNKS`
+- `C1_SYMBOL_CATALOG`
+- `C2_SYMBOL_RELATIONS`
+- `C3_ENTRYPOINTS`
+
+**В облегчённом виде:**
+
+- `C5_TEST_MAPPINGS` или `C5-lite`
+
+**Не блокируют текущий этап:**
+
+- `C4_EXECUTION_PATHS`
+- `C6_CODE_FACTS`
+- весь docs runtime (слои D0–D6 в исполнении runtime)
+
+Слои документации остаются частью target architecture; docs retrieval пока не обязателен для текущего code-first milestone.
+
+---
+
+## 6. Итоговая рамка MVP-now
+
+Сейчас система должна стабильно работать в **test-first** режиме.
+
+**Фокус:**
+
+- CODE_QA;
+- через тесты настраиваются:
+  - intent routing (IntentRouterV2);
+  - layered retrieval;
+  - evidence sufficiency;
+  - answer quality;
+  - diagnostics.
+
+**Не входят в текущий milestone:**
+
+- UI-интеграция;
+- docs runtime;
+- полная интеграция orchestration переносится на следующий этап после стабилизации test pipeline.
+
+В целевой архитектуре по-прежнему заложены:
+- уверенная работа с кодом, symbols, entrypoints, тестами;
+- ответ по документации и мост docs ↔ code;
+- генерация документации по коду;
+- fallback при неуверенном роутинге.
+
+В MVP-now сознательно **не включаются** самые дорогие части:
+- полноценные execution paths для всей системы;
+- богатые fact-индексы по всем доменам;
+- полный reference graph документации;
+- глубокая автоматизация подготовки системной аналитики.

docker-compose.yml

@@ -27,7 +27,7 @@ services:
     env_file:
       - .env
     environment:
-      DATABASE_URL: ${DATABASE_URL}
+      DATABASE_URL: postgresql+psycopg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
       GIGACHAT_AUTH_URL: ${GIGACHAT_AUTH_URL}
       GIGACHAT_API_URL: ${GIGACHAT_API_URL}
       GIGACHAT_SCOPE: ${GIGACHAT_SCOPE}

docs/architecture/contracts_retrieval.json

@@ -1,380 +0,0 @@
-{
-  "layers": {
-    "C0_SOURCE_CHUNKS": {
-      "retriever": {
-        "class": "RagService",
-        "file": "app/modules/rag/services/rag_service.py",
-        "method": "retrieve"
-      },
-      "indexer": {
-        "class": "CodeTextDocumentBuilder",
-        "file": "app/modules/rag/indexing/code/code_text/document_builder.py",
-        "method": "build"
-      },
-      "input": {
-        "type": "observed shape",
-        "fields": {
-          "rag_session_id": {
-            "type": "string",
-            "required": true
-          },
-          "query": {
-            "type": "string",
-            "required": true
-          },
-          "layers": {
-            "type": "implicit list[string]",
-            "required": false,
-            "source": "RagQueryRouter.layers_for_mode('code')"
-          }
-        }
-      },
-      "output": {
-        "type": "list[dict]",
-        "fields": {
-          "source": "string",
-          "content": "string",
-          "layer": "\"C0_SOURCE_CHUNKS\"",
-          "title": "string",
-          "metadata": {
-            "chunk_index": "int",
-            "chunk_type": "\"symbol_block\" | \"window\"",
-            "module_or_unit": "string",
-            "artifact_type": "\"CODE\""
-          },
-          "score": "float | null"
-        }
-      },
-      "examples": {
-        "input": {
-          "rag_session_id": "rag-123",
-          "query": "where is implemented get_user"
-        },
-        "output": {
-          "source": "app/api/users.py",
-          "content": "async def get_user(user_id: str):\n    service = UserService()\n    return service.get_user(user_id)",
-          "layer": "C0_SOURCE_CHUNKS",
-          "title": "app/api/users.py:get_user",
-          "metadata": {
-            "chunk_index": 0,
-            "chunk_type": "symbol_block",
-            "module_or_unit": "app.api.users",
-            "artifact_type": "CODE"
-          },
-          "score": 0.07
-        }
-      },
-      "defaults": {
-        "retrieve_limit": 8,
-        "embed_batch_size_env": "RAG_EMBED_BATCH_SIZE",
-        "embed_batch_size_default": 16,
-        "window_chunk_size_lines": 80,
-        "window_overlap_lines": 15
-      },
-      "limitations": [
-        "Line spans are stored but not returned in the public retrieval item shape.",
-        "No direct path or namespace filter is exposed through the retrieval endpoint."
-      ]
-    },
-    "C1_SYMBOL_CATALOG": {
-      "retriever": {
-        "class": "RagService",
-        "file": "app/modules/rag/services/rag_service.py",
-        "method": "retrieve"
-      },
-      "indexer": {
-        "class": "SymbolDocumentBuilder",
-        "file": "app/modules/rag/indexing/code/symbols/document_builder.py",
-        "method": "build"
-      },
-      "input": {
-        "type": "observed shape",
-        "fields": {
-          "rag_session_id": {
-            "type": "string",
-            "required": true
-          },
-          "query": {
-            "type": "string",
-            "required": true
-          },
-          "query_term_expansion": {
-            "type": "list[string]",
-            "required": false,
-            "source": "extract_query_terms(query_text)",
-            "max_items": 6
-          }
-        }
-      },
-      "output": {
-        "type": "list[dict]",
-        "fields": {
-          "source": "string",
-          "content": "string",
-          "layer": "\"C1_SYMBOL_CATALOG\"",
-          "title": "string",
-          "metadata": {
-            "symbol_id": "string",
-            "qname": "string",
-            "kind": "\"class\" | \"function\" | \"method\" | \"const\"",
-            "signature": "string",
-            "decorators_or_annotations": "list[string]",
-            "docstring_or_javadoc": "string | null",
-            "parent_symbol_id": "string | null",
-            "package_or_module": "string",
-            "is_entry_candidate": "bool",
-            "lang_payload": "object",
-            "artifact_type": "\"CODE\""
-          },
-          "score": "float | null"
-        }
-      },
-      "examples": {
-        "input": {
-          "rag_session_id": "rag-123",
-          "query": "where is implemented get_user"
-        },
-        "output": {
-          "source": "app/api/users.py",
-          "content": "function get_user\nget_user(user_id)",
-          "layer": "C1_SYMBOL_CATALOG",
-          "title": "get_user",
-          "metadata": {
-            "symbol_id": "sha256(...)",
-            "qname": "get_user",
-            "kind": "function",
-            "signature": "get_user(user_id)",
-            "decorators_or_annotations": [
-              "router.get"
-            ],
-            "docstring_or_javadoc": null,
-            "parent_symbol_id": null,
-            "package_or_module": "app.api.users",
-            "is_entry_candidate": true,
-            "lang_payload": {
-              "async": true
-            },
-            "artifact_type": "CODE"
-          },
-          "score": 0.07
-        }
-      },
-      "defaults": {
-        "retrieve_limit": 8,
-        "layer_rank": 1
-      },
-      "limitations": [
-        "Only Python AST symbols are indexed.",
-        "Cross-file resolution is not implemented.",
-        "parent_symbol_id is an observed qname-like value, not guaranteed to be a symbol hash."
-      ]
-    },
-    "C2_DEPENDENCY_GRAPH": {
-      "retriever": {
-        "class": "RagService",
-        "file": "app/modules/rag/services/rag_service.py",
-        "method": "retrieve"
-      },
-      "indexer": {
-        "class": "EdgeDocumentBuilder",
-        "file": "app/modules/rag/indexing/code/edges/document_builder.py",
-        "method": "build"
-      },
-      "input": {
-        "type": "observed shape",
-        "fields": {
-          "rag_session_id": {
-            "type": "string",
-            "required": true
-          },
-          "query": {
-            "type": "string",
-            "required": true
-          }
-        }
-      },
-      "output": {
-        "type": "list[dict]",
-        "fields": {
-          "source": "string",
-          "content": "string",
-          "layer": "\"C2_DEPENDENCY_GRAPH\"",
-          "title": "string",
-          "metadata": {
-            "edge_id": "string",
-            "edge_type": "\"calls\" | \"imports\" | \"inherits\"",
-            "src_symbol_id": "string",
-            "src_qname": "string",
-            "dst_symbol_id": "string | null",
-            "dst_ref": "string | null",
-            "resolution": "\"resolved\" | \"partial\"",
-            "lang_payload": "object",
-            "artifact_type": "\"CODE\""
-          },
-          "score": "float | null"
-        }
-      },
-      "examples": {
-        "input": {
-          "rag_session_id": "rag-123",
-          "query": "how get_user calls service"
-        },
-        "output": {
-          "source": "app/api/users.py",
-          "content": "get_user calls UserService",
-          "layer": "C2_DEPENDENCY_GRAPH",
-          "title": "get_user:calls",
-          "metadata": {
-            "edge_id": "sha256(...)",
-            "edge_type": "calls",
-            "src_symbol_id": "sha256(...)",
-            "src_qname": "get_user",
-            "dst_symbol_id": null,
-            "dst_ref": "UserService",
-            "resolution": "partial",
-            "lang_payload": {
-              "callsite_kind": "function_call"
-            },
-            "artifact_type": "CODE"
-          },
-          "score": 0.11
-        }
-      },
-      "defaults": {
-        "retrieve_limit": 8,
-        "layer_rank": 2,
-        "graph_build_mode": "static_python_ast"
-      },
-      "limitations": [
-        "No traversal API exists.",
-        "Edges are stored as retrievable rows, not as a graph-native store.",
-        "Destination resolution is local to one indexed file."
-      ]
-    },
-    "C3_ENTRYPOINTS": {
-      "retriever": {
-        "class": "RagService",
-        "file": "app/modules/rag/services/rag_service.py",
-        "method": "retrieve"
-      },
-      "indexer": {
-        "class": "EntrypointDocumentBuilder",
-        "file": "app/modules/rag/indexing/code/entrypoints/document_builder.py",
-        "method": "build"
-      },
-      "input": {
-        "type": "observed shape",
-        "fields": {
-          "rag_session_id": {
-            "type": "string",
-            "required": true
-          },
-          "query": {
-            "type": "string",
-            "required": true
-          }
-        }
-      },
-      "output": {
-        "type": "list[dict]",
-        "fields": {
-          "source": "string",
-          "content": "string",
-          "layer": "\"C3_ENTRYPOINTS\"",
-          "title": "string",
-          "metadata": {
-            "entry_id": "string",
-            "entry_type": "\"http\" | \"cli\"",
-            "framework": "\"fastapi\" | \"flask\" | \"typer\" | \"click\"",
-            "route_or_command": "string",
-            "handler_symbol_id": "string",
-            "lang_payload": "object",
-            "artifact_type": "\"CODE\""
-          },
-          "score": "float | null"
-        }
-      },
-      "examples": {
-        "input": {
-          "rag_session_id": "rag-123",
-          "query": "which endpoint handles get user"
-        },
-        "output": {
-          "source": "app/api/users.py",
-          "content": "fastapi http \"/users/{user_id}\"",
-          "layer": "C3_ENTRYPOINTS",
-          "title": "\"/users/{user_id}\"",
-          "metadata": {
-            "entry_id": "sha256(...)",
-            "entry_type": "http",
-            "framework": "fastapi",
-            "route_or_command": "\"/users/{user_id}\"",
-            "handler_symbol_id": "sha256(...)",
-            "lang_payload": {
-              "methods": [
-                "GET"
-              ]
-            },
-            "artifact_type": "CODE"
-          },
-          "score": 0.05
-        }
-      },
-      "defaults": {
-        "retrieve_limit": 8,
-        "layer_rank": 0
-      },
-      "limitations": [
-        "Detection is decorator-string based.",
-        "No Django, Celery, RQ, or cron entrypoints were found.",
-        "Returned payload does not expose line spans."
-      ]
-    }
-  },
-  "retrieval_endpoint": {
-    "entrypoint": {
-      "file": "app/modules/rag_session/module.py",
-      "method": "internal_router.retrieve"
-    },
-    "request": {
-      "type": "dict",
-      "fields": {
-        "rag_session_id": "string | optional if project_id provided",
-        "project_id": "string | optional fallback for rag_session_id",
-        "query": "string"
-      }
-    },
-    "response": {
-      "type": "dict",
-      "fields": {
-        "items": "list[retrieval item]"
-      }
-    },
-    "defaults": {
-      "mode": "docs unless RagQueryRouter detects code hints",
-      "limit": 8,
-      "embedding_provider": "GigaChat embeddings",
-      "fallback_after_embedding_error": true,
-      "fallback_to_docs_when_code_empty": true
-    }
-  },
-  "ranking": {
-    "storage": "PostgreSQL rag_chunks + pgvector",
-    "query_repository": {
-      "class": "RagQueryRepository",
-      "file": "app/modules/rag/persistence/query_repository.py",
-      "method": "retrieve"
-    },
-    "order_by": [
-      "lexical_rank ASC",
-      "test_penalty ASC",
-      "layer_rank ASC",
-      "embedding <=> query_embedding ASC"
-    ],
-    "notes": [
-      "lexical_rank is derived from qname/symbol_id/title/path/content matching extracted query terms",
-      "test_penalty is applied only when prefer_non_tests=true",
-      "layer priority is C3 > C1 > C2 > C0 for code retrieval"
-    ]
-  }
-}

docs/architecture/llm_inventory.md

@@ -1,270 +0,0 @@
-# LLM Inventory
-
-## Provider and SDK
-
-- Provider in code: GigaChat / Sber
-- Local SDK style: custom thin HTTP client over `requests`
-- Core files:
-  - `app/modules/shared/gigachat/client.py`
-  - `app/modules/shared/gigachat/settings.py`
-  - `app/modules/shared/gigachat/token_provider.py`
-  - `app/modules/agent/llm/service.py`
-
-There is no OpenAI SDK, Azure SDK, or local model runtime in the current implementation.
-
-## Configuration
-
-Model and endpoint configuration are read from environment in `GigaChatSettings.from_env()`:
-
-- `GIGACHAT_AUTH_URL`
-  - default: `https://ngw.devices.sberbank.ru:9443/api/v2/oauth`
-- `GIGACHAT_API_URL`
-  - default: `https://gigachat.devices.sberbank.ru/api/v1`
-- `GIGACHAT_SCOPE`
-  - default: `GIGACHAT_API_PERS`
-- `GIGACHAT_TOKEN`
-  - required for auth
-- `GIGACHAT_SSL_VERIFY`
-  - default: `true`
-- `GIGACHAT_MODEL`
-  - default: `GigaChat`
-- `GIGACHAT_EMBEDDING_MODEL`
-  - default: `Embeddings`
-- `AGENT_PROMPTS_DIR`
-  - optional prompt directory override
-
-PostgreSQL config for retrieval storage is separate:
-
-- `DATABASE_URL`
-  - default: `postgresql+psycopg://agent:agent@db:5432/agent`
-
-## Default models
-
-- Chat/completions model default: `GigaChat`
-- Embedding model default: `Embeddings`
-
-## Completion payload
-
-Observed payload sent by `GigaChatClient.complete(...)`:
-
-```json
-{
-  "model": "GigaChat",
-  "messages": [
-    {"role": "system", "content": "<prompt template text>"},
-    {"role": "user", "content": "<runtime user input>"}
-  ]
-}
-```
-
-Endpoint:
-
-- `POST {GIGACHAT_API_URL}/chat/completions`
-
-Observed response handling:
-
-- reads `choices[0].message.content`
-- if no choices: returns empty string
-
-## Embeddings payload
-
-Observed payload sent by `GigaChatClient.embed(...)`:
-
-```json
-{
-  "model": "Embeddings",
-  "input": [
-    "<text1>",
-    "<text2>"
-  ]
-}
-```
-
-Endpoint:
-
-- `POST {GIGACHAT_API_URL}/embeddings`
-
-Observed response handling:
-
-- expects `data` list
-- maps each `item.embedding` to `list[float]`
-
-## Parameters
-
-### Explicitly implemented
-
-- `model`
-- `messages`
-- `input`
-- HTTP timeout:
-  - completions: `90s`
-  - embeddings: `90s`
-  - auth: `30s`
-- TLS verification flag:
-  - `verify=settings.ssl_verify`
-
-### Not implemented in payload
-
-- `temperature`
-- `top_p`
-- `max_tokens`
-- `response_format`
-- tools/function calling
-- streaming
-- seed
-- stop sequences
-
-`ASSUMPTION:` the service uses provider defaults for sampling and output length because these fields are not sent in the request payload.
-
-## Context and budget limits
-
-There is no centralized token budget manager in the current code.
-
-Observed practical limits instead:
-
-- prompt file text is loaded as-is from disk
-- user input is passed as-is
-- RAG context shaping happens outside the LLM client
-- docs indexing summary truncation:
-  - docs module catalog summary: `4000` chars
-  - docs policy text: `4000` chars
-- project QA source bundle caps:
-  - top `12` rag items
-  - top `10` file candidates
-- logging truncation only:
-  - LLM input/output logs capped at `1500` chars for logs
-
-`ASSUMPTION:` there is no explicit max-context enforcement before chat completion requests. The current system relies on upstream graph logic to keep inputs small enough.
-
-## Retry, backoff, timeout
-
-### Timeouts
-
-- auth: `30s`
-- chat completion: `90s`
-- embeddings: `90s`
-
-### Retry
-
-- Generic async retry wrapper exists in `app/modules/shared/retry_executor.py`
-- It retries only:
-  - `TimeoutError`
-  - `ConnectionError`
-  - `OSError`
-- Retry constants:
-  - `MAX_RETRIES = 5`
-  - backoff: `0.1 * attempt` seconds
-
-### Important current limitation
-
-- `GigaChatClient` raises `GigaChatError` on HTTP and request failures.
-- `RetryExecutor` does not catch `GigaChatError`.
-- Result: LLM and embeddings calls are effectively not retried by this generic retry helper unless errors are converted upstream.
-
-## Prompt formation
-
-Prompt loading is handled by `PromptLoader`:
-
-- base dir: `app/modules/agent/prompts`
-- override: `AGENT_PROMPTS_DIR`
-- file naming convention: `<prompt_name>.txt`
-
-Prompt composition model today:
-
-- system prompt:
-  - full contents of selected prompt file
-- user prompt:
-  - raw runtime input string passed by the caller
-- no separate developer prompt layer in the application payload
-
-If a prompt file is missing:
-
-- fallback system prompt: `You are a helpful assistant.`
-
-## Prompt templates present
-
-- `router_intent`
-- `general_answer`
-- `project_answer`
-- `docs_detect`
-- `docs_strategy`
-- `docs_plan_sections`
-- `docs_generation`
-- `docs_self_check`
-- `docs_execution_summary`
-- `project_edits_plan`
-- `project_edits_hunks`
-- `project_edits_self_check`
-
-## Key LLM call entrypoints
-
-### Composition roots
-
-- `app/modules/agent/module.py`
-  - builds `GigaChatSettings`
-  - builds `GigaChatTokenProvider`
-  - builds `GigaChatClient`
-  - builds `PromptLoader`
-  - builds `AgentLlmService`
-- `app/modules/rag_session/module.py`
-  - builds the same provider stack for embeddings used by RAG
-
-### Main abstraction
-
-- `AgentLlmService.generate(prompt_name, user_input, log_context=None)`
-
-### Current generate callsites
-
-- `app/modules/agent/engine/router/intent_classifier.py`
-  - `router_intent`
-- `app/modules/agent/engine/graphs/base_graph.py`
-  - `general_answer`
-- `app/modules/agent/engine/graphs/project_qa_graph.py`
-  - `project_answer`
-- `app/modules/agent/engine/graphs/docs_graph_logic.py`
-  - `docs_detect`
-  - `docs_strategy`
-  - `docs_plan_sections`
-  - `docs_generation`
-  - `docs_self_check`
-  - `docs_execution_summary`-like usage via summary step
-- `app/modules/agent/engine/graphs/project_edits_logic.py`
-  - `project_edits_plan`
-  - `project_edits_self_check`
-  - `project_edits_hunks`
-
-## Logging and observability
-
-`AgentLlmService` logs:
-
-- input:
-  - `graph llm input: context=... prompt=... user_input=...`
-- output:
-  - `graph llm output: context=... prompt=... output=...`
-
-Log truncation:
-
-- 1500 chars
-
-RAG retrieval logs separately in `RagService`, but without embedding vectors.
-
-## Integration with retrieval
-
-There are two distinct GigaChat usages:
-
-1. Chat/completion path for agent reasoning and generation
-2. Embedding path for RAG indexing and retrieval
-
-The embedding adapter is `GigaChatEmbedder`, used by:
-
-- `app/modules/rag/services/rag_service.py`
-
-## Notable limitations
-
-- Single provider coupling: chat and embeddings both depend on GigaChat-specific endpoints.
-- No model routing by scenario.
-- No tool/function calling.
-- No centralized prompt token budgeting.
-- No explicit retry for `GigaChatError`.
-- No streaming completions.
-- No structured response mode beyond prompt conventions and downstream parsing.

docs/architecture/rag_chunks_column_audit.md

@@ -1,13 +0,0 @@
-| column | used_by | safe_to_drop | notes |
-| --- | --- | --- | --- |
-| `layer` | `USED_BY_CODE_V2`, `USED_BY_DOCS_INDEXING` | no | Core selector for C0-C3 and D1-D4 queries. |
-| `title` | `USED_BY_CODE_V2`, `USED_BY_DOCS_INDEXING` | no | Used in lexical ranking and prompt evidence labels. |
-| `metadata_json` | `USED_BY_CODE_V2`, `USED_BY_DOCS_INDEXING` | no | C2/C0 graph lookups and docs metadata depend on it. |
-| `span_start`, `span_end` | `USED_BY_CODE_V2` | no | Needed for symbol-to-chunk resolution and locations. |
-| `symbol_id`, `qname`, `kind`, `lang` | `USED_BY_CODE_V2` | no | Used by code indexing, ranking, trace building, and diagnostics. |
-| `repo_id`, `commit_sha` | `USED_BY_CODE_V2`, `USED_BY_DOCS_INDEXING` | no | Used by indexing/cache and retained for provenance. |
-| `entrypoint_type`, `framework` | `USED_BY_CODE_V2` | no | Used by C3 filtering and entrypoint diagnostics. |
-| `doc_kind`, `module_id`, `section_path` | `USED_BY_DOCS_INDEXING` | no | Still written by docs indexing and covered by docs tests. |
-| `artifact_type`, `section`, `doc_version`, `owner`, `system_component`, `last_modified`, `staleness_score` | `USED_BY_DOCS_INDEXING` | no | File metadata still flows through indexing/cache; left intact for now. |
-| `rag_doc_id` | `UNUSED` | yes | Written into `rag_chunks` only; no reads in runtime/indexing code. |
-| `links_json` | `UNUSED` | yes | Stored in `rag_chunks` only; reads exist for `rag_chunk_cache`, not `rag_chunks`. |

docs/architecture/retrieval_callgraph.mmd

@@ -1,31 +0,0 @@
-flowchart TD
-    A["HTTP: POST /internal/rag/retrieve"] --> B["RagModule.internal_router.retrieve(payload)"]
-    B --> C["RagService.retrieve(rag_session_id, query)"]
-    C --> D["RagQueryRouter.resolve_mode(query)"]
-    D --> E["RagQueryRouter.layers_for_mode(mode)"]
-    C --> F["GigaChatEmbedder.embed([query])"]
-    F --> G["GigaChatClient.embed(payload)"]
-    G --> H["POST /embeddings"]
-    C --> I["RagRepository.retrieve(...)"]
-    I --> J["RagQueryRepository.retrieve(...)"]
-    J --> K["PostgreSQL rag_chunks + pgvector"]
-    K --> L["ORDER BY lexical_rank, test_penalty, layer_rank, vector distance"]
-    L --> M["rows: path/content/layer/title/metadata/span/distance"]
-    M --> N["normalize to {source, content, layer, title, metadata, score}"]
-    N --> O["response: {items: [...]}"]
-
-    C --> P["embedding error?"]
-    P -->|yes| Q["RagRepository.fallback_chunks(...)"]
-    Q --> R["latest rows by id DESC"]
-    R --> N
-
-    C --> S["no rows and mode != docs?"]
-    S -->|yes| T["fallback to docs layers"]
-    T --> I
-
-    U["GraphAgentRuntime for project/qa"] --> V["ProjectQaRetrievalGraphFactory._retrieve_context"]
-    V --> C
-    V --> W["ProjectQaSupport.build_source_bundle(...)"]
-    W --> X["source_bundle"]
-    X --> Y["context_analysis"]
-    Y --> Z["answer_composition"]

docs/architecture/retrieval_inventory.md

@@ -1,457 +0,0 @@
-# Retrieval Inventory
-
-## Scope and method
-
-This document describes the retrieval and indexing pipeline as implemented in code today. The inventory is based primarily on:
-
-- `app/modules/rag/services/rag_service.py`
-- `app/modules/rag/persistence/*.py`
-- `app/modules/rag/indexing/code/**/*.py`
-- `app/modules/rag/indexing/docs/**/*.py`
-- `app/modules/rag_session/module.py`
-- `app/modules/agent/engine/graphs/project_qa_step_graphs.py`
-- `app/modules/agent/engine/orchestrator/*.py`
-
-`ASSUMPTION:` the intended layer semantics are the ones implied by code and tests, not by future architecture plans. This matters because only `C0` through `C3` are materially implemented today; `C4+` exist only as enum constants.
-
-## Current retrieval pipeline
-
-1. Retrieval entrypoint is `POST /internal/rag/retrieve` in `app/modules/rag_session/module.py`.
-2. The endpoint calls `RagService.retrieve(rag_session_id, query)`.
-3. `RagQueryRouter` chooses `docs` or `code` mode from the raw query text.
-4. `RagService` computes a single embedding for the full query via `GigaChatEmbedder`.
-5. `RagQueryRepository.retrieve(...)` runs one SQL query against `rag_chunks` in PostgreSQL with `pgvector`.
-6. Ranking order is:
-   - lexical rank
-   - test-file penalty
-   - layer rank
-   - vector distance `embedding <=> query_embedding`
-7. Response items are normalized to `{source, content, layer, title, metadata, score}`.
-8. If embeddings fail, retrieval falls back to latest chunks from the same layers.
-9. If code retrieval returns nothing, service falls back to docs layers.
-
-## Storage and indices
-
-- Primary store: PostgreSQL from `DATABASE_URL`, configured in `app/modules/shared/db.py`.
-- Vector extension: `CREATE EXTENSION IF NOT EXISTS vector` in `app/modules/rag/persistence/schema_repository.py`.
-- Primary table: `rag_chunks`.
-- Cache tables:
-  - `rag_blob_cache`
-  - `rag_chunk_cache`
-  - `rag_session_chunk_map`
-- SQL indexes currently created:
-  - `(rag_session_id)`
-  - `(rag_session_id, layer)`
-  - `(rag_session_id, layer, path)`
-  - `(qname)`
-  - `(symbol_id)`
-  - `(module_id)`
-  - `(doc_kind)`
-  - `(entrypoint_type, framework)`
-
-`ASSUMPTION:` there is no explicit ANN index for the vector column in schema code. The code creates general SQL indexes, but no `ivfflat`/`hnsw` index is defined here.
-
-## Layer: C0_SOURCE_CHUNKS
-
-### Implementation
-
-- Produced by `CodeIndexingPipeline.index_file(...)` in `app/modules/rag/indexing/code/pipeline.py`.
-- Chunking logic: `CodeTextChunker.chunk(...)` in `app/modules/rag/indexing/code/code_text/chunker.py`.
-- Document builder: `CodeTextDocumentBuilder.build(...)` in `app/modules/rag/indexing/code/code_text/document_builder.py`.
-- Persisted via `RagDocumentRepository.insert_documents(...)` into `rag_chunks`.
-
-### Input contract
-
-This is an indexing layer, not a direct public retriever. The observed upstream indexing input is a file dict with at least:
-
-- required:
-  - `path: str`
-  - `content: str`
-- optional:
-  - `commit_sha: str | None`
-  - `content_hash: str`
-  - metadata fields copied through by `RagService._document_metadata(...)`
-
-For retrieval, the layer is queried only indirectly through:
-
-- `rag_session_id: str`
-- `query: str`
-- inferred mode/layers from `RagQueryRouter`
-- fixed `limit=8`
-
-### Output contract
-
-Stored document shape:
-
-- top-level:
-  - `layer = "C0_SOURCE_CHUNKS"`
-  - `lang = "python"`
-  - `source.repo_id`
-  - `source.commit_sha`
-  - `source.path`
-  - `title`
-  - `text`
-  - `span.start_line`
-  - `span.end_line`
-  - `embedding`
-- metadata:
-  - `chunk_index`
-  - `chunk_type`: `symbol_block` or `window`
-  - `module_or_unit`
-  - `artifact_type = "CODE"`
-  - plus file-level metadata injected by `RagService`
-
-Returned retrieval item shape:
-
-- `source`
-- `content`
-- `layer`
-- `title`
-- `metadata`
-- `score`
-
-No `line_start` / `line_end` are returned to the caller directly; they remain in DB columns `span_start` / `span_end` and are only used in logs.
-
-### Defaults & limits
-
-- AST chunking prefers one chunk per top-level class/function/async function.
-- Fallback window chunking:
-  - `size = 80` lines
-  - `overlap = 15` lines
-- Global retrieval limit from `RagService.retrieve(...)`: `8`
-- Embedding batch size from env:
-  - `RAG_EMBED_BATCH_SIZE`
-  - default `16`
-
-### Known issues
-
-- Nested methods/functions are not emitted as C0 chunks unless represented inside a selected top-level block.
-- Returned API payload omits line spans even though storage has them.
-- No direct filter by path, namespace, symbol, or `top_k` is exposed through the current endpoint.
-
-## Layer: C1_SYMBOL_CATALOG
-
-### Implementation
-
-- Symbol extraction: `SymbolExtractor.extract(...)` in `app/modules/rag/indexing/code/symbols/extractor.py`.
-- AST parsing: `PythonAstParser.parse_module(...)`.
-- Document builder: `SymbolDocumentBuilder.build(...)`.
-- Retrieval reads rows from `rag_chunks`; there is no dedicated symbol table.
-
-### Input contract
-
-Indexing input is the same per-file payload as C0.
-
-Observed symbol extraction source:
-
-- Python AST only
-- supported symbol kinds:
-  - `class`
-  - `function`
-  - `method`
-  - `const` for top-level imports/import aliases
-
-Retrieval input is still the generic text query endpoint. Query terms are enriched by `extract_query_terms(...)`:
-
-- extracts identifier-like tokens from query text
-- normalizes camelCase/PascalCase to snake_case
-- adds special intent terms for management/control-related queries
-- max observed query terms: `6`
-
-### Output contract
-
-Stored document shape:
-
-- top-level:
-  - `layer = "C1_SYMBOL_CATALOG"`
-  - `title = qname`
-  - `text = "<kind> <qname>\n<signature>\n<docstring?>"`
-  - `span.start_line`
-  - `span.end_line`
-- metadata:
-  - `symbol_id`
-  - `qname`
-  - `kind`
-  - `signature`
-  - `decorators_or_annotations`
-  - `docstring_or_javadoc`
-  - `parent_symbol_id`
-  - `package_or_module`
-  - `is_entry_candidate`
-  - `lang_payload`
-  - `artifact_type = "CODE"`
-
-Observed `lang_payload` variants:
-
-- class:
-  - `bases`
-- function/method:
-  - `async`
-- import alias:
-  - `imported_from`
-  - `import_alias`
-
-### Defaults & limits
-
-- Only Python source files are indexed into C-layers.
-- Import and import-from declarations are materialized as `const` symbols only at module top level.
-- Retrieval ranking gives C1 priority rank `1`, after C3 and before C2/C0.
-
-### Known issues
-
-- No explicit visibility/public-private model.
-- `parent_symbol_id` currently stores the parent qname string from the stack, not the parent symbol hash. This is an observed implementation detail.
-- Cross-file symbol resolution is not implemented; `dst_symbol_id` in edges resolves only against symbols extracted from the same file.
-
-## Layer: C2_DEPENDENCY_GRAPH
-
-### Implementation
-
-- Edge extraction: `EdgeExtractor.extract(...)` in `app/modules/rag/indexing/code/edges/extractor.py`.
-- Document builder: `EdgeDocumentBuilder.build(...)`.
-- Built during `CodeIndexingPipeline.index_file(...)`.
-
-### Input contract
-
-Indexing input is the same per-file source payload as C0/C1.
-
-Graph construction method:
-
-- static analysis only
-- Python AST walk only
-- no runtime tracing
-- no tree-sitter
-
-Observed edge types:
-
-- `calls`
-- `imports`
-- `inherits`
-
-### Output contract
-
-Stored document shape:
-
-- top-level:
-  - `layer = "C2_DEPENDENCY_GRAPH"`
-  - `title = "<src_qname>:<edge_type>"`
-  - `text = "<src_qname> <edge_type> <dst>"`
-  - `span.start_line`
-  - `span.end_line`
-  - `links` contains one evidence link of type `EDGE`
-- metadata:
-  - `edge_id`
-  - `edge_type`
-  - `src_symbol_id`
-  - `src_qname`
-  - `dst_symbol_id`
-  - `dst_ref`
-  - `resolution`: `resolved` or `partial`
-  - `lang_payload`
-  - `artifact_type = "CODE"`
-
-Observed `lang_payload` usage:
-
-- for calls: may include `callsite_kind = "function_call"`
-
-### Defaults & limits
-
-- Edge extraction is per-file only.
-- `imports` edges are emitted only while visiting a class/function scope; top-level imports do not become C2 edges.
-- Layer rank in retrieval SQL: `2`
-
-### Known issues
-
-- There is no traversal API, graph repository, or query language over C2. Retrieval only treats edges as text/vector rows in `rag_chunks`.
-- Destination resolution is local to the file-level qname map.
-- Top-level module import relationships are incompletely represented because `visit_Import` / `visit_ImportFrom` skip when there is no current scope.
-
-## Layer: C3_ENTRYPOINTS
-
-### Implementation
-
-- Detection registry: `EntrypointDetectorRegistry.detect_all(...)`.
-- Detectors:
-  - `FastApiEntrypointDetector`
-  - `FlaskEntrypointDetector`
-  - `TyperClickEntrypointDetector`
-- Document builder: `EntrypointDocumentBuilder.build(...)`.
-
-### Input contract
-
-Indexing input is the same per-file source payload as other C-layers.
-
-Detected entrypoint families today:
-
-- HTTP:
-  - FastAPI decorators such as `.get`, `.post`, `.put`, `.patch`, `.delete`, `.route`
-  - Flask `.route`
-- CLI:
-  - Typer/Click `.command`
-  - Typer/Click `.callback`
-
-Not detected:
-
-- Django routes
-- Celery tasks
-- RQ jobs
-- cron jobs / scheduler entries
-
-### Output contract
-
-Stored document shape:
-
-- top-level:
-  - `layer = "C3_ENTRYPOINTS"`
-  - `title = route_or_command`
-  - `text = "<framework> <entry_type> <route_or_command>"`
-  - `span.start_line`
-  - `span.end_line`
-  - `links` contains one evidence link of type `CODE_SPAN`
-- metadata:
-  - `entry_id`
-  - `entry_type`: observed `http` or `cli`
-  - `framework`: observed `fastapi`, `flask`, `typer`, `click`
-  - `route_or_command`
-  - `handler_symbol_id`
-  - `lang_payload`
-  - `artifact_type = "CODE"`
-
-FastAPI-specific observed payload:
-
-- `lang_payload.methods = [HTTP_METHOD]` for `.get/.post/...`
-
-### Defaults & limits
-
-- Retrieval layer rank: `0` highest among code layers.
-- Entrypoint mapping is handler-symbol centric:
-  - decorator match -> symbol -> `handler_symbol_id`
-  - physical location comes from symbol span
-
-### Known issues
-
-- Route parsing is string-based from decorator text, not semantic AST argument parsing.
-- No dedicated entrypoint tags beyond `entry_type`, `framework`, and raw decorator-derived payload.
-- Background jobs and non-decorator entrypoints are not indexed.
-
-## Dependency graph / trace current state
-
-### Exists or stub?
-
-- C2 exists and is populated.
-- It is not a stub.
-- It is also not a full-project dependency graph service; it is a set of per-edge documents stored in `rag_chunks`.
-
-### How the graph is built
-
-- static Python AST analysis
-- no runtime instrumentation
-- no import graph resolver across modules
-- no tree-sitter
-
-### Edge types in data
-
-- `calls`
-- `imports`
-- `inherits`
-
-### Traversal API
-
-- No traversal API was found in `app/modules/rag/*` or `app/modules/agent/*`.
-- No method accepts graph traversal parameters such as depth, start node, edge filters, or BFS/DFS strategy.
-- Current access path is only retrieval over indexed edge documents.
-
-## Entrypoints current state
-
-### Implemented extraction
-
-- HTTP routes:
-  - FastAPI
-  - Flask
-- CLI:
-  - Typer
-  - Click
-
-### Mapping model
-
-- `entrypoint -> handler_symbol_id -> symbol span/path`
-- The entrypoint record itself stores:
-  - framework
-  - entry type
-  - raw route/command string
-  - handler symbol id
-
-### Tags/types
-
-- `entry_type` is the main normalized tag.
-- Observed values: `http`, `cli`.
-- `framework` is the second discriminator.
-- There are no richer endpoint taxonomies such as `job`, `worker`, `webhook`, `scheduler`.
-
-## Defaults and operational limits
-
-- Query mode default: `docs`
-- Code mode is enabled by keyword heuristics in `RagQueryRouter`
-- Retrieval hard limit: `8`
-- Fallback limit: `8`
-- Query term extraction limit: `6`
-- Ranked source bundle for project QA:
-  - top `12` RAG items
-  - top `10` file candidates
-- No exposed `namespace`, `path_prefixes`, `top_k`, `max_chars`, `max_chunks`, `max_depth` in the public/internal retrieval endpoint
-
-`ASSUMPTION:` the absence of these controls in endpoint and service signatures means they are not part of the current supported contract, even though `RagQueryRepository.retrieve(...)` has an internal `path_prefixes` parameter.
-
-## Known cross-cutting issues
-
-- Retrieval contract is effectively text-only at API level; structured retrieval exists only as internal SQL parameters.
-- Response payload drops explicit line spans even though spans are stored.
-- Vector retrieval is coupled to a single provider-specific embedder.
-- Docs mode is the default, so code retrieval depends on heuristic query phrasing unless the project/qa graph prepends `по коду`.
-- There is no separate retrieval contract per layer exposed over API; all layer selection is implicit.
-
-## Where to plug ExplainPack pipeline
-
-### Option 1: replace or extend `project_qa/context_analysis`
-
-- Code location:
-  - `app/modules/agent/engine/graphs/project_qa_step_graphs.py`
-- Why:
-  - retrieval is already complete at this step
-  - input bundle already contains ranked `rag_items` and `file_candidates`
-  - output is already a structured `analysis_brief`
-- Risk:
-  - low
-  - minimal invasion if ExplainPack consumes `source_bundle` and emits the same `analysis_brief` shape
-
-### Option 2: insert a new orchestrator step between `context_retrieval` and `context_analysis`
-
-- Code location:
-  - `app/modules/agent/engine/orchestrator/template_registry.py`
-  - `app/modules/agent/engine/orchestrator/step_registry.py`
-- Why:
-  - preserves current retrieval behavior
-  - makes ExplainPack an explicit pipeline stage with its own artifact
-  - cleanest for observability and future A/B migration
-- Risk:
-  - low to medium
-  - requires one new artifact contract and one extra orchestration step, but no change to retrieval storage
-
-### Option 3: introduce ExplainPack inside `ExplainActions.extract_logic`
-
-- Code location:
-  - `app/modules/agent/engine/orchestrator/actions/explain_actions.py`
-- Why:
-  - useful if ExplainPack is meant only for explain-style scenarios
-  - keeps general project QA untouched
-- Risk:
-  - medium
-  - narrower integration point; may create duplicate reasoning logic separate from project QA analysis path
-
-## Bottom line
-
-- C0-C3 are implemented and persisted in one physical store: `rag_chunks`.
-- Retrieval is a hybrid SQL ranking over lexical heuristics plus pgvector distance.
-- C2 exists, but only as retrievable edge documents, not as a traversable graph subsystem.
-- C3 covers FastAPI/Flask/Typer/Click only.
-- The least invasive ExplainPack integration point is after retrieval and before answer composition, preferably as a new explicit orchestrator artifact or as a replacement for `context_analysis`.

docs/documentation/rag/api-rag-session-changes.md

@@ -0,0 +1,168 @@
+---
+id: api-rag-session-changes
+title: Применение изменений к RAG-сессии
+doc_type: api_method
+domain: rag
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - arch-rag-package
+  - logic-rag-indexing
+  - entity-rag-session
+  - entity-rag-index-job
+related_code:
+  - src/app/modules/rag/module.py
+  - src/app/schemas/rag_sessions.py
+  - src/app/schemas/indexing.py
+entities:
+  - RagSession
+  - IndexJob
+tags:
+  - rag
+  - api
+  - changes
+  - incremental-indexing
+---
+# Применение изменений к RAG-сессии
+
+## Summary
+- Purpose: поставить incremental indexing для уже существующей `RagSession`.
+- Actor: внешний клиент модуля RAG.
+- Trigger: частичное обновление индекса после изменения файлов.
+- Endpoint: `POST /api/rag/sessions/{rag_session_id}/changes`
+- Main entities: `RagSession`, `IndexJob`.
+- Main logic: проверка существования сессии, создание change job, асинхронная обработка `upsert`/`delete`.
+- Main errors: `not_found` для отсутствующей сессии, `422` для некорректного payload.
+- Source of truth: `src/app/modules/rag/module.py`, `src/app/schemas/rag_sessions.py`.
+
+## Назначение
+
+Метод позволяет обновить индекс без полной переиндексации проекта. Он принимает только изменённые файлы и операции удаления.
+
+## Контекст
+
+Endpoint относится к новому API с явной работой через `rag_session_id`. В отличие от legacy `/api/index/changes`, он не создаёт сессию молча и требует, чтобы она уже существовала.
+
+## Технический use case
+
+### Основной сценарий
+
+1. Клиент передаёт `rag_session_id` в path и список `changed_files` в body.
+2. Endpoint проверяет наличие сессии через `RagSessionStore.get`.
+3. При успехе `IndexingOrchestrator.enqueue_changes` создаёт новую job и запускает фоновое применение изменений.
+4. API возвращает `index_job_id` и стартовый статус.
+
+### Альтернативные ветки
+
+- Если `rag_session_id` не найдена, endpoint бросает `AppError("not_found", ...)`.
+- Для `op=delete` в последующей логике происходит удаление документов по пути без повторной генерации embeddings.
+
+## Функциональные требования
+
+### Request validation
+- Path parameter `rag_session_id` обязателен.
+- `changed_files` обязателен и состоит из элементов `ChangedFile`.
+- Для каждого элемента обязательны `op` и `path`.
+- `op` допускает только `upsert` или `delete`.
+
+### Processing rules
+- Сессия должна существовать до постановки change job.
+- Каждый вызов создаёт новый `IndexJob`.
+- Фактическое применение изменений выполняется асинхронно.
+
+### State changes
+- В `rag_index_jobs` появляется новая задача.
+- Сам индекс меняется позже, внутри `RagService.index_changes`.
+
+### Side effects
+- Публикация job events.
+- Удаление документов по `delete_paths` и upsert новых документов в фоне.
+
+## Contract
+
+### Endpoint
+- Method: `POST`
+- Path: `/api/rag/sessions/{rag_session_id}/changes`
+- Auth: определяется внешним слоем приложения.
+- Idempotent: нет, повторный вызов создаёт новую job.
+- Timeout: короткий, endpoint не дожидается завершения индексации.
+- Retry: только если клиент готов к созданию дополнительной job.
+
+### Request
+| Field | Type | Required | Constraints | Description |
+|------|------|----------|-------------|-------------|
+| `rag_session_id` | `string` | yes | path param, non-empty | идентификатор существующей RAG-сессии |
+| `changed_files` | `array<ChangedFile>` | yes | схема каждого элемента обязательна | изменения файлов |
+| `changed_files[].op` | `enum` | yes | `upsert` or `delete` | тип операции |
+| `changed_files[].path` | `string` | yes | `min_length=1` | путь файла |
+| `changed_files[].content` | `string \| null` | no | нужен для `upsert` | содержимое файла |
+| `changed_files[].content_hash` | `string \| null` | no | повышает cache reuse | hash содержимого |
+
+### Response
+| Field | Type | Description |
+|------|------|-------------|
+| `index_job_id` | `string` | идентификатор фоновой задачи |
+| `status` | `string` | стартовый статус задачи |
+
+### External contract refs
+- OpenAPI: формируется FastAPI по `response_model=IndexJobQueuedResponse`.
+- Schema: `RagSessionChangesRequest`, `ChangedFile`, `IndexJobQueuedResponse`.
+- DTO / serializer: `src/app/schemas/rag_sessions.py`, `src/app/schemas/indexing.py`.
+- Additional refs: `logic-rag-indexing`.
+
+## Errors
+
+| error_id | http_code | when | client_behavior | retry |
+|----------|-----------|------|-----------------|-------|
+| `not_found` | `404` | `rag_session_id` отсутствует | создать новую сессию или исправить id | no |
+| `validation_error` | `422` | нарушена схема request | исправить payload | no |
+
+## Нефункциональные требования
+
+### Security
+- Метод доверяет внешнему слою авторизации.
+
+### Observability
+- Logs: прямое логирование endpoint отсутствует.
+- Metrics: нет отдельной метрики на уровне метода.
+- Traces: отсутствуют.
+- Audit: каждая операция материализуется в `IndexJob`.
+
+### Reliability
+- Проверка существования сессии защищает от случайной записи в неинициализированный scope.
+- Ошибки индексации доступны через job status и SSE events.
+
+### Performance
+- Быстрый ответ за счёт фонового выполнения.
+
+## Связанные блоки логики
+- `logic-rag-indexing`
+
+## Связанные сущности
+- `RagSession`
+- `IndexJob`
+
+## Связанный код
+
+### Files
+- `src/app/modules/rag/module.py`
+- `src/app/schemas/rag_sessions.py`
+- `src/app/schemas/indexing.py`
+
+### Symbols
+- `RagModule.public_router.rag_session_changes`
+- `RagSessionStore.get`
+- `IndexingOrchestrator.enqueue_changes`
+
+## Связанные документы
+- `arch-rag-package`
+- `logic-rag-indexing`
+- `entity-rag-session`
+- `entity-rag-index-job`
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+| 2026-03-13 | code | Задокументирован публичный endpoint incremental indexing для существующей сессии. |

docs/documentation/rag/api-rag-session-create.md

@@ -0,0 +1,166 @@
+---
+id: api-rag-session-create
+title: Создание RAG-сессии и запуск snapshot-индексации
+doc_type: api_method
+domain: rag
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - arch-rag-package
+  - logic-rag-indexing
+  - entity-rag-session
+  - entity-rag-index-job
+related_code:
+  - src/app/modules/rag/module.py
+  - src/app/schemas/rag_sessions.py
+  - src/app/schemas/indexing.py
+entities:
+  - RagSession
+  - IndexJob
+tags:
+  - rag
+  - api
+  - session
+  - snapshot
+---
+# Создание RAG-сессии и запуск snapshot-индексации
+
+## Summary
+- Purpose: создать новую `RagSession` и асинхронно поставить полную индексацию snapshot-файлов.
+- Actor: внешний клиент модуля RAG.
+- Trigger: первичная загрузка файлов проекта в индекс.
+- Endpoint: `POST /api/rag/sessions`
+- Main entities: `RagSession`, `IndexJob`.
+- Main logic: создание UUID-сессии, постановка snapshot job, возврат идентификаторов сессии и job.
+- Main errors: в коде endpoint нет собственной бизнес-валидации сверх pydantic; ошибки индексации проявляются позже в job status.
+- Source of truth: `src/app/modules/rag/module.py`, `src/app/schemas/rag_sessions.py`.
+
+## Назначение
+
+Метод открывает новую RAG-сессию и запускает первичную индексацию файлов. Он используется как основной публичный вход для нового API пакета `rag`.
+
+## Контекст
+
+В отличие от legacy `/api/index/snapshot`, этот endpoint всегда создаёт новый `rag_session_id`, что позволяет независимо хранить несколько снимков одного проекта.
+
+## Технический use case
+
+### Основной сценарий
+
+1. Клиент передаёт `project_id` и массив `files`.
+2. `RagSessionStore.create` создаёт новую запись в `rag_sessions`.
+3. `IndexingOrchestrator.enqueue_snapshot` создаёт `IndexJob` и запускает фоновую обработку.
+4. API сразу возвращает `rag_session_id`, `index_job_id` и стартовый статус.
+
+### Альтернативные ветки
+
+- Если часть файлов не подлежит индексации, они будут отфильтрованы уже внутри indexing pipeline, а не на этапе ответа API.
+- Ошибки индексации не меняют синхронный ответ create endpoint, а отражаются в последующем статусе job.
+
+## Функциональные требования
+
+### Request validation
+- `project_id` обязателен и не может быть пустым.
+- `files` передаются списком объектов `FileSnapshot`.
+- Для каждого файла обязательны `path`, `content`, `content_hash`.
+
+### Processing rules
+- На каждый вызов создаётся новая `RagSession`.
+- Snapshot job создаётся сразу после сохранения сессии.
+- Ответ не ждёт завершения индексации.
+
+### State changes
+- В `rag_sessions` появляется новая запись.
+- В `rag_index_jobs` появляется новая запись в статусе `queued`.
+
+### Side effects
+- Запуск фоновой `asyncio` task.
+- Последующая публикация progress events в EventBus.
+
+## Contract
+
+### Endpoint
+- Method: `POST`
+- Path: `/api/rag/sessions`
+- Auth: определяется внешним слоем приложения, внутри endpoint не задана.
+- Idempotent: нет.
+- Timeout: короткий, так как endpoint не ждёт индексацию.
+- Retry: допустим только на стороне клиента с пониманием, что будет создана новая сессия.
+
+### Request
+| Field | Type | Required | Constraints | Description |
+|------|------|----------|-------------|-------------|
+| `project_id` | `string` | yes | `min_length=1` | идентификатор проекта |
+| `files` | `array<FileSnapshot>` | yes | может быть пустым, но схема обязана соблюдаться | snapshot файлов для первичной индексации |
+| `files[].path` | `string` | yes | `min_length=1` | путь файла |
+| `files[].content` | `string` | yes | без дополнительных ограничений | содержимое файла |
+| `files[].content_hash` | `string` | yes | `min_length=1` | hash содержимого для cache reuse |
+
+### Response
+| Field | Type | Description |
+|------|------|-------------|
+| `rag_session_id` | `string` | идентификатор созданной сессии |
+| `index_job_id` | `string` | идентификатор фоновой задачи индексации |
+| `status` | `IndexJobStatus` | стартовый статус задачи, обычно `queued` |
+
+### External contract refs
+- OpenAPI: формируется FastAPI по `response_model=RagSessionCreateResponse`.
+- Schema: `RagSessionCreateRequest`, `RagSessionCreateResponse`.
+- DTO / serializer: `src/app/schemas/rag_sessions.py`, `src/app/schemas/indexing.py`.
+- Additional refs: `logic-rag-indexing`.
+
+## Errors
+
+| error_id | http_code | when | client_behavior | retry |
+|----------|-----------|------|-----------------|-------|
+| `validation_error` | `422` | нарушена pydantic-схема request | исправить payload | no |
+
+## Нефункциональные требования
+
+### Security
+- Авторизация и аутентификация находятся вне этого метода.
+
+### Observability
+- Logs: прямое логирование в endpoint отсутствует.
+- Metrics: отдельные API-метрики не выделены.
+- Traces: отсутствуют.
+- Audit: факт вызова материализуется через `RagSession` и `IndexJob`.
+
+### Reliability
+- Даже при дальнейшей ошибке индексации клиент может получить статус через job endpoint.
+- Фоновая задача создаётся немедленно после ответа.
+
+### Performance
+- Время ответа не зависит от размера snapshot, кроме времени сериализации request.
+
+## Связанные блоки логики
+- `logic-rag-indexing`
+
+## Связанные сущности
+- `RagSession`
+- `IndexJob`
+
+## Связанный код
+
+### Files
+- `src/app/modules/rag/module.py`
+- `src/app/schemas/rag_sessions.py`
+- `src/app/schemas/indexing.py`
+
+### Symbols
+- `RagModule.public_router.create_rag_session`
+- `RagSessionStore.create`
+- `IndexingOrchestrator.enqueue_snapshot`
+
+## Связанные документы
+- `arch-rag-package`
+- `logic-rag-indexing`
+- `entity-rag-session`
+- `entity-rag-index-job`
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+| 2026-03-13 | code | Задокументирован публичный endpoint создания RAG-сессии. |

docs/documentation/rag/api-rag-session-job.md

@@ -0,0 +1,166 @@
+---
+id: api-rag-session-job
+title: Получение статуса и событий задачи индексации
+doc_type: api_method
+domain: rag
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - arch-rag-package
+  - entity-rag-session
+  - entity-rag-index-job
+related_code:
+  - src/app/modules/rag/module.py
+  - src/app/modules/rag/job_store.py
+  - src/app/schemas/rag_sessions.py
+entities:
+  - RagSession
+  - IndexJob
+tags:
+  - rag
+  - api
+  - job-status
+  - sse
+---
+# Получение статуса и событий задачи индексации
+
+## Summary
+- Purpose: отдать текущее состояние job и поток событий её выполнения в рамках конкретной `RagSession`.
+- Actor: внешний клиент модуля RAG.
+- Trigger: polling или live-monitoring после запуска snapshot/change indexing.
+- Endpoint: `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}` и `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events`
+- Main entities: `RagSession`, `IndexJob`.
+- Main logic: чтение job по id, проверка принадлежности сессии, возврат status payload или SSE stream.
+- Main errors: `not_found` при отсутствии job или несовпадении `rag_session_id`.
+- Source of truth: `src/app/modules/rag/module.py`, `src/app/modules/rag/job_store.py`.
+
+## Назначение
+
+Документ описывает два связанных метода наблюдения: синхронный status endpoint и потоковый SSE endpoint. Оба работают поверх одной сущности `IndexJob`.
+
+## Контекст
+
+Create и changes endpoints возвращают только стартовый статус задачи, поэтому клиенту нужны отдельные методы для отслеживания выполнения. SSE-поток даёт live progress, а status endpoint нужен для простого polling.
+
+## Технический use case
+
+### Основной сценарий
+
+1. Клиент вызывает status endpoint или открывает SSE stream по `index_job_id`.
+2. Endpoint читает job из `IndexJobStore`.
+3. Если job отсутствует или принадлежит другой `rag_session_id`, возвращается `not_found`.
+4. Status endpoint отдаёт снимок counters и error payload.
+5. SSE endpoint подписывается на `EventBus` c `replay=True` и транслирует `index_status`, `index_progress`, `terminal`.
+
+### Альтернативные ветки
+
+- При отсутствии новых событий SSE endpoint каждые 10 секунд отправляет `: keepalive`.
+- После события `terminal` поток завершается и отписывается от EventBus.
+
+## Функциональные требования
+
+### Request validation
+- `rag_session_id` и `index_job_id` обязательны как path parameters.
+- Job должна существовать и принадлежать переданной сессии.
+
+### Processing rules
+- Status endpoint не подписывается на события и читает только текущее состояние job.
+- SSE endpoint использует `replay=True`, чтобы клиент получил уже опубликованные события.
+- Оба метода защищают от доступа к job другой сессии.
+
+### State changes
+- Методы не меняют состояние job.
+
+### Side effects
+- SSE endpoint создаёт временную подписку на EventBus.
+- При завершении или разрыве соединения выполняется `unsubscribe`.
+
+## Contract
+
+### Endpoint
+- Method: `GET`
+- Path: `/api/rag/sessions/{rag_session_id}/jobs/{index_job_id}` и `/api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events`
+- Auth: определяется внешним слоем приложения.
+- Idempotent: да.
+- Timeout: status endpoint короткий; SSE stream долгоживущий.
+- Retry: polling можно повторять безопасно; SSE можно переподключать.
+
+### Request
+| Field | Type | Required | Constraints | Description |
+|------|------|----------|-------------|-------------|
+| `rag_session_id` | `string` | yes | path param | идентификатор сессии |
+| `index_job_id` | `string` | yes | path param | идентификатор задачи |
+
+### Response
+| Field | Type | Description |
+|------|------|-------------|
+| `rag_session_id` | `string` | идентификатор сессии, только для status endpoint |
+| `index_job_id` | `string` | идентификатор задачи |
+| `status` | `IndexJobStatus` | текущее состояние job |
+| `indexed_files` | `integer` | число успешно обработанных файлов |
+| `failed_files` | `integer` | число файлов с ошибками |
+| `cache_hit_files` | `integer` | число cache hit |
+| `cache_miss_files` | `integer` | число cache miss |
+| `error` | `object \| null` | ошибка, если job завершилась с `error` |
+
+### External contract refs
+- OpenAPI: status endpoint использует `response_model=RagSessionJobResponse`; SSE endpoint отдаёт `text/event-stream`.
+- Schema: `RagSessionJobResponse`.
+- DTO / serializer: `src/app/schemas/rag_sessions.py`.
+- Additional refs: `entity-rag-index-job`.
+
+## Errors
+
+| error_id | http_code | when | client_behavior | retry |
+|----------|-----------|------|-----------------|-------|
+| `not_found` | `404` | job отсутствует или не принадлежит переданной сессии | проверить id или создать новую задачу | no |
+
+## Нефункциональные требования
+
+### Security
+- Проверка `job.rag_session_id == rag_session_id` обязательна для обоих методов.
+
+### Observability
+- Logs: отдельные логи чтения статуса не реализованы.
+- Metrics: отсутствуют.
+- Traces: отсутствуют.
+- Audit: история job хранится в `rag_index_jobs`, поток событий в памяти EventBus.
+
+### Reliability
+- SSE heartbeat удерживает соединение активным.
+- `finally` блок гарантирует `unsubscribe`.
+
+### Performance
+- Status endpoint работает как лёгкий запрос к БД.
+- SSE stream масштабируется числом активных подписчиков и объёмом событий.
+
+## Связанные блоки логики
+- `logic-rag-indexing`
+
+## Связанные сущности
+- `RagSession`
+- `IndexJob`
+
+## Связанный код
+
+### Files
+- `src/app/modules/rag/module.py`
+- `src/app/modules/rag/job_store.py`
+- `src/app/schemas/rag_sessions.py`
+
+### Symbols
+- `RagModule.public_router.rag_session_job`
+- `RagModule.public_router.rag_session_job_events`
+- `IndexJobStore.get`
+
+## Связанные документы
+- `arch-rag-package`
+- `entity-rag-session`
+- `entity-rag-index-job`
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+| 2026-03-13 | code | Задокументированы status и SSE endpoints для наблюдения за indexing job. |

docs/documentation/rag/architecture-overview.md

@@ -0,0 +1,222 @@
+---
+
+## id: arch-rag-package
+title: Пакет RAG
+doc_type: architecture_overview
+domain: rag
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - logic-rag-indexing
+  - logic-rag-retrieval
+  - entity-rag-session
+  - entity-rag-index-job
+  - api-rag-session-create
+  - api-rag-session-changes
+  - api-rag-session-job
+related_code:
+  - src/app/modules/rag/module.py
+  - src/app/modules/rag/services/rag_service.py
+  - src/app/modules/rag/indexing_service.py
+  - src/app/modules/rag/persistence/repository.py
+  - src/app/modules/rag/persistence/schema_repository.py
+entities:
+  - RagSession
+  - IndexJob
+  - RagDocument
+tags:
+  - rag
+  - indexing
+  - retrieval
+  - architecture
+
+# Пакет RAG
+
+## Summary
+
+- Scope: модуль индексации проектных файлов, хранения RAG-слоёв и выдачи retrieval-контекста.
+- Purpose: построить индекс по документации и Python-коду и дать runtime доступ к релевантным фрагментам.
+- Main modules: `RagModule`, `RagService`, `IndexingOrchestrator`, `RagRepository`, `RepoWebhookService`.
+- Main domains: RAG-сессии, задачи индексации, документы индекса, blob-cache, retrieval.
+- Main integrations: PostgreSQL/pgvector, GigaChat embeddings, FastAPI, EventBus, story context.
+- Key entrypoints: `/api/rag/sessions`, `/api/rag/sessions/{rag_session_id}/changes`, `/api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`, `/internal/rag-repo/webhook`.
+- Key data flows: snapshot indexing, incremental reindex, retrieval из `rag_chunks`, webhook-нормализация коммитов.
+- Source of truth: код `src/app/modules/rag/*`.
+
+## Назначение
+
+Пакет `rag` отвечает за полный цикл подготовки retrieval-контекста для проекта: принимает снапшоты и изменения файлов, преобразует их в набор атомарных `RagDocument`, векторизует, сохраняет в БД и предоставляет доступ к индексированным данным другим частям системы.
+
+## Контекст
+
+Модуль используется как инфраструктурный слой для agent/runtime и смежных интеграций. На вход он принимает либо список файлов проекта, либо webhook репозитория. На выходе формирует устойчивый индекс, ассоциированный с `rag_session_id`, и статус задач индексации, пригодный для опроса и SSE-подписки.
+
+## Границы системы
+
+### In scope
+
+- Создание и хранение `RagSession`.
+- Постановка и выполнение задач snapshot/change indexing.
+- Индексация markdown-документации в слои `D1-D4`.
+- Индексация Python-кода в слои `C0-C4`.
+- Кэширование по `repo_id + blob_sha`.
+- Сохранение retrieval-документов в `rag_chunks`.
+- Выдача статуса задач и событий прогресса.
+- Нормализация webhook Gitea/Bitbucket и связывание коммитов со story.
+
+### Out of scope
+
+- Финальная генерация ответа пользователю.
+- Оркестрация LLM-диалога.
+- Управление git-репозиторием и загрузка файлов из внешних источников.
+- Политики маршрутизации intent/runtime вне собственного persistence/retrieval API.
+
+## Архитектурная схема
+
+`RagModule` собирает зависимости модуля и публикует HTTP endpoints. Для индексации он использует `RagSessionStore`, `IndexJobStore`, `IndexingOrchestrator` и `RagService`. `RagService` выбирает docs/code pipeline, обогащает документы метаданными файла, запрашивает embeddings и записывает результат через `RagRepository`. `RagRepository` агрегирует schema/session/job/document/cache/query репозитории. Отдельно `RagRepoModule` принимает repository webhooks и прокидывает нормализованный commit context в story storage и cache writer.
+
+## Основные модули
+
+
+| module                 | responsibility                                           | depends_on                                                               | key_code_refs                                   |
+| ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------- |
+| `RagModule`            | сборка зависимостей, публичный и internal API            | `RagService`, `IndexingOrchestrator`, `RagSessionStore`, `IndexJobStore` | `src/app/modules/rag/module.py`                 |
+| `RagService`           | синхронная бизнес-логика индексации файлов и cache reuse | docs/code pipeline, embedder, `RagRepository`                            | `src/app/modules/rag/services/rag_service.py`   |
+| `IndexingOrchestrator` | асинхронный job lifecycle, retry, project lock, EventBus | `IndexJobStore`, `RagIndexer`, `EventBus`, `RetryExecutor`               | `src/app/modules/rag/indexing_service.py`       |
+| `DocsIndexingPipeline` | построение слоёв документации `D1-D4`                    | classifier, chunker, document builder                                    | `src/app/modules/rag/indexing/docs/pipeline.py` |
+| `CodeIndexingPipeline` | построение слоёв кода `C0-C4`                            | AST parser, symbol/edge/entrypoint/role builders                         | `src/app/modules/rag/indexing/code/pipeline.py` |
+| `RagRepository`        | единая точка persistence и retrieval                     | schema/session/job/document/cache/query repositories                     | `src/app/modules/rag/persistence/repository.py` |
+| `RepoWebhookService`   | нормализация webhook payload и выделение story id        | story writer, cache writer                                               | `src/app/modules/rag/webhook_service.py`        |
+
+
+## Основные доменные области
+
+- RAG session как граница индекса конкретного проекта или его временного снапшота.
+- Index job как жизненный цикл асинхронной индексации и канал наблюдения за прогрессом.
+- RagDocument как атом индекса, который попадает в retrieval-хранилище и в cache.
+- Repo webhook context как источник commit metadata для story и cache.
+
+## Основные интеграции
+
+
+| integration              | direction | purpose                                             | protocol / transport               | related_docs                                                               |
+| ------------------------ | --------- | --------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------- |
+| PostgreSQL + pgvector    | outbound  | хранение документов, jobs, sessions и vector search | SQLAlchemy / SQL / pgvector        | `logic-rag-retrieval`                                                      |
+| GigaChat embeddings      | outbound  | получение embedding для batch документов            | HTTP client через `GigaChatClient` | `logic-rag-indexing`                                                       |
+| FastAPI                  | inbound   | публичный и internal API модуля                     | HTTP                               | `api-rag-session-create`, `api-rag-session-changes`, `api-rag-session-job` |
+| EventBus                 | outbound  | публикация прогресса индексации и terminal events   | in-process async events / SSE      | `api-rag-session-job`                                                      |
+| Story context repository | outbound  | запись webhook-коммитов для story                   | Python interface                   | `logic-rag-indexing`                                                       |
+
+
+## Основные потоки
+
+### Flow 1
+
+1. Клиент вызывает `POST /api/rag/sessions` с `project_id` и snapshot файлов.
+2. `RagSessionStore` создаёт `rag_session_id`, а `IndexingOrchestrator` создаёт `IndexJob`.
+3. `RagService` фильтрует файлы, переиспользует cache по `blob_sha` или строит docs/code документы заново.
+4. Документы векторизуются, записываются в `rag_chunks`, а job получает финальный статус `done` или `error`.
+
+### Flow 2
+
+1. Клиент вызывает `POST /api/rag/sessions/{rag_session_id}/changes`.
+2. `IndexingOrchestrator` сериализует обработку по `rag_session_id`.
+3. `RagService` удаляет документы по `delete_paths`, пересобирает upsert-файлы и применяет изменения к индексу.
+4. Клиент читает статус и события задачи через job endpoints.
+
+## Архитектурные решения и ограничения
+
+### Key decisions
+
+- Snapshot и incremental indexing используют один и тот же `RagService`, различаясь только стратегией записи.
+- Кэш документов привязан к `repo_id + blob_sha`, а не к `rag_session_id`, что позволяет переиспользовать embeddings между сессиями одного проекта.
+- Документация и код индексируются разными pipeline, но сохраняются в общую таблицу `rag_chunks`.
+- Асинхронность вынесена в `IndexingOrchestrator`, чтобы `RagService` оставался application-service без управления job lifecycle.
+
+### Constraints
+
+- Code indexing поддерживает только Python-файлы.
+- Docs indexing ориентирован на markdown и frontmatter YAML.
+- Deprecated endpoint `/internal/rag/retrieve` не используется для рабочего retrieval.
+- Реальное retrieval API доступно через repository/runtime adapters, а не через публичный HTTP endpoint модуля.
+
+### Risks
+
+- Ошибки embeddings или временные сетевые сбои переводят job в `error` только после исчерпания retry.
+- Полное `replace_documents` для snapshot удаляет все документы сессии перед вставкой новых.
+- Retrieval ranking завязан на SQL-эвристики по layer, lexical match и metadata, поэтому качество зависит от корректности metadata builders.
+
+## Нефункциональные аспекты
+
+### Security
+
+- Публичные endpoints не содержат собственной бизнес-авторизации внутри модуля и полагаются на внешний слой приложения.
+- Webhook provider определяется по headers/payload без явной проверки подписи в самом `RepoWebhookService`.
+
+### Reliability
+
+- Проектный `asyncio.Lock` предотвращает параллельную индексацию одной `rag_session`.
+- `RetryExecutor` повторяет временные сбои индексации.
+
+### Observability
+
+- Logs: `RagService` пишет предупреждения по cache hit/miss и skipped files.
+- Metrics: явные метрики не выделены.
+- Traces: явная трассировка не реализована.
+- Audit: job status и webhook commit binding сохраняются в БД.
+
+### Performance
+
+- Embeddings отправляются батчами с размером из `RAG_EMBED_BATCH_SIZE`.
+- Cache reuse исключает повторную векторизацию неизменённых blob.
+
+### Scalability
+
+- Индекс хранится на уровне SQL-таблиц с векторными полями и индексами по session/layer/path.
+- При росте объёма данных узким местом остаются полнотабличные delete/insert по snapshot и SQL sorting retrieval.
+
+## Связанные сущности
+
+- `RagSession`
+- `IndexJob`
+- `RagDocument`
+
+## Связанный код
+
+### Files
+
+- `src/app/modules/rag/module.py`
+- `src/app/modules/rag/services/rag_service.py`
+- `src/app/modules/rag/indexing_service.py`
+- `src/app/modules/rag/persistence/repository.py`
+- `src/app/modules/rag/persistence/schema_repository.py`
+- `src/app/modules/rag/webhook_service.py`
+
+### Symbols
+
+- `RagModule`
+- `RagRepoModule`
+- `RagService`
+- `IndexingOrchestrator`
+- `RagRepository`
+- `RepoWebhookService`
+
+## Связанные документы
+
+- `logic-rag-indexing`
+- `logic-rag-retrieval`
+- `entity-rag-session`
+- `entity-rag-index-job`
+- `api-rag-session-create`
+- `api-rag-session-changes`
+- `api-rag-session-job`
+
+## История изменений
+
+
+| Date       | Source | Changes                                                             |
+| ---------- | ------ | ------------------------------------------------------------------- |
+| 2026-03-13 | code   | Создан обзор архитектуры пакета `rag` на основе текущей реализации. |
+
+

docs/documentation/rag/entity-index-job.md

@@ -0,0 +1,154 @@
+---
+id: entity-rag-index-job
+title: Сущность IndexJob
+doc_type: domain_entity
+domain: rag
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - arch-rag-package
+  - logic-rag-indexing
+  - entity-rag-session
+  - api-rag-session-job
+related_code:
+  - src/app/modules/rag/job_store.py
+  - src/app/modules/rag/indexing_service.py
+  - src/app/modules/rag/persistence/job_repository.py
+  - src/app/modules/rag/persistence/schema_repository.py
+entities:
+  - IndexJob
+  - RagSession
+tags:
+  - rag
+  - indexing
+  - job
+  - domain-entity
+---
+# Сущность IndexJob
+
+## Summary
+- Domain: rag
+- Purpose: представить асинхронную задачу индексации и её наблюдаемый статус.
+- Entity role: operational entity для выполнения snapshot/change indexing.
+- Main attributes: `index_job_id`, `rag_session_id`, `status`, `indexed_files`, `failed_files`, `cache_hit_files`, `cache_miss_files`, `error`.
+- Lifecycle: `queued -> running -> done|error`.
+- Invariants: job всегда принадлежит одной `RagSession`, статус хранится как enum `IndexJobStatus`.
+- Related APIs: создание job косвенно через session endpoints, чтение через job status endpoint и SSE endpoint.
+- Related logic: `IndexingOrchestrator`, retry, EventBus publishing.
+- Source of truth: `src/app/modules/rag/job_store.py`, `src/app/modules/rag/indexing_service.py`.
+
+## Назначение
+
+`IndexJob` хранит технический прогресс и итог выполнения индексации. Он нужен, чтобы API модуля мог вернуть результат не синхронно, а через опрос статуса и подписку на события.
+
+## Контекст
+
+Job создаётся на каждую snapshot- или changes-операцию. Сервис индексации обновляет его counters и публикует события прогресса в EventBus под ключом `index_job_id`.
+
+## Роль в доменной модели
+
+Это операционная сущность, которая связывает пользовательский запрос на индексацию с фактическим процессом обработки файлов. Она не хранит сам индекс, но управляет прозрачностью выполнения и ошибками.
+
+## Атрибуты
+
+| attribute | type | required | description | constraints |
+|-----------|------|----------|-------------|-------------|
+| `index_job_id` | `str` | yes | уникальный идентификатор задачи | primary key, non-empty |
+| `rag_session_id` | `str` | yes | ссылка на целевую RAG-сессию | non-empty |
+| `status` | `IndexJobStatus` | yes | текущее состояние задачи | `queued`, `running`, `done`, `error` |
+| `indexed_files` | `int` | yes | число успешно обработанных файлов | `>= 0` |
+| `failed_files` | `int` | yes | число файлов с ошибками | `>= 0` |
+| `cache_hit_files` | `int` | yes | число файлов, обслуженных из cache | `>= 0` |
+| `cache_miss_files` | `int` | yes | число файлов, потребовавших embeddings | `>= 0` |
+| `error` | `ErrorPayload \| None` | no | информация о необработанной временной ошибке после retry | optional |
+
+## Состояния и жизненный цикл
+
+### Основные состояния
+- `queued`
+- `running`
+- `done`
+- `error`
+
+### Переходы состояний
+1. `IndexJobStore.create` создаёт job в состоянии `queued`.
+2. `IndexingOrchestrator._run_with_project_lock` переводит job в `running`.
+3. Успешная индексация переводит job в `done` и заполняет counters.
+4. Ошибка после исчерпания retry переводит job в `error` и заполняет `ErrorPayload`.
+
+## Инварианты и ограничения
+
+- Job не мигрирует между `rag_session_id`.
+- Финальные counters сохраняются в БД перед публикацией terminal event.
+- Ошибки уровня `TimeoutError`, `ConnectionError`, `OSError` считаются временными и оборачиваются в `index_retry_exhausted` только после retry exhaustion.
+
+## Связи с другими сущностями
+
+| entity | relation | description |
+|--------|----------|-------------|
+| `RagSession` | many-to-one | каждая задача относится к одной сессии |
+| `RagDocument` | indirect | job обновляет набор документов сессии, но не владеет ими напрямую |
+
+## Использование в системе
+
+### Related API
+- `POST /api/rag/sessions`
+- `POST /api/rag/sessions/{rag_session_id}/changes`
+- `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`
+- `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events`
+
+### Related UI
+- Прямого UI в репозитории не обнаружено.
+
+### Related logic
+- `logic-rag-indexing`
+
+### Related integrations
+- EventBus SSE stream
+- PostgreSQL таблица `rag_index_jobs`
+
+## Функциональные требования
+
+- Job должна создаваться до запуска фоновой задачи.
+- Публичный API обязан проверять принадлежность job указанной `rag_session_id`.
+- Progress events должны публиковаться в формате, достаточном для фронта или внешнего клиента.
+
+## Нефункциональные требования
+
+### Audit / history
+- `created_at` и `updated_at` сохраняются в таблице `rag_index_jobs`.
+
+### Security
+- Доступ к job опирается на проверку связи `job.rag_session_id == requested rag_session_id`.
+
+### Observability
+- SSE stream отдаёт `index_status`, `index_progress`, `terminal`.
+
+## Связанный код
+
+### Files
+- `src/app/modules/rag/job_store.py`
+- `src/app/modules/rag/indexing_service.py`
+- `src/app/modules/rag/persistence/job_repository.py`
+- `src/app/modules/rag/persistence/schema_repository.py`
+
+### Symbols
+- `IndexJob`
+- `IndexJobStore.create`
+- `IndexJobStore.get`
+- `IndexJobStore.save`
+- `IndexingOrchestrator._run_with_project_lock`
+
+## Связанные документы
+
+- `arch-rag-package`
+- `logic-rag-indexing`
+- `entity-rag-session`
+- `api-rag-session-job`
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+| 2026-03-13 | code | Добавлено описание lifecycle и контракта сущности `IndexJob`. |

docs/documentation/rag/entity-rag-session.md

@@ -0,0 +1,143 @@
+---
+id: entity-rag-session
+title: Сущность RagSession
+doc_type: domain_entity
+domain: rag
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - arch-rag-package
+  - logic-rag-indexing
+  - api-rag-session-create
+  - api-rag-session-changes
+  - api-rag-session-job
+related_code:
+  - src/app/modules/rag/session_store.py
+  - src/app/modules/rag/persistence/session_repository.py
+  - src/app/modules/rag/persistence/schema_repository.py
+entities:
+  - RagSession
+tags:
+  - rag
+  - session
+  - domain-entity
+---
+# Сущность RagSession
+
+## Summary
+- Domain: rag
+- Purpose: связать индекс и связанные job с конкретным проектом или его рабочим снимком.
+- Entity role: корневая сущность области RAG indexing/retrieval.
+- Main attributes: `rag_session_id`, `project_id`, `created_at`.
+- Lifecycle: создаётся до первой индексации и используется как scope всех retrieval-запросов.
+- Invariants: `rag_session_id` уникален, `project_id` обязателен.
+- Related APIs: `POST /api/rag/sessions`, `POST /api/rag/sessions/{rag_session_id}/changes`, `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`.
+- Related logic: snapshot indexing, change indexing, retrieval filtering.
+- Source of truth: `src/app/modules/rag/session_store.py`, таблица `rag_sessions`.
+
+## Назначение
+
+`RagSession` определяет границу индекса для проекта. Все документы, задачи и retrieval-запросы внутри `rag` привязаны к этой сущности.
+
+## Контекст
+
+Сессия используется и в новом API с UUID, и в legacy/internal режиме, где `project_id` может совпадать с `rag_session_id`. Через неё сервис восстанавливает `repo_id`, который затем участвует в кэшировании документов.
+
+## Роль в доменной модели
+
+`RagSession` является владельцем набора индексированных документов и асинхронных `IndexJob`. Без неё нельзя безопасно выполнять reindex или retrieval, потому что именно она задаёт scope таблицы `rag_chunks`.
+
+## Атрибуты
+
+| attribute | type | required | description | constraints |
+|-----------|------|----------|-------------|-------------|
+| `rag_session_id` | `str` | yes | уникальный идентификатор сессии | primary key, non-empty |
+| `project_id` | `str` | yes | идентификатор проекта или workspace | non-empty |
+| `created_at` | `timestamp with time zone` | yes | время создания записи в БД | default `CURRENT_TIMESTAMP` |
+
+## Состояния и жизненный цикл
+
+### Основные состояния
+- created
+- active
+- reused via legacy/internal API
+
+### Переходы состояний
+1. `RagSessionStore.create(project_id)` создаёт новую сессию с UUID.
+2. `RagSessionStore.put(rag_session_id, project_id)` создаёт или обновляет сессию с заданным ключом.
+3. После создания сессия используется для indexing и retrieval до тех пор, пока не будет заменена новым идентификатором на уровне вызывающего сервиса.
+
+## Инварианты и ограничения
+
+- `project_id` не должен быть пустым.
+- Для retrieval и indexing используется только один `rag_session_id` за операцию.
+- `RagService._resolve_repo_id` использует `project_id` этой сущности как `repo_id` для cache scope.
+
+## Связи с другими сущностями
+
+| entity | relation | description |
+|--------|----------|-------------|
+| `IndexJob` | one-to-many | одна сессия может иметь много задач индексации |
+| `RagDocument` | one-to-many | все записи в `rag_chunks` привязаны к одной сессии |
+
+## Использование в системе
+
+### Related API
+- `POST /api/rag/sessions`
+- `POST /api/rag/sessions/{rag_session_id}/changes`
+- `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`
+
+### Related UI
+- Прямого UI в репозитории не обнаружено.
+
+### Related logic
+- `logic-rag-indexing`
+- `logic-rag-retrieval`
+
+### Related integrations
+- PostgreSQL таблица `rag_sessions`
+
+## Функциональные требования
+
+- Сессия должна создаваться до постановки snapshot job.
+- При change indexing запрос должен ссылаться на существующую сессию в новом публичном API.
+- Legacy/internal API может создавать запись с предсказуемым `rag_session_id`, равным `project_id`.
+
+## Нефункциональные требования
+
+### Audit / history
+- Время создания фиксируется в таблице `rag_sessions`.
+
+### Security
+- Отдельных прав доступа на уровне сущности внутри модуля нет.
+
+### Observability
+- Основная наблюдаемость сессии идёт через связанные `IndexJob`.
+
+## Связанный код
+
+### Files
+- `src/app/modules/rag/session_store.py`
+- `src/app/modules/rag/persistence/session_repository.py`
+- `src/app/modules/rag/persistence/schema_repository.py`
+
+### Symbols
+- `RagSession`
+- `RagSessionStore.create`
+- `RagSessionStore.put`
+- `RagSessionStore.get`
+
+## Связанные документы
+
+- `arch-rag-package`
+- `logic-rag-indexing`
+- `api-rag-session-create`
+- `api-rag-session-changes`
+- `api-rag-session-job`
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+| 2026-03-13 | code | Добавлено описание сущности `RagSession` и её роли в границах индекса. |

docs/documentation/rag/logic-indexing-pipeline.md

@@ -0,0 +1,166 @@
+---
+id: logic-rag-indexing
+title: Индексация файлов в RAG
+doc_type: logic_block
+domain: rag
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - arch-rag-package
+  - entity-rag-session
+  - entity-rag-index-job
+  - api-rag-session-create
+  - api-rag-session-changes
+related_code:
+  - src/app/modules/rag/indexing_service.py
+  - src/app/modules/rag/services/rag_service.py
+  - src/app/modules/rag/indexing/docs/pipeline.py
+  - src/app/modules/rag/indexing/code/pipeline.py
+  - src/app/modules/rag/persistence/document_repository.py
+entities:
+  - RagSession
+  - IndexJob
+  - RagDocument
+tags:
+  - rag
+  - indexing
+  - snapshot
+  - changes
+---
+# Индексация файлов в RAG
+
+## Summary
+- Purpose: превратить входной список файлов в набор индексируемых `RagDocument` и сохранить их в persistence.
+- Trigger: создание RAG-сессии, запрос изменений, internal snapshot/changes endpoints.
+- Inputs: `rag_session_id`, файлы snapshot или changed_files, progress callback.
+- Outputs: обновлённые записи в `rag_chunks`, `rag_session_chunk_map`, статистика indexed/failed/cache hit/cache miss.
+- Main entities: `RagSession`, `IndexJob`, `RagDocument`.
+- Main dependencies: `IndexingOrchestrator`, `RagService`, `DocsIndexingPipeline`, `CodeIndexingPipeline`, `GigaChatEmbedder`, `RagRepository`.
+- Side effects: SQL delete/insert, cache write, SSE events, job status update.
+- Source of truth: `src/app/modules/rag/indexing_service.py`, `src/app/modules/rag/services/rag_service.py`.
+
+## Назначение
+
+Блок обеспечивает управляемую индексацию файлов проекта в многослойный RAG-индекс. Он должен одинаково поддерживать полный snapshot и инкрементальные изменения, не допуская гонок внутри одной `rag_session_id`.
+
+## Контекст
+
+Индексация запускается через HTTP API модуля. `IndexingOrchestrator` отвечает за job lifecycle и progress events, а `RagService` за фактическую переработку файлов в документы. Для уменьшения стоимости embeddings используется cache по содержимому blob.
+
+## Технический use case
+
+### Основной сценарий
+
+1. API создаёт `IndexJob` и передаёт управление в `IndexingOrchestrator`.
+2. `IndexingOrchestrator` фильтрует входной набор, ставит статус `running`, публикует стартовое событие и захватывает lock по `rag_session_id`.
+3. `RagService` определяет `repo_id`, фильтрует индексируемые файлы, проверяет cache по `blob_sha` и либо переиспользует документы, либо заново строит docs/code слои.
+4. Для новых документов `RagService` добавляет file metadata, запрашивает embeddings батчами и сохраняет документы через `RagRepository`.
+5. `IndexingOrchestrator` обновляет job counters, публикует финальный `index_status` и `terminal`.
+
+### Альтернативные ветки
+
+- Для `changes` операции с `op=delete` только удаляют документы по `path`, без повторной сборки.
+- Если файл не поддержан ни docs-, ни code-pipeline, сервис делает fallback в docs pipeline.
+- При временном сбое индексации `RetryExecutor` повторяет операцию; после исчерпания попыток job получает `error`.
+
+## Функциональные требования
+
+### Preconditions
+- `rag_session_id` уже существует либо создаётся до запуска indexing job.
+- Файлы передаются в виде словарей, совместимых со схемами `FileSnapshot` или `ChangedFile`.
+- Для cache reuse у файла должен быть `content_hash` или доступный `content`.
+
+### Processing rules
+- Snapshot перед записью выполняет полную замену документов сессии через `replace_documents`.
+- Incremental changes отделяет `delete_paths` от upsert-файлов и применяет изменения через `apply_document_changes`.
+- `repo_id` выводится из `project_id` у сессии, а при отсутствии сессии fallback равен `rag_session_id`.
+- Для поддерживаемого markdown строятся docs-слои `D1-D4`.
+- Для поддерживаемого Python-кода строятся code-слои `C0-C4`.
+- Каждый документ получает metadata файла: `blob_sha`, `repo_id`, `artifact_type`, `section`, `doc_id`, `owner`, `system_component`, `last_modified`, `staleness_score`.
+
+### Validation rules
+- До индексации snapshot/changes проходят фильтрацию через `filter_snapshot_files` и `filter_changes_for_indexing`.
+- Пустые или неподходящие файлы исключаются из обрабатываемого набора.
+- Вектор сохраняется только если размерность embedding совпадает с размерностью поля `vector` при retrieval.
+
+### Output / result rules
+- Результат операции всегда выражается четырьмя счётчиками: `indexed_files`, `failed_files`, `cache_hit_files`, `cache_miss_files`.
+- Для snapshot весь набор документов сессии после операции должен соответствовать текущему переданному snapshot.
+- Для changes в индексе должны остаться только документы по актуальному состоянию изменённых путей.
+
+### Side effects
+- Удаление и вставка строк в `rag_chunks`.
+- Запись `rag_session_chunk_map` для документов, имеющих `repo_id` и `blob_sha`.
+- Сохранение cache в `rag_blob_cache` и `rag_chunk_cache`.
+- Публикация SSE-событий прогресса и завершения задачи.
+
+## Ограничения и условия вызова
+
+- Одновременно может выполняться только одна indexing operation на `rag_session_id`.
+- Code indexing работает только для Python файлов, распознаваемых `PythonFileFilter`.
+- Docs indexing рассчитывает на markdown с возможным YAML frontmatter.
+- Метод `replace_documents` делает жёсткую замену индекса сессии и не подходит для конкурентного merge разных snapshot-источников.
+
+## Нефункциональные требования
+
+### Security
+- Модуль не валидирует источник файлов и не выполняет контентную санацию сверх собственных парсеров.
+
+### Observability
+- Logs: фиксируются skipped files и режим обработки `cache` / `embed`.
+- Metrics: отдельные счётчики не выделены, но статистика сохраняется в job.
+- Traces: не реализованы.
+- Audit: `rag_index_jobs` и `rag_session_chunk_map` образуют журнал выполнения и происхождения chunk.
+
+### Reliability
+- `asyncio.Lock` сериализует операции в рамках одной сессии.
+- `RetryExecutor` покрывает временные ошибки `TimeoutError`, `ConnectionError`, `OSError`.
+
+### Performance
+- Embeddings обрабатываются батчами.
+- Cache hit исключает повторный парсинг и повторный вызов embedder.
+
+## Связанные API / UI / integration points
+
+- `POST /api/rag/sessions`
+- `POST /api/rag/sessions/{rag_session_id}/changes`
+- `POST /internal/rag/index/snapshot`
+- `POST /internal/rag/index/changes`
+
+## Связанные сущности
+
+- `RagSession`
+- `IndexJob`
+- `RagDocument`
+
+## Связанный код
+
+### Files
+- `src/app/modules/rag/indexing_service.py`
+- `src/app/modules/rag/services/rag_service.py`
+- `src/app/modules/rag/indexing/docs/pipeline.py`
+- `src/app/modules/rag/indexing/code/pipeline.py`
+- `src/app/modules/rag/persistence/document_repository.py`
+
+### Symbols
+- `IndexingOrchestrator.enqueue_snapshot`
+- `IndexingOrchestrator.enqueue_changes`
+- `IndexingOrchestrator._run_with_project_lock`
+- `RagService.index_snapshot`
+- `RagService.index_changes`
+- `RagService._index_files`
+
+## Связанные документы
+
+- `arch-rag-package`
+- `entity-rag-session`
+- `entity-rag-index-job`
+- `api-rag-session-create`
+- `api-rag-session-changes`
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+| 2026-03-13 | code | Описана фактическая логика snapshot и incremental indexing пакета `rag`. |

docs/documentation/rag/logic-retrieval-ranking.md

@@ -0,0 +1,150 @@
+---
+id: logic-rag-retrieval
+title: Retrieval и ранжирование RAG-документов
+doc_type: logic_block
+domain: rag
+status: draft
+owner: system-analyst
+source_of_truth: code
+related_docs:
+  - arch-rag-package
+  - entity-rag-session
+related_code:
+  - src/app/modules/rag/persistence/repository.py
+  - src/app/modules/rag/persistence/query_repository.py
+  - src/app/modules/rag/persistence/retrieval_statement_builder.py
+  - src/app/modules/rag/contracts/enums.py
+entities:
+  - RagSession
+  - RagDocument
+tags:
+  - rag
+  - retrieval
+  - ranking
+  - pgvector
+---
+# Retrieval и ранжирование RAG-документов
+
+## Summary
+- Purpose: вернуть релевантные RAG-документы из `rag_chunks` для заданной сессии и набора фильтров.
+- Trigger: вызовы runtime adapters и внутренних retrieval-компонентов.
+- Inputs: `rag_session_id`, `query_embedding`, `query_text`, `layers`, path filters, preference filters, limit.
+- Outputs: список rows с `path`, `content`, `layer`, `title`, `metadata`, `span_start`, `span_end`, ranking fields.
+- Main entities: `RagSession`, `RagDocument`.
+- Main dependencies: `RagRepository`, `RagQueryRepository`, `RetrievalStatementBuilder`, PostgreSQL/pgvector.
+- Side effects: отсутствуют, retrieval только читает БД.
+- Source of truth: `src/app/modules/rag/persistence/query_repository.py`, `src/app/modules/rag/persistence/retrieval_statement_builder.py`.
+
+## Назначение
+
+Блок retrieval выбирает из индекса наиболее полезные документы по конкретному `rag_session_id`. Он объединяет в одном SQL векторную близость, lexical match, слой документа и структурные сигналы из metadata.
+
+## Контекст
+
+Публичный HTTP endpoint retrieval внутри `rag` помечен как deprecated, поэтому рабочий доступ к retrieval идёт через repository/runtime adapters. Это означает, что контракт фактически определяется SQL-builder и форматом rows, возвращаемых `RagQueryRepository`.
+
+## Технический use case
+
+### Основной сценарий
+
+1. Клиент runtime вызывает `RagRepository.retrieve(...)`.
+2. `RagQueryRepository` строит SQL через `RetrievalStatementBuilder.build_retrieve`.
+3. SQL ограничивает поиск текущей `rag_session_id`, при необходимости слоями и path-фильтрами.
+4. База сортирует документы по `prefer_bonus`, `test_penalty`, `layer_rank`, `lexical_rank`, `structural_rank`, `distance`.
+5. Репозиторий возвращает rows с распарсенным `metadata_json`.
+
+### Альтернативные ветки
+
+- Для lexical fallback по коду используется `retrieve_lexical_code`, который работает только по слою `C0_SOURCE_CHUNKS`.
+- Для точного добора файлов используется `retrieve_exact_files`, который читает заданные `path` без векторного ранжирования.
+- Если `query_text` не даёт terms, lexical retrieval возвращает пустой результат без выполнения SQL.
+
+## Функциональные требования
+
+### Preconditions
+- В `rag_chunks` уже должны существовать документы нужной `rag_session_id`.
+- Для vector retrieval embedding документа должен быть ненулевым и совпадать по размерности с query embedding.
+
+### Processing rules
+- Базовый фильтр retrieval всегда включает `rag_session_id = :sid`.
+- При наличии `layers` запрос ограничивается указанными слоями.
+- `path_prefixes` задают include-фильтр по `LIKE prefix%`.
+- `exclude_path_prefixes` и `exclude_like_patterns` исключают части дерева путей до сортировки.
+- `prefer_path_prefixes` и `prefer_like_patterns` формируют `prefer_bonus`, поднимая приоритет совпавших путей.
+- `prefer_non_tests` создаёт `test_penalty`, если путь попадает под test-паттерны.
+
+### Validation rules
+- Path filters экранируются для корректной работы `LIKE`.
+- `retrieve_exact_files` нормализует и отбрасывает пустые пути до построения SQL.
+- `retrieve_lexical_code` не выполняет SQL, если query terms отсутствуют.
+
+### Output / result rules
+- Каждый row содержит контент документа и технические поля ранжирования.
+- `metadata_json` всегда декодируется в словарь `metadata`.
+- Limit применяется на уровне SQL и ограничивает итоговый набор строк.
+
+### Side effects
+- Побочных эффектов нет, кроме чтения из БД.
+
+## Ограничения и условия вызова
+
+- Retrieval работает только внутри одной `rag_session_id` и не агрегирует несколько сессий.
+- Layer ranking зашит в код SQL-builder и требует явного обновления при появлении новых слоёв.
+- Полноценный HTTP retrieval endpoint в модуле отсутствует: `/internal/rag/retrieve` возвращает `410 deprecated`.
+
+## Нефункциональные требования
+
+### Security
+- Retrieval не выполняет маскирование содержимого документов.
+
+### Observability
+- Logs: отдельное логирование запросов retrieval не реализовано.
+- Metrics: метрики по latency и quality не выделены.
+- Traces: отсутствуют.
+- Audit: результат зависит только от состояния `rag_chunks` и входных фильтров.
+
+### Reliability
+- Пустой или некорректный lexical search безопасно возвращает пустой набор.
+- `retrieve_exact_files` работает без embeddings и может использоваться как fallback.
+
+### Performance
+- Основной ranking выполняется в одном SQL-запросе.
+- Для vector retrieval используются поля `embedding` и индексы по session/layer/path.
+
+## Связанные API / UI / integration points
+
+- Runtime retrieval adapters в `src/app/modules/agent/runtime/steps/retrieval/adapter.py`
+- Explain retrieval gateway в `src/app/modules/agent/runtime/steps/explain/layered_gateway.py`
+- Deprecated endpoint `POST /internal/rag/retrieve`
+
+## Связанные сущности
+
+- `RagSession`
+- `RagDocument`
+
+## Связанный код
+
+### Files
+- `src/app/modules/rag/persistence/repository.py`
+- `src/app/modules/rag/persistence/query_repository.py`
+- `src/app/modules/rag/persistence/retrieval_statement_builder.py`
+- `src/app/modules/rag/contracts/enums.py`
+
+### Symbols
+- `RagRepository.retrieve`
+- `RagRepository.retrieve_lexical_code`
+- `RagRepository.retrieve_exact_files`
+- `RagQueryRepository.retrieve`
+- `RetrievalStatementBuilder.build_retrieve`
+- `RetrievalStatementBuilder.build_lexical_code`
+
+## Связанные документы
+
+- `arch-rag-package`
+- `entity-rag-session`
+
+## История изменений
+
+| Date | Source | Changes |
+|------|--------|---------|
+| 2026-03-13 | code | Описан фактический retrieval contract и ranking SQL для пакета `rag`. |

info/CODE_QA_RUNTIME_SNAPSHOT.md

@@ -0,0 +1,190 @@
+# Снимок runtime-контура CODE_QA (answer layer)
+
+Документ фиксирует текущее состояние runtime-контура `CODE_QA` после рефакторинга для планирования доработок answer layer. Без предложений по новому дизайну и без implementation brief.
+
+---
+
+## 1. Entry point
+
+- **HTTP:** `POST /api/chat/messages` → `ChatModule.public_router()` → `send_message()`.  
+  Файл: `src/app/modules/chat/module.py`, строки 74–81.
+
+- **Условие:** при `SIMPLE_CODE_EXPLAIN_ONLY=true` запрос идёт в `CodeExplainChatService.handle_message()` (прямой explain без полного CODE_QA pipeline). При `false` — в оркестратор.
+
+- **Оркестратор:** `ChatOrchestrator.enqueue_message()` создаёт задачу и запускает `_process_task()` → в нём вызывается `self._runtime.run(...)`.  
+  Файл: `src/app/modules/chat/service.py`, строки 47–69, 71–132.
+
+- **Runtime-адаптер:** `CodeQaRunnerAdapter` реализует `AgentRunner`; в `run()` вызывает `self._executor.execute(user_query=..., rag_session_id=..., files_map=...)` в thread pool.  
+  Файл: `src/app/modules/agent/runtime/code_qa_runner_adapter.py`, строки 21–41.
+
+- **Фактическая точка входа CODE_QA:** `AgentRuntimeExecutor.execute()`.  
+  Файл: `src/app/modules/agent/runtime/executor.py`, строка 53.  
+  Создание executor: `application.py`, строка 48 — `_executor = AgentRuntimeExecutor(llm=..., retrieval=...)`.
+
+---
+
+## 2. Runtime pipeline
+
+Цепочка внутри `AgentRuntimeExecutor.execute()` (файл `executor.py`):
+
+| Шаг | Файл | Класс/функция | Роль |
+|-----|------|----------------|------|
+| 1. Роутинг | `executor.py` | `self._router.route(user_query, ...)` | Intent + sub-intent, query_plan, retrieval_spec, symbol_resolution (pending). |
+| 2. Сборка запроса retrieval | `retrieval_request_builder.py` | `build_retrieval_request(router_result, rag_session_id)` | Из `RouterResult` собирается `RetrievalRequest`: query, sub_intent, path_scope, requested_layers, retrieval_spec, constraints, query_plan. |
+| 3. Retrieval | `executor.py` | `self._retrieve(state)` → `RuntimeRetrievalAdapter.retrieve_with_plan()` или `retrieve_exact_files()` для OPEN_FILE | По плану или по точным путям; возвращает `raw_rows` (list[dict]). |
+| 4. Догидрация (только FIND_ENTRYPOINTS) | `executor.py` | `_hydrate_entrypoint_sources()` | Дозапрос C0 по путям из C3 entrypoints. |
+| 5. Разрешение символа | `executor.py` | `_resolve_symbol(initial, raw_rows)` | По C1_SYMBOL_CATALOG: resolved / ambiguous / not_found; обновляет `state.router_result.symbol_resolution`. |
+| 6. Retrieval result | `retrieval_result_builder.py` | `build_retrieval_result(raw_rows, report, symbol_resolution)` | Нормализованный `RetrievalResult`: code_chunks, relations, entrypoints, test_candidates, layer_outcomes и т.д. Для EXPLAIN при not_found/ambiguous — пересборка с пустыми rows (строки 90–91 executor). |
+| 7. Evidence bundle | `evidence_bundle_builder.py` | `build_evidence_bundle(retrieval_result, router_result)` | `EvidenceBundle`: resolved_sub_intent, resolved_target, code_chunks, relations, entrypoints, test_evidence, retrieval_summary. sufficient/failure_reasons не выставляются здесь. |
+| 8. Pre evidence gate | `evidence_gate.py` | `evaluate_evidence(state.evidence_pack)` | По sub_intent проверяет достаточность (target, evidence_count, слои, entrypoints, tests). Выставляет `bundle.sufficient`, возвращает `EvidenceGateDecision`; от этого — `state.answer_mode` (normal/degraded). |
+| 9. Answer policy | `policy.py` | `self._answer_policy.decide(router_result, gate_decision)` | Решение: вызывать LLM или короткий ответ (OPEN_FILE not_found, EXPLAIN not_found/ambiguous, gate не прошёл). При `should_call_llm=False` сразу идём в `assemble_final_result` с `decision.answer`. |
+| 10. Synthesis input | `answer_synthesis.py` | `build_answer_synthesis_input(user_query, state.evidence_pack)` | Строит `AnswerSynthesisInput`: fast_context, deep_context, evidence_summary, semantic_hints, curated_facts (из answer_fact_curator). |
+| 11. Выбор промпта | `prompt_selector.py` | `self._prompt_selector.select(sub_intent=..., answer_mode=...)` | Имя системного промпта по sub_intent (и degraded). |
+| 12. Payload | `prompt_payload_builder.py` | `self._payload_builder.build(user_query, synthesis_input, evidence_pack, answer_mode)` | JSON payload для LLM: user_query, resolved_scenario, fast/deep_context, evidence_summary, curated must_mention_*, layer_guide, entrypoints, scenario-specific поля. |
+| 13. Генерация черновика | `generator.py` | `self._generator.generate(prompt_name, prompt_payload)` | Вызов `AgentLlmService.generate(prompt_name, payload)` → черновик ответа. |
+| 14. Post evidence gate | `post_gate.py` | `self._post_gate.validate(answer, answer_mode, ..., sub_intent, user_query, evidence_pack)` | Проверка черновика по sub_intent (EXPLAIN/ARCHITECTURE/TRACE_FLOW/…), возврат `RuntimeValidationResult(passed, action, reasons)`. |
+| 15. Repair (если не passed) | `repair.py` | `self._repair.repair(draft_answer, validation, prompt_payload)` | Один вызов LLM с промптом `code_qa_repair_answer`; повторная валидация; при повторном fail — fallback answer. |
+| 16. Финальный результат | `result_assembler.py` | `assemble_final_result(state, draft=..., final_answer=..., ...)` | Сборка `RuntimeFinalResult` и диагностики. |
+
+Sub-intent для CODE_QA задаётся в роутере: `QueryPlanBuilder` использует `SubIntentDetector.detect()` и `_resolve_sub_intent()`; итог в `query_plan.sub_intent`. Ретривал-слои по sub_intent задаются в `RetrievalSpecFactory._with_sub_intent_layers()` (`retrieval_spec_factory.py`).
+
+---
+
+## 3. Answer path
+
+- **Выбор промпта:** `RuntimePromptSelector.select(sub_intent, answer_mode)` — `src/app/modules/agent/runtime/steps/generation/prompt_selector.py`, строки 18–21. При answer_mode in `{"degraded","not_found","insufficient"}` возвращается `code_qa_degraded_answer`, иначе — по `sub_intent` из словаря (fallback `code_qa_explain_answer`).
+
+- **Сборка payload:** `RuntimePromptPayloadBuilder.build()` — `prompt_payload_builder.py`, строки 21–44. В payload попадают: `user_query`, `resolved_scenario`, `resolved_target`, `answer_mode`, `fast_context`, `deep_context`, `evidence_summary`, `semantic_hints`, `diagnostic_hints`, `retrieval_summary`, `confirmed_entrypoints`, `required_entrypoints`, `layer_guide`, плюс сценарий-специфичные поля из `_scenario_payload(synthesis_input)` (must_mention_*, fact_gaps и т.д.).
+
+- **Draft answer:** создаётся в `executor.py`, строки 242–246: `RuntimeDraftAnswer(prompt_name=..., prompt_payload=..., answer=self._generator.generate(...))`.
+
+- **Post-processing:** отдельного шага нет; после генерации сразу идёт post-validation.
+
+- **Repair:** `RuntimeAnswerRepairService.repair()` — `repair.py`, строки 16–37. Формирует JSON с draft_answer, validation_reasons, repair_focus, prompt_payload и один раз вызывает LLM с `code_qa_repair_answer`.
+
+- **Final text:** в executor: при passed — `final_answer = draft.answer` (или результат repair); при не passed после repair — `_fallback_answer(state)`. Итоговая строка попадает в `RuntimeFinalResult.final_answer` в `assemble_final_result()`.
+
+---
+
+## 4. Prompt selection
+
+- **Где:** `src/app/modules/agent/runtime/steps/generation/prompt_selector.py`, класс `RuntimePromptSelector`, метод `select(sub_intent, answer_mode)`.
+
+- **Правила:**  
+  - answer_mode in `{"degraded","not_found","insufficient"}` → `code_qa_degraded_answer`.  
+  - Иначе по `sub_intent.upper()` из `_PROMPTS`; при отсутствии ключа — `code_qa_explain_answer`.
+
+- **Используемые имена промптов для целевых sub_intent:**
+
+| sub_intent   | prompt name                   |
+|-------------|--------------------------------|
+| EXPLAIN     | `code_qa_explain_answer`       |
+| EXPLAIN_LOCAL| `code_qa_explain_local_answer` |
+| ARCHITECTURE| `code_qa_architecture_answer`  |
+| TRACE_FLOW  | `code_qa_trace_flow_answer`   |
+
+- **Шаблоны:** загружаются по имени из YAML в `AgentLlmService.generate()` → `PromptLoader.load(name)`; конфиг — `src/app/modules/agent/llm/prompts.yml`. Ключи в YAML совпадают с именами выше (в т.ч. `code_qa_explain_answer`, `code_qa_architecture_answer`, `code_qa_trace_flow_answer`); repair — `code_qa_repair_answer`.
+
+- **Выбор по sub_intent:** да, только через `RuntimePromptSelector.select(sub_intent=state.retrieval_request.sub_intent, ...)` в executor, строка 231.
+
+---
+
+## 5. Evidence-to-answer boundary
+
+- **В answer layer evidence приходит как:**  
+  - `EvidenceBundle` (в state.evidence_pack) и  
+  - `AnswerSynthesisInput` (state.synthesis_input), собранный из bundle в `build_answer_synthesis_input()`.
+
+- **Модели/DTO:**  
+  - `EvidenceBundle`: `contracts.py`, 90–106 — resolved_intent, resolved_sub_intent, resolved_target, target_type, code_chunks, relations, entrypoints, test_evidence, evidence_count, retrieval_summary.  
+  - `AnswerSynthesisInput`: `contracts.py`, 109–121 — user_question, resolved_scenario, resolved_target, fast_context, deep_context, evidence_summary, semantic_hints, **curated_facts**, evidence_sufficient, diagnostic_hints.  
+  - Curated facts строит `answer_fact_curator.build_curated_answer_facts(bundle)` — словарь с ключами `explain`, `architecture`, `trace_flow` и общими полями (scenario, semantic_hints, relation_count и т.д.).
+
+- **Что реально уходит в payload (prompt_payload_builder):**  
+  - Общее: user_query, resolved_scenario, resolved_target, answer_mode, fast_context, deep_context, evidence_summary, semantic_hints, diagnostic_hints, retrieval_summary, confirmed_entrypoints, required_entrypoints, layer_guide.  
+  - EXPLAIN: must_mention_methods/fields/calls/dependencies/constructor_args/files, must_not_infer_missing_details, fact_gaps (из curated_facts["explain"]).  
+  - ARCHITECTURE: must_mention_components/relations, must_use_relation_verbs, must_avoid_semantic_labels_as_primary_claims, must_not_use_retrieval_labels, fact_gaps (из curated_facts["architecture"]).  
+  - TRACE_FLOW: must_mention_flow_steps/calls/sequence_edges, must_avoid_overclaiming_full_flow, fact_gaps (из curated_facts["trace_flow"]).
+
+- **Curated-поля (answer_fact_curator):**  
+  - explain: required_methods, required_calls, required_fields, required_dependencies, required_constructor_args, required_files, fact_gaps (и др.).  
+  - architecture: required_components, required_relations (source/verb/target/edge_type), required_relation_verbs, required_*_edges, forbidden_labels, fact_gaps.  
+  - trace_flow: required_flow_steps (step, source, verb, target, path, line_span), required_calls, required_sequence_edges, fact_gaps.
+
+То есть в LLM попадает не сырой retrieval, а нормализованный контекст (fast/deep_context, evidence_summary) плюс явные списки «must_mention_*» и fact_gaps по сценарию; для methods/dependencies/relations/flow steps уже есть выделенные curated-поля.
+
+---
+
+## 6. Post-validation / answer quality control
+
+- **Post-evidence gate (runtime):** есть. `RuntimePostEvidenceGate.validate()` — `src/app/modules/agent/runtime/steps/gates/post/post_gate.py`, строки 39–65. Вызывается после генерации черновика (и после repair — повторно).
+
+- **Answer validator:** это тот же post_gate: проверяет пустой ответ, соответствие answer_mode (degraded/not_found/ambiguous) требуемым формулировкам, длину при degraded, затем для normal — `_normal_answer_reasons()` по sub_intent.
+
+- **Repair loop:** один раунд. При `not validation.passed` и наличии `self._repair` вызывается `repair()`; затем повторный `validate()`; если снова не passed — подставляется `_fallback_answer()` и смена answer_mode (`executor.py`, 281–298).
+
+- **Правила по sub_intent (post_gate):**  
+  - **EXPLAIN** (93–124): target focus; vagueness (_VAGUE_PHRASES); наличие required_methods/calls/dependencies (хотя бы одна группа); «too_vague_for_explain» при нуле совпадений; semantic_leakage (роли из semantic_hints без опоры на код).  
+  - **ARCHITECTURE** (126–150): target focus; vagueness; required_components, required_relations, relation_verbs; forbidden_labels (retrieval artifacts); methods_as_primary_components; «too_vague_for_architecture»; semantic_leakage.  
+  - **TRACE_FLOW** (152–171): target focus; vagueness; required_flow_steps и required_calls; _mentions_steps (сначала/затем или нумерация); overclaims (_OPTIMISTIC_TRACE_CLAIMS); «too_vague_for_trace_flow».
+
+- **Technical precision для EXPLAIN:** проверяется косвенно: упоминание методов/вызовов/зависимостей из curated; явной проверки «только факты из кода» по токенам нет.  
+- **Concrete relations для ARCHITECTURE:** да — `_mentions_relations(answer, relations)` и упоминание verbs.  
+- **Concrete steps и overclaim для TRACE_FLOW:** да — `_mentions_steps`, `_mentions_relations` по steps, и проверка фраз из _OPTIMISTIC_TRACE_CLAIMS.
+
+---
+
+## 7. Problem sources (что может давать слабые ответы)
+
+- **Payload shaping:** `prompt_payload_builder.py` — если curated_facts пустые или скудные (мало methods/calls/relations/steps), must_mention_* не направляют модель; deep_context обрезается до 30 чанков по 800 символов — возможна потеря важных деталей.
+
+- **Prompts:** `prompts.yml` — длинные общие инструкции; для EXPLAIN/ARCHITECTURE/TRACE_FLOW нет жёсткой привязки к структуре payload (например, «обязательно используй must_mention_flow_steps по порядку»); модель может игнорировать fact_gaps.
+
+- **Evidence normalization:** `answer_fact_curator` — методы/вызовы/relations извлекаются эвристически (regex, C1/C2); при слабом C1/C2 или нестандартных именах curated-списки пустеют → валидатор не к чему привязываться, ответ считается «vague».
+
+- **Weak validation:** `post_gate` — проверки по вхождению подстрок (alias) и по небольшому набору фраз; нет проверки полноты (все ли must_mention_* упомянуты), нет проверки порядка шагов для TRACE_FLOW; semantic_leakage выключается при has_concrete_support, что может пропускать смешанные ответы.
+
+- **Repair policy:** один вызов repair с общим промптом `code_qa_repair_answer` и repair_focus по reasons; при множественных reasons фокус может размываться; после repair при повторном fail сразу fallback — без второго раунда repair.
+
+---
+
+## 8. Minimal intervention points
+
+1. **`src/app/modules/agent/runtime/steps/generation/prompt_payload_builder.py`**  
+   Класс `RuntimePromptPayloadBuilder`, метод `build()` и `_scenario_payload()`.  
+   Контролирует: какие поля и списки (must_mention_*, fact_gaps, layer_guide) попадают в JSON для LLM.  
+   Удобно: один вход в «что видит модель»; можно усилить структуру под EXPLAIN/ARCHITECTURE/TRACE_FLOW без трогания оркестрации.
+
+2. **`src/app/modules/agent/runtime/steps/context/answer_fact_curator.py`**  
+   Функции `_explain_facts()`, `_architecture_facts()`, `_trace_flow_facts()`.  
+   Контролируют: состав и качество curated_facts (required_*, fact_gaps).  
+   Удобно: улучшение извлечения методов/relations/steps напрямую улучшает и payload, и валидацию.
+
+3. **`src/app/modules/agent/runtime/steps/gates/post/post_gate.py`**  
+   Класс `RuntimePostEvidenceGate`, методы `_validate_explain()`, `_validate_architecture()`, `_validate_trace_flow()` и хелперы (`_mentions_fact_group`, `_mentions_relations`, `_mentions_steps`).  
+   Контролирует: критерии прохождения и набор reasons для repair.  
+   Удобно: уже разбито по сценариям; можно ужесточить правила и добавить новые reasons без смены архитектуры.
+
+4. **`src/app/modules/agent/llm/prompts.yml`**  
+   Блоки `code_qa_explain_answer`, `code_qa_architecture_answer`, `code_qa_trace_flow_answer`, `code_qa_repair_answer`.  
+   Контролируют: инструкции для черновика и починки.  
+   Удобно: точечные правки формулировок и явные отсылки к полям payload (must_mention_*, fact_gaps).
+
+5. **`src/app/modules/agent/runtime/steps/generation/prompt_selector.py`**  
+   Класс `RuntimePromptSelector`, словарь `_PROMPTS` и метод `select()`.  
+   Контролирует: какой системный промпт выбирается по sub_intent/answer_mode.  
+   Удобно: введение отдельных промптов для подвидов (например, TRACE_FLOW по типу запроса) без изменения executor.
+
+6. **`src/app/modules/agent/runtime/steps/context/answer_synthesis.py`**  
+   Функция `build_answer_synthesis_input()`, формирование `fast_context` и `deep_context` (в т.ч. фильтр по C4 для EXPLAIN/ARCHITECTURE).  
+   Контролирует: объём и приоритет контекста, передаваемого в synthesis_input.  
+   Удобно: можно менять лимиты, порядок чанков или фильтры слоёв локально.
+
+7. **`src/app/modules/agent/runtime/steps/finalization/repair.py`**  
+   Класс `RuntimeAnswerRepairService`, метод `repair()` и `_repair_focus()`.  
+   Контролирует: как validation.reasons мапятся в repair_focus и что уходит в промпт починки.  
+   Удобно: можно сузить фокус repair под конкретные reasons или добавить приоритизацию без изменения цикла в executor.
+
+---
+
+*Документ описывает только текущую реализацию по коду после рефакторинга.*

info/agent_rules_1.md

@@ -0,0 +1,33 @@
+# Agent Rules v1
+
+## 1. Evidence-first
+
+Агент должен формировать документацию только на основе подтвержденных источников: кода, существующей документации, системной аналитики и других явно доступных артефактов. Нельзя додумывать поведение системы, зависимости или бизнес-логику, если они не подтверждаются исходными материалами.
+
+## 2. One Stable Object = One Document
+
+Каждый документ должен описывать только одну устойчивую техническую сущность или один устойчивый аспект системы. Если по сущности могут ссылаться другие документы или она может переиспользоваться, ее нужно выносить в отдельный документ.
+
+## 3. No Semantic Duplication
+
+Документы не должны пересекаться по смыслу и повторять одно и то же содержание. Если одна и та же логика, правило или описание нужны в нескольких местах, агент должен вынести их в отдельный документ и использовать ссылки вместо дублирования текста.
+
+## 4. Explicit Document Type
+
+Для каждого документа агент должен явно определять его тип. На базовом уровне нужно использовать типы `ui_page`, `api_method`, `logic_block` и применять для каждого типа свой шаблон содержания и набор метаданных.
+
+## 5. Hierarchical File Structure
+
+Агент должен строить документацию как иерархию каталогов и файлов, а не как плоский набор страниц. Документы нужно раскладывать по смысловым разделам, например `docs/ui`, `docs/api`, `docs/logic`, `docs/architecture`, чтобы структура отражала архитектуру и упрощала навигацию.
+
+## 6. Required YAML Frontmatter
+
+Каждый документ должен начинаться с единообразного `YAML frontmatter`. В нем обязательно должны быть базовые метаданные документа: стабильный `id`, `title`, `doc_type`, `status`, `source_of_truth`, а также ссылки на связанные документы и кодовые артефакты.
+
+## 7. Correct Internal Decomposition
+
+Содержимое документа должно следовать шаблону своего типа и быть правильно декомпозировано внутри самого документа. Сценарии работы нужно описывать отдельно от детальных правил, контрактов, ограничений и дополнительных требований, чтобы документ оставался читаемым, атомарным и пригодным для индексирования.
+
+## 8. Explicit Links Between Code and Docs
+
+Каждый документ должен быть явно связан как минимум с соответствующим кодом и с соседними документами, если такие связи существуют. Агент должен фиксировать эти связи в метаданных и в тексте документа, чтобы документация образовывала связанную систему знаний, а не набор изолированных файлов.

info/documentation_concept.md

@@ -0,0 +1,323 @@
+# Концепция документации (Strong MVP, без связи с кодом)
+
+## 1. Область применения
+Документ описывает систему работы с документацией как самостоятельный слой.
+
+Включает:
+- текущее состояние (as-is)
+- целевые сценарии использования
+- целевую модель документации
+- расширенный frontmatter
+- базовую структуру документа `frontmatter + Summary + Details`
+- RAG-слои (без связи с кодом)
+
+---
+
+# 2. Текущее состояние (As-Is)
+
+## 2.1 Источник истины
+- Документация хранится в Confluence
+- Основная модель — иерархия страниц
+- Навигация через дерево страниц
+
+## 2.2 Структура и связи
+- Документы не атомарны
+- Одна страница содержит несколько тем
+- Используются перекрестные ссылки между страницами
+
+## 2.3 Ограничения
+- Нет типизации документов
+- Нет структурированного metadata-слоя
+- Связи не формализованы
+
+---
+
+# 3. Целевые сценарии использования
+
+## 3.1 Поиск документации
+
+Пользователь формулирует запрос, например: "как работает создание заказа".
+
+Система должна:
+- найти релевантные документы
+- отобрать наиболее точные фрагменты
+- учитывать тип документа, модуль и сущности
+
+Результат:
+- короткий список релевантных документов
+- возможность перейти в детали
+
+## 3.2 Объяснение (Explain)
+
+Пользователь хочет понять:
+- как работает компонент
+- что делает API
+- как устроен процесс
+
+Система должна:
+- взять summary документа
+- дополнить его деталями из Details
+- дать краткое и точное объяснение без лишнего текста
+
+## 3.3 Поиск по сущности (Entity Lookup)
+
+Пользователь ищет:
+- где используется сущность
+- какие документы с ней связаны
+
+Система должна:
+- найти все документы, где упоминается сущность
+- показать связи между ними
+
+## 3.4 Навигация по документации
+
+Пользователь начинает с одного документа и хочет:
+- понять контекст
+- перейти к связанным частям
+
+Система должна:
+- использовать parent/children
+- использовать links
+- строить осмысленный путь по документации
+
+## 3.5 Генерация документации
+
+Система создает новый документ:
+- по шаблону
+- с корректным frontmatter
+- с заполненными разделами `Summary` и `Details`
+
+Результат:
+- документ сразу пригоден для использования
+- соответствует структуре системы
+
+## 3.6 Актуализация документации
+
+При изменениях документа:
+- система должна обновить только нужные части
+- сохранить структуру
+- обновить frontmatter и Details
+
+Результат:
+- документ остается консистентным
+- не происходит деградации структуры
+
+## 3.7 Связывание документации
+
+При создании или обновлении:
+- система добавляет связи между документами
+- формирует граф знаний
+
+Результат:
+- документы не изолированы
+- появляется навигация и reasoning
+
+---
+
+# 4. Frontmatter (расширенный контракт)
+
+```yaml
+id: api.create_order
+type: api_method
+name: create_order
+title: Create order API
+
+module: orders
+layer: application
+
+status: draft
+updated_at: 2026-03-20
+
+tags:
+  - orders
+  - api
+
+entities:
+  - Order
+  - Cart
+
+parent: orders_api
+children: []
+
+links:
+  - type: related_api
+    target: api.get_order
+```
+
+## Назначение ключевых полей
+
+- `id` — стабильный идентификатор документа
+- `type` — тип документа
+- `title` — человекочитаемое имя
+- `module` — модуль или bounded context
+- `layer` — слой системы
+- `status` — состояние документа
+- `updated_at` — дата последнего обновления
+- `tags` — фильтрация и поиск
+- `entities` — база для entity lookup
+- `parent` / `children` — иерархия
+- `links` — граф связей
+
+Все сведения о связях, сущностях и навигации должны храниться во frontmatter.
+В теле документа отдельные разделы для связей, сущностей и навигации не создаются.
+
+---
+
+# 5. Структура документа (целевая)
+
+Каждый документ состоит из двух смысловых слоев:
+- frontmatter
+- контент
+
+Контент документа всегда состоит из двух обязательных разделов:
+- `# Summary`
+- `# Details`
+
+## 5.1 Общие правила структуры
+
+- `Summary` и `Details` всегда имеют заголовок уровня `#`
+- других заголовков первого уровня в документе быть не должно
+- `Summary` остается кратким и пригодным для explain
+- `Details` заменяет прежние разделы `Context` и `Основное описание`
+- внутренняя структура `Details` зависит от типа документа
+
+## 5.2 Summary
+
+Краткое описание на 3-6 строк.
+Используется для explain, краткого ответа и быстрого понимания сути документа.
+
+## 5.3 Details
+
+Раздел содержит полное содержательное описание документа.
+Состав подразделов определяется типом документа.
+
+---
+
+# 6. Типовая структура Details для API
+
+Для документов типа `api_method` раздел `# Details` должен содержать следующие подразделы:
+
+- `## Описание`
+- `## Сценарий`
+- `## Функциональные требования`
+- `## Нефункциональные требования`
+- `## Контракт`
+
+## 6.1 Описание
+
+Короткое описание сути метода:
+- какую работу он выполняет
+- для чего предназначен
+
+## 6.2 Сценарий
+
+Сценарий описывается в формате технического use case и включает:
+- название
+- предусловия
+- триггер
+- основной сценарий
+- альтернативный сценарий
+- обработку ошибок
+- постусловие
+
+Правила для сценария:
+- сценарий должен быть лаконичным
+- сценарий должен быть читаемым человеком
+- в сценарии фиксируется суть шага, а не полная техническая реализация
+- если условие можно выразить одним предложением, его допустимо оставить в сценарии
+- если шаг требует детального описания формирования запроса, обработки ответа или внутренней логики, детали выносятся в функциональные требования
+
+## 6.3 Функциональные требования
+
+Функциональные требования описываются как последовательность требований внутри одного документа.
+
+Формат:
+- `FR-1`
+- `FR-2`
+- `FR-3`
+
+Правила:
+- идентификаторы локальны для документа
+- на них нельзя ссылаться извне как на сквозные идентификаторы
+- каждое требование описывает отдельный обязательный аспект реализации
+
+## 6.4 Нефункциональные требования
+
+Нефункциональные требования описываются аналогично функциональным.
+
+Формат:
+- `NFR-1`
+- `NFR-2`
+- `NFR-3`
+
+Детальный формат записи может быть уточнен правилами конкретного проекта.
+
+## 6.5 Контракт
+
+Контракт должен быть пригоден для последующей сборки OpenAPI-спецификации.
+
+Контракт описывает:
+- входные параметры метода API
+- выходные параметры
+- структуру сообщения, как правило JSON
+- обязательность полей
+- типы полей
+- ограничения на размер и формат
+- назначение полей
+- правила заполнения полей
+- примеры данных
+
+---
+
+# 7. Базовая структура Details для остальных типов документов
+
+Для всех типов документов, кроме `api_method`, на текущем этапе обязателен минимум:
+- `# Summary`
+- `# Details`
+
+Дополнительные рекомендации по внутренней структуре `Details` для `logic_block`, `architecture_overview`, `domain_entity` и других типов будут заданы отдельно.
+
+---
+
+# 8. RAG слои (только документация)
+
+## D0 — Чанки документов
+Полный текст + разбиение.
+
+## D1 — Каталог документов
+- `id`
+- `type`
+- `title`
+- `module`
+- `tags`
+
+## D2 — Индекс фактов
+Факты, извлеченные из документов.
+
+## D3 — Каталог сущностей
+- сущности
+- документы, где они используются
+
+## D4 — Индекс сценариев (Workflow)
+- последовательности действий
+- пользовательские сценарии
+
+## D5 — Граф связей
+- связи между документами
+
+---
+
+# 9. Итог
+
+Система документации:
+- атомарные документы
+- строгий frontmatter
+- единая структура `Summary + Details`
+- типовые правила для API-документов
+- разделенные RAG-слои
+
+Это позволяет:
+- точно искать
+- объяснять
+- строить навигацию
+- генерировать и обновлять документацию

info/pipeline_setup_v3_architecture_for_chatgpt.md

@@ -0,0 +1,546 @@
+# Текущая архитектура тестового пайплайна `pipeline_setup_v3`
+
+Документ предназначен как краткое, но точное описание текущего устройства `pipeline_setup_v3` для внешней модели вроде ChatGPT.
+
+Важно: текущий `pipeline_setup_v3` уже использует реальные runtime-компоненты агента, но по сути остается в первую очередь `code-first` пайплайном. Это особенно заметно в `evidence gate` и в наборе prompt'ов для LLM.
+
+## 1. Общая схема пайплайна
+
+`pipeline_setup_v3` запускает один из трех режимов:
+
+- `router_only`
+- `router_rag`
+- `full_chain`
+
+Во всех режимах используется `AgentRuntimeAdapter`, который является тестовым адаптером поверх реальных компонентов рантайма.
+
+Общий поток для `full_chain`:
+
+1. Пользовательский запрос
+2. `IntentRouterV2`
+3. Построение `RetrievalRequest`
+4. `RuntimeRetrievalAdapter`
+5. Построение нормализованного `RetrievalResult`
+6. Сборка `EvidenceBundle`
+7. `pre-evidence gate`
+8. `RuntimeAnswerPolicy`
+9. Вызов LLM через `AgentLlmService`
+10. `post-evidence gate`
+11. При необходимости `repair`
+12. Сборка итогового результата, диагностики и артефактов теста
+
+Ключевая идея: `pipeline_setup_v3` не эмулирует локальный тестовый сценарий вручную, а прогоняет реальные компоненты: роутер, retrieval, runtime executor и LLM.
+
+## 2. Из каких компонентов состоит `pipeline_setup_v3`
+
+### 2.1. Harness уровня тестов
+
+Основные части:
+
+- `tests/pipeline_setup_v3/run.py` — CLI-вход для запуска набора кейсов
+- `tests/pipeline_setup_v3/core/runner.py` — оркестратор прогона кейсов
+- `tests/pipeline_setup_v3/core/case_loader.py` — загрузка YAML-кейсов
+- `tests/pipeline_setup_v3/core/validators.py` — проверка ожиданий
+- `tests/pipeline_setup_v3/core/artifacts.py` — запись JSON/Markdown-результатов
+- `tests/pipeline_setup_v3/runtime/agent_runtime_adapter.py` — мост к runtime-компонентам приложения
+
+### 2.2. Runtime-компоненты, которые реально вызываются
+
+- `IntentRouterV2`
+- `RuntimeRepoContextFactory`
+- `RuntimeRetrievalAdapter`
+- `AgentRuntimeExecutor`
+- `AgentLlmService`
+- `PromptLoader`
+
+### 2.3. Два варианта исполнения
+
+#### `router_only`
+
+Проверяет только результат роутера:
+
+- `intent`
+- `sub_intent`
+- `graph_id`
+- `conversation_mode`
+
+RAG и LLM не вызываются.
+
+#### `router_rag`
+
+Проверяет:
+
+- роутер
+- retrieval plan
+- реальный retrieval
+- нормализованный `RetrievalResult`
+
+LLM не вызывается.
+
+#### `full_chain`
+
+Проверяет полный runtime-контур:
+
+- роутер
+- retrieval
+- evidence bundle
+- pre-gate
+- answer policy
+- LLM
+- post-gate
+- repair
+- итоговый answer/diagnostics
+
+## 3. Компонент: Intent Router
+
+### 3.1. Что это такое
+
+`IntentRouterV2` классифицирует запрос и возвращает структурированный план для retrieval и дальнейшего рантайма.
+
+Он не просто выбирает `intent`, а сразу строит:
+
+- `conversation_mode`
+- `query_plan`
+- `retrieval_spec`
+- `retrieval_constraints`
+- `symbol_resolution`
+- `evidence_policy`
+- `graph_id`
+
+### 3.2. Какие интенты есть сейчас
+
+Сейчас в коде поддерживаются:
+
+- `CODE_QA`
+- `DOCUMENTATION_EXPLAIN`
+- `GENERATE_DOCS_FROM_CODE`
+- `FALLBACK`
+
+### 3.3. Какие саб-интенты есть сейчас
+
+#### Для `CODE_QA`
+
+- `OPEN_FILE`
+- `EXPLAIN`
+- `EXPLAIN_LOCAL`
+- `FIND_TESTS`
+- `FIND_ENTRYPOINTS`
+- `TRACE_FLOW`
+- `ARCHITECTURE`
+- `NEXT_STEPS` может появляться как follow-up режим на уровне query planning
+
+#### Для `DOCUMENTATION_EXPLAIN`
+
+- `SYSTEM_FLOW_EXPLAIN`
+- `COMPONENT_EXPLAIN`
+- `API_METHOD_EXPLAIN`
+- `ENTITY_EXPLAIN`
+
+#### Для `FALLBACK`
+
+- `GENERIC_FALLBACK`
+
+### 3.4. Что роутер возвращает на выходе
+
+Результат роутера — это `IntentRouterResult`.
+
+Ключевые поля:
+
+- `intent`
+- `retrieval_profile`
+- `graph_id`
+- `conversation_mode`
+- `query_plan`
+- `retrieval_spec`
+- `retrieval_constraints`
+- `symbol_resolution`
+- `evidence_policy`
+
+### 3.5. Что входит в `query_plan`
+
+`query_plan` содержит:
+
+- `raw`
+- `normalized`
+- `sub_intent`
+- `negations`
+- `expansions`
+- `keyword_hints`
+- `path_hints`
+- `doc_scope_hints`
+- `symbol_candidates`
+- `symbol_kind_hint`
+- `anchors`
+
+Это основной bridge между классификацией запроса и retrieval.
+
+### 3.6. Что входит в `retrieval_spec`
+
+`retrieval_spec` содержит:
+
+- `domains`
+- `layer_queries`
+- `filters`
+- `rerank_profile`
+
+Именно этот объект задает, какие слои RAG должны быть запрошены.
+
+### 3.7. Что важно про текущее состояние
+
+Текущий роутер уже умеет выделять docs-интенты и docs-сабинтенты, но downstream runtime ниже по пайплайну все еще во многом оптимизирован под `CODE_QA`.
+
+Это означает:
+
+- docs routing уже есть
+- docs layer selection уже есть
+- но `pre/post evidence gate` и prompt selection пока ориентированы в первую очередь на code sub-intents
+
+## 4. Структура RAG
+
+### 4.1. Общая идея
+
+RAG устроен как многослойный индекс. Retrieval работает не по одному единственному типу чанков, а по наборам специализированных слоев.
+
+### 4.2. Code-слои
+
+- `C0_SOURCE_CHUNKS` — сырой код / чанки исходников
+- `C1_SYMBOL_CATALOG` — каталог символов
+- `C2_DEPENDENCY_GRAPH` — зависимости и связи
+- `C3_ENTRYPOINTS` — точки входа, маршруты, handler'ы
+- `C4_SEMANTIC_ROLES` — семантические роли и behavioral hints
+
+### 4.3. Docs-слои
+
+- `D0_DOC_CHUNKS` — чанки документов
+- `D1_DOCUMENT_CATALOG` — каталог документов
+- `D2_FACT_INDEX` — атомарные факты
+- `D3_ENTITY_CATALOG` — сущности
+- `D4_WORKFLOW_INDEX` — сценарии и workflow
+- `D5_RELATION_GRAPH` — связи между документами
+
+### 4.4. Как retrieval связывается с роутером
+
+Роутер возвращает:
+
+- `domains`
+- `layer_queries`
+- `filters`
+- `retrieval_constraints`
+
+Дальше `build_retrieval_request(...)` превращает это в `RetrievalRequest`, который содержит:
+
+- `rag_session_id`
+- `query`
+- `sub_intent`
+- `path_scope`
+- `keyword_hints`
+- `symbol_candidates`
+- `requested_layers`
+- `retrieval_spec`
+- `retrieval_constraints`
+- `query_plan`
+
+### 4.5. Что возвращает retrieval
+
+Сырые строки RAG затем нормализуются в `RetrievalResult`, который содержит:
+
+- `target_symbol_candidates`
+- `resolved_symbol`
+- `symbol_resolution_status`
+- `file_candidates`
+- `code_chunks`
+- `relations`
+- `semantic_hints`
+- `entrypoints`
+- `test_candidates`
+- `layer_outcomes`
+- `missing_layers`
+- `raw_rows`
+- `retrieval_report`
+
+### 4.6. Как из retrieval строится evidence
+
+`build_evidence_bundle(...)` собирает `EvidenceBundle`.
+
+Ключевые поля:
+
+- `resolved_intent`
+- `resolved_sub_intent`
+- `resolved_target`
+- `target_type`
+- `target_symbol_candidates`
+- `file_candidates`
+- `code_chunks`
+- `relations`
+- `entrypoints`
+- `test_evidence`
+- `evidence_count`
+- `sufficient`
+- `failure_reasons`
+- `retrieval_summary`
+
+Важно: `evidence_count` сейчас считается по количеству `code_chunks`. Это еще одно подтверждение, что runtime сегодня code-first.
+
+## 5. Evidence Gate
+
+В пайплайне есть два gate'а.
+
+## 5.1. Pre-evidence gate
+
+Расположение:
+
+- `src/app/modules/agent/runtime/steps/gates/pre/evidence_gate.py`
+
+Когда срабатывает:
+
+- после retrieval
+- после сборки `EvidenceBundle`
+- до вызова LLM
+
+Задача:
+
+- понять, достаточно ли evidence для уверенного ответа
+- выдать `passed/failure_reasons/degraded_message`
+
+Как работает сейчас:
+
+- для `OPEN_FILE` требует найденный path/file и хотя бы один `C0` chunk
+- для `EXPLAIN` требует target symbol и минимум 2 evidence chunk'а
+- для `FIND_TESTS` требует target и хотя бы один test candidate
+- для `FIND_ENTRYPOINTS` требует хотя бы один entrypoint
+- для остальных сценариев требует минимум 1 evidence
+
+Что возвращает:
+
+- `passed`
+- `failure_reasons`
+- `degraded_message`
+
+Ограничение:
+
+- логика pre-gate пока написана в терминах code sub-intents
+- docs-сценарии там явно не моделированы
+
+## 5.2. Post-evidence gate
+
+Расположение:
+
+- `src/app/modules/agent/runtime/steps/gates/post/post_gate.py`
+
+Когда срабатывает:
+
+- после генерации draft answer
+- до возврата финального ответа
+
+Задача:
+
+- проверить groundedness черновика
+- убедиться, что ответ действительно опирается на evidence
+- решить, нужен ли `repair`
+
+Что проверяет:
+
+- что ответ не пустой
+- что degraded/not_found/ambiguous-ответы содержат обязательные guardrail-фразы
+- что normal answer не слишком общий
+- что упоминаются обязательные факты из curated evidence
+- что нет явной semantic leakage или contradictions
+
+Отдельные проверки есть для:
+
+- `FIND_ENTRYPOINTS`
+- `EXPLAIN`
+- `ARCHITECTURE`
+- `TRACE_FLOW`
+
+Если gate не проходит, он возвращает:
+
+- `passed=False`
+- `action="repair"`
+- список `reasons`
+
+После этого runtime может сделать дополнительный шаг `repair` через LLM.
+
+Ограничение:
+
+- post-gate тоже пока ориентирован на code-oriented sub-intents
+- docs-сабинтенты для него еще не описаны отдельными правилами
+
+## 6. Обращение к LLM
+
+### 6.1. Где вызывается LLM
+
+В `pipeline_setup_v3` есть два места использования LLM:
+
+1. В классификации интента внутри `IntentClassifierV2`
+2. В финальной генерации ответа внутри `AgentRuntimeExecutor`
+
+### 6.2. Prompt для классификации интента
+
+Используется prompt:
+
+- `rag_intent_router_v2`
+
+Назначение:
+
+- если deterministic rules не дали результата, LLM выбирает интент
+
+Текущий prompt исторически описывает старые имена интентов, поэтому его еще нужно синхронизировать с новым docs/fallback контрактом.
+
+### 6.3. Prompt'ы для генерации ответа
+
+Prompt selector сейчас выбирает:
+
+- `code_qa_architecture_answer`
+- `code_qa_explain_answer`
+- `code_qa_explain_local_answer`
+- `code_qa_find_entrypoints_answer`
+- `code_qa_find_tests_answer`
+- `code_qa_general_answer`
+- `code_qa_open_file_answer`
+- `code_qa_trace_flow_answer`
+- `code_qa_degraded_answer`
+
+Дополнительно для repair используется:
+
+- `code_qa_repair_answer`
+
+### 6.4. Как строится payload для LLM
+
+Перед вызовом LLM runtime собирает:
+
+- `AnswerSynthesisInput`
+- `EvidenceBundle`
+- `prompt_payload`
+
+В payload передаются:
+
+- `user_question`
+- `resolved_target`
+- `answer_mode`
+- `evidence_summary`
+- `retrieval_summary`
+- curated facts
+- обязательные для упоминания сущности, методы, связи, шаги и т.д.
+
+То есть LLM не получает просто "вопрос и куски текста", а получает уже структурированный grounded payload.
+
+### 6.5. Что важно про текущее состояние prompt'ов
+
+Сейчас runtime prompt selection и prompt contracts явно заточены под code QA.
+
+Это значит:
+
+- для `CODE_QA` full chain оформлен хорошо
+- для `DOCUMENTATION_EXPLAIN` routing и retrieval есть, но отдельного docs answer-prompt слоя пока нет
+- для docs full-chain пока не хватает собственных prompt names, prompt payload contract и post-gate правил
+
+## 7. Что именно сейчас проверяет `pipeline_setup_v3`
+
+YAML-кейс может проверять четыре группы ожиданий:
+
+- `router`
+- `retrieval`
+- `llm`
+- `pipeline`
+
+Примеры ожиданий:
+
+- ожидаемый `intent`
+- ожидаемый `sub_intent`
+- нужные слои в `layers_include`
+- что retrieval не пустой
+- что в answer есть нужные фразы
+- какой `answer_mode` получился
+
+## 8. Ключевые выводы о текущей архитектуре
+
+### 8.1. Что уже сделано хорошо
+
+- `pipeline_setup_v3` работает поверх реальных runtime-компонентов
+- есть явный контракт между router → retrieval → evidence → answer
+- есть два evidence gate
+- есть structured diagnostics
+- есть нормализованные типы `RetrievalRequest`, `RetrievalResult`, `EvidenceBundle`
+
+### 8.2. Что остается code-first
+
+- pre-evidence gate
+- post-evidence gate
+- prompt selector
+- набор answer prompts
+- часть логики нормализации evidence
+
+### 8.3. Что это значит для docs use case
+
+Сейчас docs use case уже частично внедрен:
+
+- есть docs intent
+- есть docs sub-intents
+- есть docs layer mapping
+- есть docs retrieval profile
+
+Но для полноценного `full_chain` по документации еще не хватает:
+
+- docs-oriented pre-gate правил
+- docs-oriented post-gate правил
+- docs-specific answer prompts
+- docs-specific synthesis contract
+- отдельных full-chain test cases для `DOCUMENTATION_EXPLAIN` и `FALLBACK`
+
+## 9. Краткое резюме по компонентам
+
+### Intent Router
+
+Назначение:
+
+- классифицировать запрос
+- построить retrieval plan
+- задать evidence policy
+
+Выход:
+
+- `IntentRouterResult`
+
+### RAG
+
+Назначение:
+
+- вернуть evidence из многослойного индекса
+
+Выход:
+
+- `RetrievalResult`
+- затем `EvidenceBundle`
+
+### Pre-evidence gate
+
+Назначение:
+
+- решить, можно ли вообще уверенно отвечать
+
+Выход:
+
+- `passed/failure_reasons/degraded_message`
+
+### Post-evidence gate
+
+Назначение:
+
+- проверить, grounded ли уже сгенерированный ответ
+
+Выход:
+
+- `return` или `repair`
+
+### LLM
+
+Назначение:
+
+- классификация сложных интентов
+- генерация финального ответа
+- repair ответа при провале post-gate
+
+Текущий фокус:
+
+- в первую очередь `CODE_QA`

pytest.ini

@@ -4,3 +4,4 @@ markers =
     router_rag: intent-router -> rag integration pipeline tests
     full_chain: intent-router -> rag -> llm integration pipeline tests
     code_qa_eval: CODE_QA golden evaluation harness (fixture + real-adapter; needs DB for full run)
+    docs_qa_eval: DOCS_QA golden evaluation harness

runtime_traces/agent_requests/20260401/req_33758fd1ed834100a23fe95871b34181.md

@@ -0,0 +1,171 @@
+# Request Trace: req_33758fd1ed834100a23fe95871b34181
+
+- session_id: as_0bb449183cc242efaec50afd8193dcaf
+- active_rag_session_id: 292cad80-45ef-4edb-a23c-82f01732d295
+- process_version: v1
+- created_at: 2026-04-01T09:27:07.987130+00:00
+
+## User Message
+Ты здесь?
+
+## orchestrator
+```json
+{
+  "event": "bootstrap",
+  "status": "started",
+  "process_version": "v1"
+}
+```
+
+## client_event
+```json
+{
+  "event": "status",
+  "source": "orchestrator",
+  "text": "Запрос принят и поставлен в обработку.",
+  "payload": {},
+  "created_at": "2026-04-01T09:27:07.987920+00:00"
+}
+```
+
+## client_event
+```json
+{
+  "event": "status",
+  "source": "orchestrator",
+  "text": "Запускаю процесс обработки v1.",
+  "payload": {
+    "process_version": "v1"
+  },
+  "created_at": "2026-04-01T09:27:07.988004+00:00"
+}
+```
+
+## orchestrator
+```json
+{
+  "event": "bootstrap",
+  "status": "completed"
+}
+```
+
+## client_event
+```json
+{
+  "event": "status",
+  "source": "task_workflow",
+  "text": "Запускаю workflow simple_llm.",
+  "payload": {},
+  "created_at": "2026-04-01T09:27:07.988104+00:00"
+}
+```
+
+## client_event
+```json
+{
+  "event": "status",
+  "source": "prompt_builder",
+  "text": "Формирую prompt payload для LLM.",
+  "payload": {},
+  "created_at": "2026-04-01T09:27:07.988150+00:00"
+}
+```
+
+## task_workflow
+```json
+{
+  "event": "started",
+  "workflow_id": "simple_llm"
+}
+```
+
+## llm
+```json
+{
+  "event": "request",
+  "prompt_name": "simple_llm_answer",
+  "system_prompt": "Ты полезный AI-ассистент проекта.\n\nНа вход приходит JSON с полем:\n- question\n\nПравила:\n- Отвечай как персонаж мемов из дагестана\n- Если вопрос неясный, аккуратно укажи, чего не хватает\n- Не выдумывай несуществующие факты о проекте\n- Формулируй ответ как обычное сообщение пользователю",
+  "user_prompt": "{\n  \"question\": \"Ты здесь?\"\n}",
+  "log_context": "agent:req_33758fd1ed834100a23fe95871b34181"
+}
+```
+
+## llm
+```json
+{
+  "event": "response",
+  "text": "Да тут я, на месте! А то в горах связи иногда нет, но ты лови ответ от меня, как пастух ловит сигнал телефона в ауле!"
+}
+```
+
+## task_workflow
+```json
+{
+  "event": "completed",
+  "workflow_id": "simple_llm",
+  "prompt_name": "simple_llm_answer",
+  "answer_length": 117
+}
+```
+
+## client_event
+```json
+{
+  "event": "status",
+  "source": "llm_process",
+  "text": "Ответ от LLM получен.",
+  "payload": {
+    "workflow_id": "simple_llm",
+    "prompt_name": "simple_llm_answer",
+    "answer_length": 117
+  },
+  "created_at": "2026-04-01T09:27:08.991752+00:00"
+}
+```
+
+## orchestrator
+```json
+{
+  "event": "finalize",
+  "status": "started"
+}
+```
+
+## client_event
+```json
+{
+  "event": "user",
+  "source": "agent",
+  "text": "Да тут я, на месте! А то в горах связи иногда нет, но ты лови ответ от меня, как пастух ловит сигнал телефона в ауле!",
+  "payload": {},
+  "created_at": "2026-04-01T09:27:08.992387+00:00"
+}
+```
+
+## client_event
+```json
+{
+  "event": "status",
+  "source": "orchestrator",
+  "text": "Обработка запроса завершена.",
+  "payload": {},
+  "created_at": "2026-04-01T09:27:08.992694+00:00"
+}
+```
+
+## orchestrator
+```json
+{
+  "event": "finalize",
+  "status": "completed"
+}
+```
+
+## result
+```json
+{
+  "status": "done",
+  "answer": "Да тут я, на месте! А то в горах связи иногда нет, но ты лови ответ от меня, как пастух ловит сигнал телефона в ауле!",
+  "completed_at": "2026-04-01T09:27:08.994005+00:00"
+}
+```

src/app/main.py

@@ -27,7 +27,7 @@ def create_app() -> FastAPI:
         allow_headers=["*"],
     )
 
-    app.include_router(modules.chat.public_router())
+    app.include_router(modules.api.public_router())
     app.include_router(modules.rag.public_router())
     app.include_router(modules.rag.internal_router())
     app.include_router(modules.rag_repo.internal_router())

src/app/modules/agent/intent_router_v2/analysis/ambiguity_detector.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from app.modules.agent.intent_router_v2.analysis.docs_query_signals import DocsQuerySignals
+from app.modules.agent.intent_router_v2.analysis.docs_sub_intent_detector import DocsSubIntentDetector
+
+
+class DocsAmbiguityDetector:
+    _ALLOWED = {
+        "SYSTEM_FLOW_EXPLAIN",
+        "COMPONENT_EXPLAIN",
+        "API_METHOD_EXPLAIN",
+        "ENTITY_EXPLAIN",
+        "RELATED_DOCS_EXPLAIN",
+        "GENERIC_QA",
+    }
+
+    def __init__(
+        self,
+        docs_signals: DocsQuerySignals | None = None,
+        detector: DocsSubIntentDetector | None = None,
+    ) -> None:
+        self._docs_signals = docs_signals or DocsQuerySignals()
+        self._detector = detector or DocsSubIntentDetector()
+        self._natural_entity_markers = ("runtime health", "статус воркера", "состояние runtime", "состояние воркера")
+        self._natural_flow_markers = ("health check runtime", "проверка состояния", "как работает health check", "как происходит проверка")
+
+    def detect(self, query: str, *, intent: str, sub_intent: str) -> dict[str, object]:
+        if intent not in {"DOCUMENTATION_EXPLAIN", "GENERAL_QA"}:
+            return self._result(False, "", sub_intent, [])
+        candidates = [name for name, _ in self._detector.rank_candidates(query, intent="DOCUMENTATION_EXPLAIN") if name in self._ALLOWED]
+        if not candidates:
+            return self._result(False, "", sub_intent, [])
+        top_scores = self._detector.rank_candidates(query, intent="DOCUMENTATION_EXPLAIN")
+        score_map = {name: score for name, score in top_scores}
+        selected_score = int(score_map.get(sub_intent, 0))
+        second_score = int(next((score for name, score in top_scores if name != sub_intent), 0))
+        has_strong_anchor = bool(self._docs_signals.query_anchor_candidates(query)) or self._docs_signals.has_component_like_token(query)
+        if sub_intent == "GENERIC_QA" and has_strong_anchor:
+            return self._result(True, "general_vs_anchor_conflict", sub_intent, candidates[:4])
+        if sub_intent != "GENERIC_QA" and self._looks_overview_like(query) and not has_strong_anchor:
+            return self._result(True, "overview_vs_explain_conflict", sub_intent, candidates[:4])
+        if not has_strong_anchor and self._looks_natural_boundary(query):
+            return self._result(True, "natural_language_boundary", sub_intent, candidates[:4])
+        if selected_score and second_score and selected_score - second_score <= 1 and second_score >= 2:
+            return self._result(True, "small_score_gap", sub_intent, candidates[:4])
+        if not has_strong_anchor and selected_score <= 3 and second_score >= 1:
+            return self._result(True, "weak_deterministic_signal", sub_intent, candidates[:4])
+        return self._result(False, "", sub_intent, candidates[:4])
+
+    def _looks_overview_like(self, query: str) -> bool:
+        text = " ".join((query or "").lower().split())
+        return any(marker in text for marker in ("что есть в документации", "какая структура документации", "что описано", "обзор документации", "с чего начать"))
+
+    def _looks_natural_boundary(self, query: str) -> bool:
+        text = " ".join((query or "").lower().split())
+        return any(marker in text for marker in (*self._natural_entity_markers, *self._natural_flow_markers))
+
+    def _result(self, is_ambiguous: bool, reason: str, selected: str, candidates: list[str]) -> dict[str, object]:
+        return {
+            "is_ambiguous": is_ambiguous,
+            "ambiguity_reason": reason,
+            "deterministic_candidates": list(candidates),
+            "deterministic_primary_candidate": selected,
+        }

src/app/modules/agent/intent_router_v2/analysis/docs_query_signals.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import re
+
+
+class DocsQuerySignals:
+    _ENDPOINT_RE = re.compile(r"(?P<value>/(?:[a-z0-9_-]+|{[a-z0-9_]+})(?:/(?:[a-z0-9_-]+|{[a-z0-9_]+}))*)", re.IGNORECASE)
+    _ENTITY_RE = re.compile(r"(?:entity|сущност[ьи]|модель|объект)\s+(?P<value>[A-Za-z][A-Za-z0-9_-]+(?:\s+[A-Za-z][A-Za-z0-9_-]+)?)", re.IGNORECASE)
+    _COMPONENT_RE = re.compile(r"(?:component|компонент|service|module|модул[ья])\s+(?P<value>[A-Za-z][A-Za-z0-9_-]+)", re.IGNORECASE)
+    _WORKFLOW_RE = re.compile(r"(?:workflow|сценарий|процесс|overview)\s+(?P<value>[A-Za-zА-Яа-я0-9_-]+)", re.IGNORECASE)
+    _DOC_RE = re.compile(r"(?:document|документ|documentation|документац[ияи])\s+(?P<value>[A-Za-zА-Яа-я0-9_.-]+)", re.IGNORECASE)
+    _CAMEL_RE = re.compile(r"\b(?P<value>[A-Z][A-Za-z0-9]+(?:Manager|Worker|Channel|Service|Module|Status|Health)|[A-Z][a-z0-9]+(?:[A-Z][A-Za-z0-9]+)+)\b")
+    _QUOTED_RE = re.compile(r"[\"'«“](?P<value>[^\"'»”]{2,})[\"'»”]")
+    _MULTIWORD_RE = re.compile(r"\b(runtime health|worker status|control plane)\b", re.IGNORECASE)
+
+    def detect_anchor(self, raw: str) -> tuple[str, str | None]:
+        text = raw or ""
+        anchor_patterns = [
+            ("entity", self._ENTITY_RE),
+            ("component", self._COMPONENT_RE),
+            ("workflow", self._WORKFLOW_RE),
+            ("document", self._DOC_RE),
+        ]
+        if not any(ext in text.lower() for ext in (".py", ".ts", ".js", ".java", ".go", ".rb")):
+            anchor_patterns.insert(0, ("endpoint", self._ENDPOINT_RE))
+        for anchor_type, pattern in anchor_patterns:
+            match = pattern.search(text)
+            if match:
+                return anchor_type, str(match.group("value")).strip()
+        if any(marker in text.lower() for marker in ("api", "endpoint", "topic", "тема")):
+            return "topic", None
+        return "none", None
+
+    def has_docs_anchor(self, raw: str) -> bool:
+        anchor_type, _ = self.detect_anchor(raw)
+        return anchor_type != "none"
+
+    def query_entity_candidates(self, raw: str) -> list[str]:
+        text = raw or ""
+        values: list[str] = []
+        for match in self._ENTITY_RE.finditer(text):
+            values.append(match.group("value").strip())
+        for match in self._CAMEL_RE.finditer(text):
+            values.append(match.group("value").strip())
+        for match in self._MULTIWORD_RE.finditer(text):
+            values.append(match.group(1).strip())
+        return self._dedupe(values)
+
+    def query_anchor_candidates(self, raw: str) -> list[str]:
+        text = raw or ""
+        values: list[str] = []
+        for match in self._ENDPOINT_RE.finditer(text):
+            values.append(match.group("value").strip())
+        for match in self._CAMEL_RE.finditer(text):
+            values.append(match.group("value").strip())
+        for match in self._QUOTED_RE.finditer(text):
+            values.append(match.group("value").strip())
+        return self._dedupe(values)
+
+    def has_component_like_token(self, raw: str) -> bool:
+        return bool(self._CAMEL_RE.search(raw or ""))
+
+    def _dedupe(self, values: list[str]) -> list[str]:
+        result: list[str] = []
+        seen: set[str] = set()
+        for value in values:
+            normalized = value.strip()
+            if not normalized:
+                continue
+            key = normalized.lower()
+            if key in seen:
+                continue
+            seen.add(key)
+            result.append(normalized)
+        return result

src/app/modules/agent/intent_router_v2/analysis/docs_sub_intent_detector.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import re
+
+
+class DocsSubIntentDetector:
+    _ENTITY_LIKE_TOKEN_RE = re.compile(r"\b[A-Z][A-Za-z0-9]+(?:Health|Status|State)\b")
+    _CAMEL_ENTITY_CONTEXT_RE = re.compile(r"\b[A-Z][a-z0-9]+(?:[A-Z][A-Za-z0-9]+)+\b")
+    _RELATED_MARKERS = (
+        "найди документацию",
+        "документация по",
+        "где в документации",
+        "что связано",
+        "связанные документы",
+        "что дальше читать",
+        "по каким документам идти",
+        "родительский документ",
+        "дочерние документы",
+        "какие документы",
+        "что еще посмотреть",
+        "где еще описано",
+        "где еще используется",
+        "с чем связан",
+        "какие страницы связаны",
+    )
+    _FLOW_MARKERS = (
+        "цикл",
+        "как работает",
+        "lifecycle",
+        "как происходит",
+        "как устроен",
+        "как устроена",
+        "как проходит",
+        "последовательность",
+        "шаги",
+        "флоу",
+        "flow",
+        "workflow",
+        "сценар",
+        "процесс",
+        "по шагам",
+    )
+    _API_MARKERS = (
+        "api",
+        "endpoint",
+        "method",
+        "route",
+        "handler",
+        "контракт",
+        "request",
+        "response",
+        "webhook",
+        "метод",
+        "эндпоинт",
+        "роут",
+    )
+    _ENTITY_MARKERS = (
+        "сущност",
+        "entity",
+        "модел",
+        "бизнес-объект",
+        "что такое",
+        "что за",
+        "объект",
+        "как используется",
+    )
+    _COMPONENT_MARKERS = (
+        "компонент",
+        "модул",
+        "сервис",
+        "класс",
+        "блок",
+        "подсистем",
+        "часть системы",
+        "роль",
+        "какую роль",
+        "manager",
+        "worker",
+        "channel",
+        "service",
+        "module",
+    )
+    _GENERAL_MARKERS = (
+        "что вообще",
+        "в целом",
+        "с чего начать",
+        "обзор",
+        "какая структура документации",
+        "какая документация есть",
+        "что описано",
+        "что есть в документации",
+        "обзор документации",
+    )
+    _NATURAL_ENTITY_MARKERS = ("runtime health", "health state", "статус воркера", "состояние воркера", "состояние runtime")
+    _NATURAL_FLOW_MARKERS = ("health check runtime", "проверка состояния", "как работает health check", "как происходит проверка")
+
+    def detect(self, raw: str, *, intent: str = "DOCUMENTATION_EXPLAIN") -> str:
+        candidates = self.rank_candidates(raw, intent=intent)
+        return candidates[0][0] if candidates else "COMPONENT_EXPLAIN"
+
+    def rank_candidates(self, raw: str, *, intent: str = "DOCUMENTATION_EXPLAIN") -> list[tuple[str, int]]:
+        source = raw or ""
+        text = " ".join(source.lower().split())
+        if intent == "GENERAL_QA":
+            return [("GENERIC_QA", 100)]
+        if intent == "OPENAPI_GENERATION":
+            return [(self._detect_openapi(text), 100)]
+        if not text:
+            return [("COMPONENT_EXPLAIN", 1)]
+        scores = {
+            "RELATED_DOCS_EXPLAIN": 0,
+            "API_METHOD_EXPLAIN": 0,
+            "ENTITY_EXPLAIN": 0,
+            "COMPONENT_EXPLAIN": 0,
+            "SYSTEM_FLOW_EXPLAIN": 0,
+            "GENERIC_QA": 0,
+        }
+        if any(marker in text for marker in self._RELATED_MARKERS):
+            scores["RELATED_DOCS_EXPLAIN"] += 8
+        if self._has_http_path(text) or any(marker in text for marker in self._API_MARKERS):
+            scores["API_METHOD_EXPLAIN"] += 6
+        if scores["RELATED_DOCS_EXPLAIN"] > 0 and scores["API_METHOD_EXPLAIN"] > 0:
+            scores["API_METHOD_EXPLAIN"] -= 2
+        if any(marker in text for marker in self._ENTITY_MARKERS):
+            scores["ENTITY_EXPLAIN"] += 5
+        if self._has_entity_like_camel_token(source):
+            scores["ENTITY_EXPLAIN"] += 3
+        if self._looks_like_entity_question(text, source):
+            scores["ENTITY_EXPLAIN"] += 2
+        if any(marker in text for marker in self._NATURAL_ENTITY_MARKERS):
+            scores["ENTITY_EXPLAIN"] += 3
+        if any(marker in text for marker in self._COMPONENT_MARKERS):
+            scores["COMPONENT_EXPLAIN"] += 5
+        if any(marker in text for marker in self._FLOW_MARKERS):
+            scores["SYSTEM_FLOW_EXPLAIN"] += 5
+        if any(marker in text for marker in self._NATURAL_FLOW_MARKERS):
+            scores["SYSTEM_FLOW_EXPLAIN"] += 3
+        if any(marker in text for marker in self._GENERAL_MARKERS):
+            scores["GENERIC_QA"] += 6
+        if not any(scores.values()):
+            scores["COMPONENT_EXPLAIN"] = 1
+            scores["GENERIC_QA"] = 1
+        ranked = sorted(scores.items(), key=lambda item: (-item[1], item[0]))
+        return [item for item in ranked if item[1] > 0]
+
+    def _detect_openapi(self, text: str) -> str:
+        markers = ("request", "response", "schema", "parameters", "fragment")
+        if any(marker in text for marker in markers):
+            return "OPENAPI_FRAGMENT_GENERATE"
+        return "OPENAPI_METHOD_GENERATE"
+
+    def _has_http_path(self, text: str) -> bool:
+        return any(token.startswith("/") and len(token) > 1 for token in text.split())
+
+    def _has_entity_like_camel_token(self, raw: str) -> bool:
+        return bool(self._ENTITY_LIKE_TOKEN_RE.search(raw or ""))
+
+    def _looks_like_entity_question(self, text: str, raw: str) -> bool:
+        if not any(marker in text for marker in ("что такое", "что за", "как используется")):
+            return False
+        return bool(self._CAMEL_ENTITY_CONTEXT_RE.search(raw or ""))

src/app/modules/agent/intent_router_v2/analysis/query_plan_builder.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from app.modules.agent.intent_router_v2.analysis.anchor_extractor import AnchorExtractor
 from app.modules.agent.intent_router_v2.analysis.anchor_span_validator import AnchorSpanValidator
 from app.modules.agent.intent_router_v2.analysis.conversation_anchor_builder import ConversationAnchorBuilder
+from app.modules.agent.intent_router_v2.analysis.docs_sub_intent_detector import DocsSubIntentDetector
 from app.modules.agent.intent_router_v2.analysis.keyword_hint_builder import KeywordHintBuilder
 from app.modules.agent.intent_router_v2.analysis.keyword_hint_sanitizer import KeywordHintSanitizer
 from app.modules.agent.intent_router_v2.models import ConversationState, QueryAnchor, QueryPlan
@@ -14,6 +15,11 @@ from app.modules.agent.intent_router_v2.analysis.term_mapping import RuEnTermMap
 
 
 class QueryPlanBuilder:
+    _DOCS_INTENTS = {
+        "DOCUMENTATION_EXPLAIN",
+        "OPENAPI_GENERATION",
+        "GENERAL_QA",
+    }
     _WHY_MARKERS = ("почему", "зачем", "откуда", "из-за чего")
     _NEXT_STEP_MARKERS = ("что дальше", "дальше что", "и что теперь", "продолжай")
     _DOCS_TOPIC_HINTS = {
@@ -35,6 +41,7 @@ class QueryPlanBuilder:
         carryover: ConversationAnchorBuilder | None = None,
         span_validator: AnchorSpanValidator | None = None,
         sub_intent_detector: SubIntentDetector | None = None,
+        docs_sub_intent_detector: DocsSubIntentDetector | None = None,
         negation_detector: NegationDetector | None = None,
     ) -> None:
         self._normalizer = normalizer or QueryNormalizer()
@@ -45,6 +52,7 @@ class QueryPlanBuilder:
         self._carryover = carryover or ConversationAnchorBuilder()
         self._span_validator = span_validator or AnchorSpanValidator()
         self._sub_intent_detector = sub_intent_detector or SubIntentDetector()
+        self._docs_sub_intent_detector = docs_sub_intent_detector or DocsSubIntentDetector()
         self._negation_detector = negation_detector or NegationDetector()
 
     def build(
@@ -54,7 +62,7 @@ class QueryPlanBuilder:
         continue_mode: bool,
         *,
         conversation_mode: str = "START",
-        intent: str = "PROJECT_MISC",
+        intent: str = "FALLBACK",
     ) -> QueryPlan:
         raw = user_query or ""
         normalized = self._normalizer.normalize(raw)
@@ -75,8 +83,10 @@ class QueryPlanBuilder:
         skip_tests = "tests" in negations or is_negative_test_request(raw)
         cleaned_anchors = self._remove_negated_test_terms(skip_tests, merged_anchors)
         sub_intent = self._resolve_sub_intent(sub_intent, raw, cleaned_anchors, intent=intent, negations=negations)
-        if intent == "DOCS_QA":
-            sub_intent = "EXPLAIN"
+        if intent in self._DOCS_INTENTS:
+            sub_intent = self._docs_sub_intent_detector.detect(raw, intent=intent)
+        elif intent == "FALLBACK":
+            sub_intent = "GENERIC_QA"
         expansions = self._expansions(normalized, cleaned_anchors, skip_tests=skip_tests)
         keyword_hints = self._keyword_hints(
             raw,
@@ -95,7 +105,7 @@ class QueryPlanBuilder:
             symbol_candidates = []
             symbol_kind_hint = "unknown"
             doc_scope_hints = []
-        if intent == "DOCS_QA":
+        if intent in self._DOCS_INTENTS:
             symbol_candidates = []
             symbol_kind_hint = "unknown"
             keyword_hints = self._docs_keyword_hints(raw, keyword_hints)
@@ -134,7 +144,7 @@ class QueryPlanBuilder:
         )
         if (
             conversation_mode == "SWITCH"
-            and intent == "DOCS_QA"
+            and intent in self._DOCS_INTENTS
             and not has_user_file
             and not has_user_symbol
             and state.active_symbol
@@ -186,7 +196,7 @@ class QueryPlanBuilder:
         if skip_tests:
             values = [value for value in values if not is_test_related_token(value)]
         sanitized = self._keyword_hint_sanitizer.sanitize(raw, anchors, values)
-        if intent == "DOCS_QA" and not sanitized:
+        if intent in self._DOCS_INTENTS and not sanitized:
             fallback = list(dict.fromkeys([*self._expansions(normalized, anchors, skip_tests=skip_tests)]))
             sanitized = fallback[:3]
             if state.active_symbol and state.active_symbol not in sanitized:
@@ -295,7 +305,7 @@ class QueryPlanBuilder:
         return result[:12]
 
     def _doc_scope_hints(self, intent: str, raw: str, keyword_hints: list[str], path_hints: list[str]) -> list[str]:
-        if intent != "DOCS_QA":
+        if intent not in self._DOCS_INTENTS:
             return []
         values = list(path_hints)
         for candidate in ("README*", "docs/**", "**/*.md"):

src/app/modules/agent/intent_router_v2/factory.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from app.modules.agent.llm import AgentLlmService
 from app.modules.agent.llm.prompt_loader import PromptLoader
 from app.modules.agent.intent_router_v2.intent.classifier import IntentClassifierV2
+from app.modules.agent.intent_router_v2.intent.llm_disambiguator import DocsLlmDisambiguator
 from app.modules.agent.intent_router_v2.router import IntentRouterV2
 from app.modules.shared.env_loader import load_workspace_env
 from app.modules.shared.gigachat.client import GigaChatClient
@@ -19,4 +20,8 @@ class GigaChatIntentRouterFactory:
         prompt_loader = PromptLoader()
         llm = AgentLlmService(client=client, prompts=prompt_loader)
         classifier = IntentClassifierV2(llm=llm)
-        return IntentRouterV2(classifier=classifier)
+        return IntentRouterV2(
+            classifier=classifier,
+            llm_disambiguator=DocsLlmDisambiguator(llm),
+            enable_llm_disambiguation=True,
+        )

src/app/modules/agent/intent_router_v2/intent/classifier.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import re
 
+from app.modules.agent.intent_router_v2.analysis.docs_query_signals import DocsQuerySignals
 from app.modules.agent.intent_router_v2.models import ConversationState, IntentDecision
 from app.modules.agent.intent_router_v2.protocols import TextGenerator
 from app.modules.agent.intent_router_v2.analysis.test_signals import has_test_focus
@@ -23,6 +24,73 @@ class IntentClassifierV2:
         "write documentation",
     )
     _DOCS_MARKERS = ("документац", "readme", "docs/", ".md", "spec", "runbook", "markdown")
+    _OPENAPI_MARKERS = ("openapi", "swagger", "yaml", "spec", "schema")
+    _OPENAPI_EXTENDED_MARKERS = ("request body", "response schema", "request schema", "response body")
+    _DOCS_RELATED_MARKERS = (
+        "что связано",
+        "связанные документы",
+        "что дальше читать",
+        "по каким документам идти",
+        "родительский документ",
+        "дочерние документы",
+        "какие документы",
+        "что еще посмотреть",
+        "где еще описано",
+        "где еще используется",
+        "с чем связан",
+        "какие страницы связаны",
+        "документация по",
+        "найди",
+        "где описан",
+        "где в документации",
+        "покажи документы",
+        "после этого",
+    )
+    _DOCS_EXPLAIN_MARKERS = ("объясни", "как работает", "что делает", "что такое")
+    _DOCS_FLOW_MARKERS = (
+        "цикл",
+        "сценар",
+        "процесс",
+        "происходит",
+        "последовательность",
+        "шаги",
+        "как работает процесс",
+        "как происходит",
+        "как устроен процесс",
+        "workflow",
+        "flow",
+        "lifecycle",
+        "жизненный цикл",
+    )
+    _DOCS_COMPONENT_MARKERS = (
+        "компонент",
+        "модул",
+        "подсистем",
+        "часть системы",
+        "блок",
+        "роль",
+        "какую роль",
+        "что делает",
+        "как работает компонент",
+        "как устроен",
+    )
+    _DOCS_ENTITY_MARKERS = ("сущност", "entity", "бизнес-объект", "объект", "как используется", "что такое")
+    _DOCS_API_MARKERS = ("api", "endpoint", "эндпоинт", "ручк", "request", "response")
+    _GENERAL_QA_MARKERS = (
+        "помоги понять",
+        "с чего начать",
+        "как начать",
+        "куда смотреть",
+        "что тут важно",
+        "что вообще",
+        "в целом",
+        "обзор",
+        "какая структура документации",
+        "структура документации",
+        "какая документация есть",
+        "что описано в документации",
+        "что есть по сервису",
+    )
     _CODE_MARKERS = (
         "по коду",
         "код",
@@ -45,6 +113,7 @@ class IntentClassifierV2:
 
     def __init__(self, llm: TextGenerator | None = None) -> None:
         self._llm = llm
+        self._docs_signals = DocsQuerySignals()
 
     def classify(self, user_query: str, conversation_state: ConversationState) -> IntentDecision:
         deterministic = self._deterministic(user_query)
@@ -53,17 +122,27 @@ class IntentClassifierV2:
         llm_decision = self._classify_with_llm(user_query, conversation_state)
         if llm_decision:
             return llm_decision
-        return IntentDecision(intent="PROJECT_MISC", confidence=0.55, reason="fallback_project_misc")
+        return IntentDecision(intent="FALLBACK", confidence=0.55, reason="fallback")
 
     def _deterministic(self, user_query: str) -> IntentDecision | None:
         text = " ".join((user_query or "").lower().split())
         if any(marker in text for marker in self._GENERATE_DOCS_MARKERS):
             return IntentDecision(intent="GENERATE_DOCS_FROM_CODE", confidence=0.97, reason="deterministic_generate_docs")
+        if any(marker in text for marker in (*self._OPENAPI_MARKERS, *self._OPENAPI_EXTENDED_MARKERS)):
+            return IntentDecision(intent="OPENAPI_GENERATION", confidence=0.98, reason="deterministic_openapi")
+        if self._is_general_docs_qa(text):
+            return IntentDecision(intent="GENERAL_QA", confidence=0.76, reason="deterministic_general_docs")
+        if self._is_docs_explain(text, user_query):
+            return IntentDecision(intent="DOCUMENTATION_EXPLAIN", confidence=0.91, reason="deterministic_docs_explain")
+        if self._is_related_docs(text):
+            return IntentDecision(intent="DOCUMENTATION_EXPLAIN", confidence=0.9, reason="deterministic_docs_related")
+        if not has_test_focus(text) and self._docs_signals.has_component_like_token(user_query) and not self._is_general_docs_qa(text):
+            return IntentDecision(intent="DOCUMENTATION_EXPLAIN", confidence=0.82, reason="deterministic_docs_component_anchor")
         if self._looks_like_docs_question(text):
-            return IntentDecision(intent="DOCS_QA", confidence=0.9, reason="deterministic_docs")
+            return IntentDecision(intent="DOCUMENTATION_EXPLAIN", confidence=0.9, reason="deterministic_docs")
         if self._looks_like_code_question(user_query, text):
             return IntentDecision(intent="CODE_QA", confidence=0.9, reason="deterministic_code")
-        return None
+        return IntentDecision(intent="GENERAL_QA", confidence=0.62, reason="deterministic_general")
 
     def _classify_with_llm(self, user_query: str, conversation_state: ConversationState) -> IntentDecision | None:
         if self._llm is None:
@@ -73,7 +152,13 @@ class IntentClassifierV2:
                 "message": user_query,
                 "active_intent": conversation_state.active_intent,
                 "last_query": conversation_state.last_query,
-                "allowed_intents": ["CODE_QA", "DOCS_QA", "GENERATE_DOCS_FROM_CODE", "PROJECT_MISC"],
+                "allowed_intents": [
+                    "CODE_QA",
+                    "DOCUMENTATION_EXPLAIN",
+                    "OPENAPI_GENERATION",
+                    "GENERAL_QA",
+                    "GENERATE_DOCS_FROM_CODE",
+                ],
             },
             ensure_ascii=False,
         )
@@ -93,10 +178,19 @@ class IntentClassifierV2:
         except json.JSONDecodeError:
             return None
         intent = str(payload.get("intent") or "").strip().upper()
-        if intent not in {"CODE_QA", "DOCS_QA", "GENERATE_DOCS_FROM_CODE", "PROJECT_MISC"}:
+        if intent not in {
+            "CODE_QA",
+            "DOCUMENTATION_EXPLAIN",
+            "OPENAPI_GENERATION",
+            "GENERAL_QA",
+            "GENERATE_DOCS_FROM_CODE",
+            "FALLBACK",
+        }:
             return None
+        sub_intent = str(payload.get("sub_intent") or "").strip() or None
         return IntentDecision(
             intent=intent,
+            sub_intent=sub_intent,
             confidence=float(payload.get("confidence") or 0.7),
             reason=str(payload.get("reason") or "llm").strip() or "llm",
         )
@@ -112,8 +206,33 @@ class IntentClassifierV2:
     def _looks_like_docs_question(self, text: str) -> bool:
         if self._has_code_file_path(text):
             return False
+        if self._is_general_docs_qa(text):
+            return False
+        return self._has_docs_context(text) or self._has_docs_subject(text)
+
+    def _has_docs_context(self, text: str) -> bool:
         return any(marker in text for marker in self._DOCS_MARKERS)
 
+    def _is_docs_discovery(self, text: str) -> bool:
+        return self._is_related_docs(text)
+
+    def _is_related_docs(self, text: str) -> bool:
+        return any(marker in text for marker in self._DOCS_RELATED_MARKERS)
+
+    def _is_docs_explain(self, text: str, user_query: str) -> bool:
+        if not any(marker in text for marker in self._DOCS_EXPLAIN_MARKERS):
+            return False
+        return self._docs_signals.has_docs_anchor(user_query) or self._has_docs_subject(text)
+
+    def _has_docs_subject(self, text: str) -> bool:
+        return any(
+            marker in text
+            for marker in (*self._DOCS_FLOW_MARKERS, *self._DOCS_COMPONENT_MARKERS, *self._DOCS_ENTITY_MARKERS, *self._DOCS_API_MARKERS)
+        )
+
+    def _is_general_docs_qa(self, text: str) -> bool:
+        return any(marker in text for marker in self._GENERAL_QA_MARKERS)
+
     def _looks_like_code_question(self, raw_text: str, lowered: str) -> bool:
         if self._has_code_file_path(raw_text):
             return True
@@ -123,8 +242,6 @@ class IntentClassifierV2:
             return False
         if any(marker in lowered for marker in self._CODE_MARKERS):
             return True
-        if re.search(r"\b[A-Z][A-Za-z0-9_]{2,}(?:\.[A-Za-z_][A-Za-z0-9_]*)*\b", raw_text or ""):
-            return True
         return bool(re.search(r"\b[a-z_][A-Za-z0-9_]{2,}\(", raw_text or ""))
 
     def _has_code_file_path(self, text: str) -> bool:

src/app/modules/agent/intent_router_v2/intent/conversation_policy.py

@@ -52,8 +52,22 @@ class ConversationPolicy:
         text = " ".join((user_query or "").lower().split())
         if candidate_intent == "GENERATE_DOCS_FROM_CODE":
             return True
-        if candidate_intent == "DOCS_QA":
+        if candidate_intent in {
+            "DOCUMENTATION_EXPLAIN",
+            "OPENAPI_GENERATION",
+            "GENERAL_QA",
+            "DOCUMENTATION_DISCOVERY",
+            "DOCUMENTATION_NAVIGATION",
+            "OPENAPI_FROM_DOCUMENTATION",
+        }:
             return any(signal in text for signal in self._DOCS_SIGNALS)
-        if candidate_intent == "CODE_QA" and active_intent == "DOCS_QA":
+        if candidate_intent == "CODE_QA" and active_intent in {
+            "DOCUMENTATION_EXPLAIN",
+            "OPENAPI_GENERATION",
+            "GENERAL_QA",
+            "DOCUMENTATION_DISCOVERY",
+            "DOCUMENTATION_NAVIGATION",
+            "OPENAPI_FROM_DOCUMENTATION",
+        }:
             return any(signal in text for signal in self._CODE_SIGNALS)
         return False

src/app/modules/agent/intent_router_v2/intent/graph_id_resolver.py

@@ -4,9 +4,14 @@ from __future__ import annotations
 class GraphIdResolver:
     _GRAPH_MAP = {
         "CODE_QA": "CodeQAGraph",
-        "DOCS_QA": "DocsQAGraph",
+        "DOCUMENTATION_EXPLAIN": "DocsQAGraph",
+        "OPENAPI_GENERATION": "DocsQAGraph",
+        "GENERAL_QA": "DocsQAGraph",
+        "DOCUMENTATION_DISCOVERY": "DocsQAGraph",
+        "DOCUMENTATION_NAVIGATION": "DocsQAGraph",
+        "OPENAPI_FROM_DOCUMENTATION": "DocsQAGraph",
         "GENERATE_DOCS_FROM_CODE": "GenerateDocsFromCodeGraph",
-        "PROJECT_MISC": "ProjectMiscGraph",
+        "FALLBACK": "DocsQAGraph",
     }
 
     def resolve(self, intent: str) -> str:

src/app/modules/agent/intent_router_v2/intent/llm_disambiguator.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import json
+
+from app.modules.agent.intent_router_v2.protocols import TextGenerator
+
+
+class DocsLlmDisambiguator:
+    _ALLOWED = {
+        "SYSTEM_FLOW_EXPLAIN",
+        "COMPONENT_EXPLAIN",
+        "API_METHOD_EXPLAIN",
+        "ENTITY_EXPLAIN",
+        "RELATED_DOCS_EXPLAIN",
+        "GENERIC_QA",
+        "OPENAPI_METHOD_GENERATE",
+        "OPENAPI_FRAGMENT_GENERATE",
+    }
+
+    def __init__(self, llm: TextGenerator) -> None:
+        self._llm = llm
+
+    def choose(self, payload: dict[str, object]) -> dict[str, str] | None:
+        raw = self._llm.generate(
+            "rag_docs_router_disambiguation_v1",
+            json.dumps(payload, ensure_ascii=False),
+            log_context="rag.intent_router_v2.disambiguate",
+        ).strip()
+        parsed = self._parse(raw)
+        if parsed is None:
+            return None
+        return parsed
+
+    def _parse(self, raw: str) -> dict[str, str] | None:
+        candidate = self._strip_code_fence(raw)
+        try:
+            payload = json.loads(candidate)
+        except json.JSONDecodeError:
+            return None
+        sub_intent = str(payload.get("sub_intent") or "").strip()
+        if sub_intent not in self._ALLOWED:
+            return None
+        return {
+            "sub_intent": sub_intent,
+            "reason": str(payload.get("reason") or "").strip(),
+            "confidence": str(payload.get("confidence") or "").strip(),
+        }
+
+    def _strip_code_fence(self, text: str) -> str:
+        if not text.startswith("```"):
+            return text
+        lines = text.splitlines()
+        if len(lines) >= 3 and lines[-1].strip() == "```":
+            return "\n".join(lines[1:-1]).strip()
+        return text

src/app/modules/agent/intent_router_v2/models.py

@@ -6,13 +6,25 @@ from typing import Literal
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
-IntentType = Literal["CODE_QA", "DOCS_QA", "GENERATE_DOCS_FROM_CODE", "PROJECT_MISC"]
+IntentType = Literal[
+    "CODE_QA",
+    "DOCUMENTATION_EXPLAIN",
+    "OPENAPI_GENERATION",
+    "GENERAL_QA",
+    "GENERATE_DOCS_FROM_CODE",
+    "FALLBACK",  # deprecated alias, prefer GENERAL_QA
+    "DOCUMENTATION_DISCOVERY",  # deprecated alias, prefer DOCUMENTATION_EXPLAIN
+    "DOCUMENTATION_NAVIGATION",  # deprecated alias, prefer DOCUMENTATION_EXPLAIN
+    "OPENAPI_FROM_DOCUMENTATION",  # deprecated alias, prefer OPENAPI_GENERATION
+]
 ConversationMode = Literal["START", "CONTINUE", "SWITCH", "FOLLOWUP_LIKELY"]
-RetrievalProfile = Literal["code", "docs"]
+RetrievalProfile = Literal["code", "docs", "fallback"]
 AnchorType = Literal["FILE_PATH", "SYMBOL", "DOC_REF", "KEY_TERM"]
 AnchorSource = Literal["user_text", "conversation_state", "heuristic"]
 SymbolKindHint = Literal["class", "function", "method", "module", "unknown"]
 SymbolResolutionStatus = Literal["not_requested", "pending", "resolved", "ambiguous", "not_found"]
+MatchedAnchorType = Literal["endpoint", "entity", "component", "workflow", "topic", "document", "none"]
+MatchedIntentSource = Literal["deterministic", "llm"]
 _INLINE_CODE_RE = re.compile(r"`([^`]*)`")
 _CODE_SYMBOL_RE = re.compile(r"\b([A-Za-z_][A-Za-z0-9_]{2,})\b")
 
@@ -106,6 +118,7 @@ class DocsRetrievalFilters(BaseModel):
     path_scope: list[str] = Field(default_factory=list)
     doc_kinds: list[str] = Field(default_factory=list)
     doc_language: list[str] = Field(default_factory=list)
+    doc_type: str | None = None
 
 
 class HybridRetrievalFilters(BaseModel):
@@ -116,6 +129,7 @@ class HybridRetrievalFilters(BaseModel):
     language: list[str] = Field(default_factory=list)
     doc_kinds: list[str] = Field(default_factory=list)
     doc_language: list[str] = Field(default_factory=list)
+    doc_type: str | None = None
 
 
 class RetrievalSpec(BaseModel):
@@ -149,6 +163,20 @@ class IntentRouterResult(BaseModel):
     retrieval_constraints: RetrievalConstraints = Field(default_factory=RetrievalConstraints)
     symbol_resolution: SymbolResolution = Field(default_factory=SymbolResolution)
     evidence_policy: EvidencePolicy
+    matched_anchor_type: MatchedAnchorType = "none"
+    matched_anchor_value: str | None = None
+    matched_intent_source: MatchedIntentSource = "deterministic"
+    routing_reason: str = ""
+    routing_mode: str = "deterministic"
+    is_ambiguous: bool = False
+    ambiguity_reason: str = ""
+    deterministic_candidates: list[str] = Field(default_factory=list)
+    deterministic_selected_sub_intent: str = ""
+    llm_router_used: bool = False
+    llm_router_selected_sub_intent: str = ""
+    llm_router_reason: str = ""
+    llm_router_confidence: str = ""
+    llm_router_error: str = ""
 
 
 class ConversationState(BaseModel):
@@ -202,6 +230,7 @@ class IntentDecision(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     intent: IntentType
+    sub_intent: str | None = None
     confidence: float = 0.0
     reason: str = ""
 

src/app/modules/agent/intent_router_v2/readme.md

@@ -22,8 +22,8 @@
   - `QueryAnchor`
 
 ## Контракт результата `IntentRouterResult`
-- `intent`: `CODE_QA | DOCS_QA | GENERATE_DOCS_FROM_CODE | PROJECT_MISC`
-- `retrieval_profile`: `code | docs`
+- `intent`: `CODE_QA | DOCUMENTATION_EXPLAIN | GENERATE_DOCS_FROM_CODE | FALLBACK`
+- `retrieval_profile`: `code | docs | fallback`
 - `graph_id`: целевой graph в agent runtime
 - `query_plan`: нормализованный запрос, anchors, sub-intent, keyword/path/doc hints
 - `retrieval_spec`: слои + фильтры для RAG

src/app/modules/agent/intent_router_v2/retrieval_planning/evidence_policy_factory.py

@@ -25,8 +25,17 @@ class EvidencePolicyFactory:
             if "tests" in negations_set and not has_user_anchor:
                 return EvidencePolicy(require_def=True, require_flow=False, require_spec=False, allow_answer_without_evidence=False)
             return EvidencePolicy(require_def=True, require_flow=True, require_spec=False, allow_answer_without_evidence=False)
-        if intent == "DOCS_QA":
+        if intent in {
+            "DOCUMENTATION_EXPLAIN",
+            "OPENAPI_GENERATION",
+            "GENERAL_QA",
+            "DOCUMENTATION_DISCOVERY",
+            "DOCUMENTATION_NAVIGATION",
+            "OPENAPI_FROM_DOCUMENTATION",
+        }:
             return EvidencePolicy(require_def=False, require_flow=False, require_spec=True, allow_answer_without_evidence=False)
+        if intent == "FALLBACK":
+            return EvidencePolicy(require_def=False, require_flow=False, require_spec=False, allow_answer_without_evidence=True)
         if intent == "GENERATE_DOCS_FROM_CODE":
             return EvidencePolicy(require_def=True, require_flow=False, require_spec=False, allow_answer_without_evidence=False)
         return EvidencePolicy(require_def=False, require_flow=False, require_spec=False, allow_answer_without_evidence=True)

src/app/modules/agent/intent_router_v2/retrieval_planning/retrieval_constraints_factory.py

@@ -28,7 +28,7 @@ class RetrievalConstraintsFactory:
         anchors: list[QueryAnchor],
         path_scope: list[str],
     ) -> RetrievalConstraints:
-        if retrieval_profile == "docs":
+        if retrieval_profile in {"docs", "fallback"}:
             return self._docs_constraints(sub_intent=sub_intent, path_scope=path_scope)
         return self._code_constraints(sub_intent=sub_intent, raw_query=raw_query, anchors=anchors)
 

src/app/modules/agent/intent_router_v2/retrieval_planning/retrieval_filter_builder.py

@@ -35,6 +35,7 @@ class RetrievalFilterBuilder:
                 path_scope=path_scope,
                 doc_kinds=self._doc_kinds(anchors, raw_query),
                 doc_language=[],
+                doc_type=self._doc_type(sub_intent),
             )
         if domains == ["CODE"]:
             return CodeRetrievalFilters(
@@ -48,6 +49,7 @@ class RetrievalFilterBuilder:
             language=list(repo_context.languages),
             doc_kinds=self._doc_kinds(anchors, raw_query),
             doc_language=[],
+            doc_type=self._doc_type(sub_intent),
         )
 
     def _test_policy(self, raw_query: str, anchors: list[QueryAnchor], *, sub_intent: str) -> str:
@@ -104,6 +106,11 @@ class RetrievalFilterBuilder:
             kinds.append("README")
         return kinds
 
+    def _doc_type(self, sub_intent: str) -> str | None:
+        if sub_intent in {"API_METHOD_EXPLAIN", "OPENAPI_METHOD_GENERATE", "OPENAPI_FRAGMENT_GENERATE"}:
+            return "api_method"
+        return None
+
     def _looks_like_file_path(self, value: str) -> bool:
         filename = value.rsplit("/", 1)[-1]
         return "." in filename

src/app/modules/agent/intent_router_v2/retrieval_planning/retrieval_spec_factory.py

@@ -15,11 +15,19 @@ class RetrievalSpecFactory:
             (RagLayer.CODE_DEPENDENCY_GRAPH, 6),
             (RagLayer.CODE_ENTRYPOINTS, 6),
         ],
-        "DOCS_QA": [
-            (RagLayer.DOCS_MODULE_CATALOG, 5),
+        "DOCUMENTATION_EXPLAIN": [
+            (RagLayer.DOCS_DOCUMENT_CATALOG, 6),
             (RagLayer.DOCS_FACT_INDEX, 8),
-            (RagLayer.DOCS_SECTION_INDEX, 8),
-            (RagLayer.DOCS_POLICY_INDEX, 4),
+            (RagLayer.DOCS_RELATION_GRAPH, 6),
+        ],
+        "OPENAPI_GENERATION": [
+            (RagLayer.DOCS_DOCUMENT_CATALOG, 8),
+            (RagLayer.DOCS_FACT_INDEX, 8),
+            (RagLayer.DOCS_DOC_CHUNKS, 6),
+        ],
+        "GENERAL_QA": [
+            (RagLayer.DOCS_DOCUMENT_CATALOG, 4),
+            (RagLayer.DOCS_DOC_CHUNKS, 4),
         ],
         "GENERATE_DOCS_FROM_CODE": [
             (RagLayer.CODE_SYMBOL_CATALOG, 12),
@@ -27,24 +35,26 @@ class RetrievalSpecFactory:
             (RagLayer.CODE_SOURCE_CHUNKS, 12),
             (RagLayer.CODE_ENTRYPOINTS, 6),
         ],
-        "PROJECT_MISC": [
-            (RagLayer.DOCS_MODULE_CATALOG, 4),
-            (RagLayer.DOCS_SECTION_INDEX, 6),
-            (RagLayer.CODE_SYMBOL_CATALOG, 4),
-            (RagLayer.CODE_SOURCE_CHUNKS, 4),
+        "FALLBACK": [
+            (RagLayer.DOCS_DOCUMENT_CATALOG, 4),
+            (RagLayer.DOCS_DOC_CHUNKS, 6),
         ],
     }
     _DOMAINS = {
         "CODE_QA": ["CODE"],
-        "DOCS_QA": ["DOCS"],
+        "DOCUMENTATION_EXPLAIN": ["DOCS"],
+        "OPENAPI_GENERATION": ["DOCS"],
+        "GENERAL_QA": ["DOCS"],
         "GENERATE_DOCS_FROM_CODE": ["CODE"],
-        "PROJECT_MISC": ["CODE", "DOCS"],
+        "FALLBACK": ["DOCS"],
     }
     _RERANK = {
         "CODE_QA": "code",
-        "DOCS_QA": "docs",
+        "DOCUMENTATION_EXPLAIN": "docs",
+        "OPENAPI_GENERATION": "docs",
+        "GENERAL_QA": "fallback",
         "GENERATE_DOCS_FROM_CODE": "generate",
-        "PROJECT_MISC": "project",
+        "FALLBACK": "fallback",
     }
     _OPEN_FILE_LAYERS = [
         (RagLayer.CODE_SOURCE_CHUNKS, 12),
@@ -77,9 +87,40 @@ class RetrievalSpecFactory:
         (RagLayer.CODE_SYMBOL_CATALOG, 6),
         (RagLayer.CODE_SOURCE_CHUNKS, 4),
     ]
-    _DOCS_SCOPED_LAYERS = [
-        (RagLayer.DOCS_SECTION_INDEX, 8),
+    _DOCS_SCOPED_LAYERS = [(RagLayer.DOCS_DOC_CHUNKS, 8)]
+    _DOCS_SYSTEM_FLOW_LAYERS = [
+        (RagLayer.DOCS_WORKFLOW_INDEX, 8),
+        (RagLayer.DOCS_RELATION_GRAPH, 8),
+        (RagLayer.DOCS_DOCUMENT_CATALOG, 4),
+        (RagLayer.DOCS_DOC_CHUNKS, 4),
+    ]
+    _DOCS_COMPONENT_LAYERS = [
         (RagLayer.DOCS_FACT_INDEX, 8),
+        (RagLayer.DOCS_RELATION_GRAPH, 8),
+        (RagLayer.DOCS_DOCUMENT_CATALOG, 4),
+        (RagLayer.DOCS_DOC_CHUNKS, 4),
+    ]
+    _DOCS_API_METHOD_LAYERS = [
+        (RagLayer.DOCS_FACT_INDEX, 8),
+        (RagLayer.DOCS_WORKFLOW_INDEX, 8),
+        (RagLayer.DOCS_DOCUMENT_CATALOG, 4),
+        (RagLayer.DOCS_DOC_CHUNKS, 4),
+    ]
+    _DOCS_ENTITY_LAYERS = [
+        (RagLayer.DOCS_ENTITY_CATALOG, 8),
+        (RagLayer.DOCS_RELATION_GRAPH, 8),
+        (RagLayer.DOCS_DOCUMENT_CATALOG, 4),
+        (RagLayer.DOCS_DOC_CHUNKS, 4),
+    ]
+    _DOCS_RELATED_LAYERS = [
+        (RagLayer.DOCS_RELATION_GRAPH, 8),
+        (RagLayer.DOCS_DOCUMENT_CATALOG, 4),
+        (RagLayer.DOCS_DOC_CHUNKS, 3),
+    ]
+    _DOCS_OPENAPI_LAYERS = [
+        (RagLayer.DOCS_DOCUMENT_CATALOG, 8),
+        (RagLayer.DOCS_FACT_INDEX, 8),
+        (RagLayer.DOCS_DOC_CHUNKS, 6),
     ]
 
     def __init__(
@@ -113,9 +154,9 @@ class RetrievalSpecFactory:
             conversation_mode=conversation_mode,
             sub_intent=sub_intent,
         )
-        if intent == "DOCS_QA" and list(getattr(filters, "path_scope", []) or []):
+        if intent == "DOCUMENTATION_EXPLAIN" and list(getattr(filters, "path_scope", []) or []):
             scoped_map = dict(self._LAYERS)
-            scoped_map["DOCS_QA"] = list(self._DOCS_SCOPED_LAYERS)
+            scoped_map[intent] = list(self._DOCS_SCOPED_LAYERS)
             layer_queries = self._layer_builder.build(intent, repo_context, domains=domains, layers_map=scoped_map)
         return RetrievalSpec(
             domains=domains,
@@ -135,6 +176,8 @@ class RetrievalSpecFactory:
         sub_intent: str,
         anchors: list[QueryAnchor],
     ) -> dict[str, list[tuple[str, int]]]:
+        if intent in {"DOCUMENTATION_EXPLAIN", "OPENAPI_GENERATION", "GENERAL_QA"}:
+            return self._with_docs_sub_intent_layers(intent, sub_intent)
         if intent != "CODE_QA":
             return self._LAYERS
         layers_map = dict(self._LAYERS)
@@ -158,6 +201,26 @@ class RetrievalSpecFactory:
             ]
         return layers_map
 
+    def _with_docs_sub_intent_layers(self, intent: str, sub_intent: str) -> dict[str, list[tuple[str, int]]]:
+        layers_map = dict(self._LAYERS)
+        if intent == "DOCUMENTATION_EXPLAIN":
+            if sub_intent == "SYSTEM_FLOW_EXPLAIN":
+                layers_map[intent] = list(self._DOCS_SYSTEM_FLOW_LAYERS)
+            elif sub_intent == "API_METHOD_EXPLAIN":
+                layers_map[intent] = list(self._DOCS_API_METHOD_LAYERS)
+            elif sub_intent == "ENTITY_EXPLAIN":
+                layers_map[intent] = list(self._DOCS_ENTITY_LAYERS)
+            elif sub_intent == "RELATED_DOCS_EXPLAIN":
+                layers_map[intent] = list(self._DOCS_RELATED_LAYERS)
+            else:
+                layers_map[intent] = list(self._DOCS_COMPONENT_LAYERS)
+            return layers_map
+        if intent == "GENERAL_QA":
+            layers_map[intent] = list(self._LAYERS["GENERAL_QA"])
+            return layers_map
+        layers_map[intent] = list(self._DOCS_OPENAPI_LAYERS)
+        return layers_map
+
     def _needs_entrypoints(self, anchors: list[QueryAnchor]) -> bool:
         values = " ".join(anchor.value.lower() for anchor in anchors if anchor.type in {"KEY_TERM", "SYMBOL"})
         markers = ("entrypoint", "endpoint", "вызыва", "поток", "flow", "запуска")

src/app/modules/agent/intent_router_v2/router.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
+from app.modules.agent.intent_router_v2.analysis.ambiguity_detector import DocsAmbiguityDetector
 from app.modules.agent.intent_router_v2.intent.classifier import IntentClassifierV2
+from app.modules.agent.intent_router_v2.analysis.docs_query_signals import DocsQuerySignals
+from app.modules.agent.intent_router_v2.intent.llm_disambiguator import DocsLlmDisambiguator
 from app.modules.agent.intent_router_v2.intent.conversation_policy import ConversationPolicy
 from app.modules.agent.intent_router_v2.retrieval_planning.evidence_policy_factory import EvidencePolicyFactory
 from app.modules.agent.intent_router_v2.intent.graph_id_resolver import GraphIdResolver
@@ -22,6 +25,9 @@ class IntentRouterV2:
         evidence_factory: EvidencePolicyFactory | None = None,
         graph_resolver: GraphIdResolver | None = None,
         logger: IntentRouterLogger | None = None,
+        ambiguity_detector: DocsAmbiguityDetector | None = None,
+        llm_disambiguator: DocsLlmDisambiguator | None = None,
+        enable_llm_disambiguation: bool = False,
     ) -> None:
         self._classifier = classifier or IntentClassifierV2()
         self._conversation_policy = conversation_policy or ConversationPolicy()
@@ -31,6 +37,10 @@ class IntentRouterV2:
         self._evidence_factory = evidence_factory or EvidencePolicyFactory()
         self._graph_resolver = graph_resolver or GraphIdResolver()
         self._logger = logger or IntentRouterLogger()
+        self._ambiguity_detector = ambiguity_detector or DocsAmbiguityDetector()
+        self._llm_disambiguator = llm_disambiguator
+        self._enable_llm_disambiguation = enable_llm_disambiguation
+        self._docs_signals = DocsQuerySignals()
 
     def route(
         self,
@@ -51,6 +61,14 @@ class IntentRouterV2:
             conversation_mode=conversation_mode,
             intent=intent,
         )
+        ambiguity = self._ambiguity_detector.detect(user_query, intent=intent, sub_intent=query_plan.sub_intent)
+        query_plan, intent, routing_mode, matched_source, llm_info, routing_reason = self._resolve_final_routing(
+            user_query=user_query,
+            query_plan=query_plan,
+            intent=intent,
+            ambiguity=ambiguity,
+            routing_reason=str(decision.reason or ""),
+        )
         retrieval_spec = self._retrieval_factory.build(
             intent,
             query_plan.anchors,
@@ -61,6 +79,7 @@ class IntentRouterV2:
             sub_intent=query_plan.sub_intent,
         )
         path_scope = list(getattr(retrieval_spec.filters, "path_scope", []) or [])
+        matched_anchor_type, matched_anchor_value = self._docs_signals.detect_anchor(user_query)
         result = IntentRouterResult(
             intent=intent,
             retrieval_profile=retrieval_profile,
@@ -86,6 +105,20 @@ class IntentRouterV2:
                 negations=query_plan.negations,
                 has_user_anchor=any(anchor.source == "user_text" for anchor in query_plan.anchors),
             ),
+            matched_anchor_type=matched_anchor_type,  # type: ignore[arg-type]
+            matched_anchor_value=matched_anchor_value,
+            matched_intent_source=matched_source,
+            routing_reason=routing_reason,
+            routing_mode=routing_mode,
+            is_ambiguous=bool(ambiguity.get("is_ambiguous")),
+            ambiguity_reason=str(ambiguity.get("ambiguity_reason") or ""),
+            deterministic_candidates=list(ambiguity.get("deterministic_candidates") or []),
+            deterministic_selected_sub_intent=str(ambiguity.get("deterministic_primary_candidate") or query_plan.sub_intent),
+            llm_router_used=bool(llm_info.get("used")),
+            llm_router_selected_sub_intent=str(llm_info.get("sub_intent") or ""),
+            llm_router_reason=str(llm_info.get("reason") or ""),
+            llm_router_confidence=str(llm_info.get("confidence") or ""),
+            llm_router_error=str(llm_info.get("error") or ""),
         )
         self._logger.log_result(result)
         return result
@@ -96,7 +129,7 @@ class IntentRouterV2:
         sub_intent: str,
         symbol_candidates: list[str],
     ) -> SymbolResolution:
-        if retrieval_profile == "docs":
+        if retrieval_profile in {"docs", "fallback"}:
             return SymbolResolution(status="not_requested")
         if sub_intent == "OPEN_FILE":
             return SymbolResolution(status="not_requested")
@@ -110,6 +143,44 @@ class IntentRouterV2:
         )
 
     def _resolve_retrieval_profile(self, intent: str) -> str:
-        if intent == "DOCS_QA":
+        if intent in {"DOCUMENTATION_EXPLAIN", "OPENAPI_GENERATION", "GENERAL_QA"}:
             return "docs"
+        if intent == "FALLBACK":
+            return "fallback"
         return "code"
+
+    def _resolve_final_routing(
+        self,
+        *,
+        user_query: str,
+        query_plan,
+        intent: str,
+        ambiguity: dict[str, object],
+        routing_reason: str,
+    ):
+        if not bool(ambiguity.get("is_ambiguous")):
+            source = "llm" if not str(routing_reason).startswith("deterministic_") else "deterministic"
+            return query_plan, intent, "deterministic", source, {"used": False}, routing_reason
+        if not self._enable_llm_disambiguation or self._llm_disambiguator is None:
+            return query_plan, intent, "deterministic_fallback", "deterministic", {"used": False}, routing_reason
+        payload = {
+            "query": user_query,
+            "normalized_query": query_plan.normalized,
+            "deterministic_primary_candidate": str(ambiguity.get("deterministic_primary_candidate") or query_plan.sub_intent),
+            "deterministic_candidates": list(ambiguity.get("deterministic_candidates") or []),
+            "ambiguity_reason": str(ambiguity.get("ambiguity_reason") or ""),
+            "matched_anchor_type": self._docs_signals.detect_anchor(user_query)[0],
+            "query_entity_candidates": self._docs_signals.query_entity_candidates(user_query),
+            "query_anchor_candidates": self._docs_signals.query_anchor_candidates(user_query),
+        }
+        try:
+            llm_choice = self._llm_disambiguator.choose(payload)
+        except Exception as exc:
+            return query_plan, intent, "deterministic_fallback", "deterministic", {"used": False, "error": str(exc)}, routing_reason
+        if llm_choice is None:
+            return query_plan, intent, "deterministic_fallback", "deterministic", {"used": False, "error": "invalid_llm_output"}, routing_reason
+        final_sub_intent = str(llm_choice.get("sub_intent") or query_plan.sub_intent)
+        final_intent = "GENERAL_QA" if final_sub_intent == "GENERIC_QA" else intent
+        final_intent = "DOCUMENTATION_EXPLAIN" if final_sub_intent in {"SYSTEM_FLOW_EXPLAIN", "COMPONENT_EXPLAIN", "API_METHOD_EXPLAIN", "ENTITY_EXPLAIN", "RELATED_DOCS_EXPLAIN"} else final_intent
+        final_query_plan = query_plan.model_copy(update={"sub_intent": final_sub_intent})
+        return final_query_plan, final_intent, "llm_disambiguation", "llm", {"used": True, **llm_choice}, f"llm_disambiguation:{llm_choice.get('reason') or 'override'}"

src/app/modules/agent/llm/prompts.yml

@@ -20,35 +20,12 @@ prompts:
   code_qa_architecture_answer: |
     Ты инженер, который объясняет устройство подсистемы только по наблюдаемым компонентам и связям из кода.
 
-    Отвечай только по коду и структуре проекта, которые есть в контексте.
-    Пиши естественным инженерным языком, без искусственных markdown-секций и без повторов одной и той же мысли.
-    Если ответ можно дать в 1-3 фразах, не раздувай его.
-    Упоминай файлы, классы, функции, методы и связи только если они реально присутствуют в извлечённых данных.
-    Каждое содержательное утверждение по возможности привязывай к конкретному наблюдаемому имени или факту из контекста: пути файла, имени класса, функции, метода, аргумента, поля, route path, вызова или связи.
-    Если конкретные имена, параметры, вызовы или связи не видны, прямо скажи, чего именно не видно, вместо общих формулировок.
-    Не вводи новые сущности, зависимости или сценарии, которых нет в контексте.
-    Явно различай подтверждённые факты и осторожные выводы по косвенным признакам.
-    Если данных мало, честно скажи об этом вместо общего обзора.
-    Не используй жирные заголовки блоков, если пользователь их не просил.
-    Строго соблюдай контракт sub-intent и не подменяй локальный ответ архитектурным обзором.
-    Избегай расплывчатых и пустых формулировок вроде: "различные аргументы", "ряд аргументов", "различные подпакеты", "основные службы", "ключевой компонент", "играет роль", "представляет собой", если после них нет конкретики.
-    Не добавляй очевидные метафразы о том, что ответ основан на контексте или на видимом фрагменте, если это ничего не добавляет по сути.
-    Если сущность не найдена, остановись на факте not_found и не объясняй её предполагаемое назначение по одному только названию.
-    Не выводи пустые разделы, пустые списки и формулировки вида "кандидатов нет", если это не помогает ответу.
+    В payload есть `answer_contract`, `must_mention_components`, `must_mention_relations`, `must_mention_relation_summaries`, `must_use_relation_verbs`. Это обязательный каркас: ответ должен перечислять компоненты уровня класса/модуля и связи между ними с глаголами (создаёт, вызывает, импортирует, читает, записывает, наследует). Учитывай `fact_gaps`.
 
-    Дай архитектурное объяснение без лишней теории.
-    Строй ответ вокруг concrete facts из payload: `must_mention_components`, `must_mention_relations`, `must_use_relation_verbs`.
-    Если эти списки непустые, назови хотя бы часть компонентов и хотя бы одну наблюдаемую связь между ними.
-    Описывай не просто компоненты, а связи типа: создаёт, вызывает, регистрирует, читает, записывает, передаёт, оборачивает, импортирует, наследует.
-    Если связь не видна в payload, не додумывай её и не заменяй общими словами про управление подсистемой.
-    Методы и функции можно упоминать только как доказательство связи между компонентами, но не как основные "компоненты" ответа.
-    Затем коротко опиши границы ответственности, только если они реально видны в коде.
-    Не используй synthetic role labels как готовый пользовательский вывод, если они не поддержаны кодом.
-    Не придумывай скрытые слои и не расширяй архитектуру за пределы извлечённого контекста.
-    Не используй обязательные markdown-секции.
-    Не используй `semantic_hints` как primary explanation, особенно если `must_avoid_semantic_labels_as_primary_claims=true`.
-    Не используй raw retrieval labels вроде `dataflow_slice`, `execution_trace`, `trace_path` в финальном тексте.
-    Не используй абстрактные формулы вроде "главный компонент", "центральный управляющий компонент", "управляет потоками данных и состоянием системы", "этап пайплайна", если конкретная связь не раскрыта через наблюдаемые методы, поля или вызовы.
+    Отвечай только по коду из контекста. Пиши естественным языком, без лишних markdown-секций.
+    Строй ответ вокруг компонентов из `must_mention_components` и связей из `must_mention_relations` / `must_mention_relation_summaries`. Каждую связь формулируй с relation verb из `must_use_relation_verbs`. Методы и функции упоминай только как обоснование связи (например, "A вызывает B через метод X"), а не как основные "компоненты" списка.
+    Запрещено использовать в ответе raw retrieval labels: dataflow_slice, execution_trace, trace_path. Запрещено подменять архитектуру перечислением одних только методов без компонентов и связей. Запрещены абстрактные формулы без опоры на payload: "главный компонент", "управляет потоками данных", "этап пайплайна".
+    Не используй semantic_hints как primary explanation. Если связей в payload нет (fact_gaps), так и скажи — не додумывай связи. Не расширяй архитектуру за пределы извлечённого контекста.
   code_qa_degraded_answer: |
     Ты формируешь осторожный деградированный ответ.
     Нужно честно описать, что удалось подтвердить, а чего не хватает.
@@ -56,36 +33,13 @@ prompts:
   code_qa_explain_answer: |
     Ты senior Python-инженер и code reviewer, который объясняет устройство кода без домысливания.
 
-    Отвечай только по коду и структуре проекта, которые есть в контексте.
-    Пиши естественным инженерным языком, без искусственных markdown-секций и без повторов одной и той же мысли.
-    Если ответ можно дать в 1-3 фразах, не раздувай его.
-    Упоминай файлы, классы, функции, методы и связи только если они реально присутствуют в извлечённых данных.
-    Каждое содержательное утверждение по возможности привязывай к конкретному наблюдаемому имени или факту из контекста: пути файла, имени класса, функции, метода, аргумента, поля, route path, вызова или связи.
-    Если конкретные имена, параметры, вызовы или связи не видны, прямо скажи, чего именно не видно, вместо общих формулировок.
-    Не вводи новые сущности, зависимости или сценарии, которых нет в контексте.
-    Явно различай подтверждённые факты и осторожные выводы по косвенным признакам.
-    Если данных мало, честно скажи об этом вместо общего обзора.
-    Не используй жирные заголовки блоков, если пользователь их не просил.
-    Строго соблюдай контракт sub-intent и не подменяй локальный ответ архитектурным обзором.
-    Избегай расплывчатых и пустых формулировок вроде: "различные аргументы", "ряд аргументов", "различные подпакеты", "основные службы", "ключевой компонент", "играет роль", "представляет собой", если после них нет конкретики.
-    Не добавляй очевидные метафразы о том, что ответ основан на контексте или на видимом фрагменте, если это ничего не добавляет по сути.
-    Если сущность не найдена, остановись на факте not_found и не объясняй её предполагаемое назначение по одному только названию.
-    Не выводи пустые разделы, пустые списки и формулировки вида "кандидатов нет", если это не помогает ответу.
+    В payload есть блок `answer_contract` и списки must_mention_* — это обязательный каркас ответа. Если списки непусты, ты обязан использовать из них конкретные имена (методы, вызовы, зависимости, поля), а не подменять их общими фразами. Учитывай `fact_gaps`: если там указаны пробелы в данных, явно скажи об этом и не додумывай.
 
-    Объясни, как работает сущность из вопроса пользователя, обычным инженерным текстом.
-    Начни с самого важного: что это за сущность и где она находится, если это видно.
-    Затем строй ответ вокруг concrete facts из payload: `must_mention_methods`, `must_mention_fields`, `must_mention_calls`, `must_mention_dependencies`, `must_mention_constructor_args`, `must_mention_files`.
-    Если эти списки непустые, назови хотя бы часть этих имён явно, а не заменяй их общей интерпретацией.
-    Если в `must_mention_methods` даны полные qname, можно назвать метод по короткому имени, но только если связь с целевой сущностью остаётся ясной.
-    Сначала идентифицируй сущность, затем назови только подтверждённые методы, аргументы, вызовы, поля и зависимости.
-    Если сигнатуры, аргументы, методы или вызовы не видны, прямо скажи, чего именно не видно, используя `fact_gaps`, и остановись на этом.
-    Не используй общие формулы без конкретных имён.
-    Если виден конструктор, метод или вызов, лучше назвать его явно, чем писать абстрактно про "инициализацию", "службы", "аргументы" или "компоненты".
-    Если вывод основан на косвенных признаках, явно пометь это как осторожный вывод.
-    Если сущность не найдена или evidence слабый, не пиши обычное объяснение — прямо скажи об этом и остановись.
-    Запрещено подменять concrete methods/fields/calls формулами вроде "принимает ряд аргументов", "имеет responsibilities", "используется в службах", "регистрирует основные службы", если в payload есть конкретные имена.
-    Не используй `semantic_hints` как основной каркас ответа. Они допустимы только как вторичное замечание и только если не противоречат C0/C1/C2.
-    Не используй обязательные секции и подзаголовки.
+    Отвечай только по коду из контекста. Пиши естественным инженерным языком, без лишних markdown-секций.
+    Начни с идентификации сущности и её расположения. Затем обязательно опирайся на: `must_mention_methods`, `must_mention_calls`, `must_mention_dependencies`, `must_mention_fields`, `must_mention_constructor_args`, `must_mention_files`. Каждый непустой список должен быть отражён в ответе конкретными именами из списка — хотя бы часть. Не заменяй их формулировками вроде "принимает ряд аргументов", "имеет responsibilities", "регистрирует основные службы", "используется в службах".
+    Если в fact_gaps указано, что методы или вызовы не подтверждены, прямо скажи об этом и не строй объяснение на догадках.
+    Запрещено использовать semantic_hints как основной каркас ответа; только concrete code edges (C0/C1/C2). Избегай расплывчатых фраз: "ряд аргументов", "ключевой компонент", "играет роль", "представляет собой" без конкретики.
+    Если сущность не найдена или evidence слабый — скажи об этом и остановись. Не используй обязательные секции и подзаголовки.
   code_qa_explain_local_answer: |
     Ты инженер, который объясняет локальный фрагмент кода без лишней теории и без перехода на уровень всей архитектуры.
 
@@ -110,6 +64,7 @@ prompts:
     Если виден только фрагмент, ограничь вывод тем, что прямо видно в этом фрагменте.
     Не компенсируй нехватку локального контекста общими архитектурными фразами.
     Не расписывай всю архитектуру проекта и не используй секции без необходимости.
+    
   code_qa_find_entrypoints_answer: |
     Ты инженер, который находит подтверждённые точки входа и отдельно помечает только возможные кандидаты.
 
@@ -218,41 +173,137 @@ prompts:
     Если файла нет, ответь одной короткой фразой: `Файл <path> не найден.`
     Не придумывай анализ отсутствующего файла.
   code_qa_repair_answer: |
-    Ты исправляешь черновой ответ по коду после проверки groundedness.
-    Сделай ответ короче, точнее и строже по evidence payload.
-    Если проверка требует not_found или degraded формулировку, отрази это явно и убери спекуляции.
-    Если в `repair_focus` есть причины для `EXPLAIN`, перепиши ответ так, чтобы он назвал concrete methods, calls, fields, constructor args или dependencies из payload, а не общие responsibilities.
-    Если в `repair_focus` есть причины для `ARCHITECTURE`, перепиши ответ так, чтобы он назвал concrete components и связи с relation verbs из payload: создает, вызывает, читает, записывает, импортирует, наследует.
-    Если в `repair_focus` есть причины для `TRACE_FLOW`, перепиши ответ как последовательность concrete steps с явными methods/calls/edges из payload. Если виден только partial flow, так и скажи.
-    Если в `repair_focus` есть `semantic_labels_without_code_edges`, убери semantic role labels из основной формулировки, если они не подкреплены concrete code edges.
-    Если в `repair_focus` есть `contains_retrieval_artifacts` или `methods_as_primary_components`, убери raw retrieval labels и не выдавай методы за компоненты.
-    Если в `repair_focus` есть `overclaims_trace_completeness`, убери фразы про полный/полностью восстановленный flow, если payload не подтверждает это явно.
+    Ты исправляешь черновой ответ по результатам проверки groundedness. Вход: draft_answer, validation_reasons, repair_focus, prompt_payload. Исправь только то, на что указывает repair_focus; остальное сохрани. Ответ должен строго опираться на prompt_payload (must_mention_*, fact_gaps).
+
+    По repair_focus:
+    - missing_concrete_methods / missing_concrete_calls / missing_concrete_dependencies / missing_concrete_fields / too_vague_for_explain: встрой в ответ конкретные имена из must_mention_methods, must_mention_calls, must_mention_dependencies, must_mention_fields в payload. Убери общие фразы про "ряд аргументов", "responsibilities", "основные службы".
+    - semantic_labels_without_code_edges: убери формулировки, опирающиеся на semantic role labels; оставь только то, что подкреплено concrete code edges (методы, вызовы, зависимости из payload).
+    - missing_concrete_components / missing_concrete_relations / missing_relation_verbs / too_vague_for_architecture: перечисли компоненты и связи из must_mention_components, must_mention_relations, must_mention_relation_summaries; используй глаголы из must_use_relation_verbs. Не перечисляй только методы.
+    - contains_retrieval_artifacts: удали из текста слова dataflow_slice, execution_trace, trace_path и подобные raw labels.
+    - methods_as_primary_components: переформулируй так, чтобы компонентами были классы/модули, а методы упоминались только как обоснование связей.
+    - missing_flow_steps / missing_sequence_edges / too_vague_for_trace_flow: построй ответ как явную последовательность шагов из must_mention_flow_steps / must_mention_ordered_steps; назови конкретные вызовы и edges из payload.
+    - overclaims_trace_completeness: убери фразы про "полностью восстанавливается", "полный поток"; если в fact_gaps указана частичность, добавь формулировку вроде "видна только часть цепочки".
+    Если проверка требовала not_found или degraded — отрази это явно, без спекуляций.
   code_qa_trace_flow_answer: |
     Ты инженер, который восстанавливает поток вызовов и движение данных только по доказуемой цепочке из контекста.
 
-    Отвечай только по коду и структуре проекта, которые есть в контексте.
-    Пиши естественным инженерным языком, без искусственных markdown-секций и без повторов одной и той же мысли.
-    Если ответ можно дать в 1-3 фразах, не раздувай его.
-    Упоминай файлы, классы, функции, методы и связи только если они реально присутствуют в извлечённых данных.
-    Каждое содержательное утверждение по возможности привязывай к конкретному наблюдаемому имени или факту из контекста: пути файла, имени класса, функции, метода, аргумента, поля, route path, вызова или связи.
-    Если конкретные имена, параметры, вызовы или связи не видны, прямо скажи, чего именно не видно, вместо общих формулировок.
-    Не вводи новые сущности, зависимости или сценарии, которых нет в контексте.
-    Явно различай подтверждённые факты и осторожные выводы по косвенным признакам.
-    Если данных мало, честно скажи об этом вместо общего обзора.
-    Не используй жирные заголовки блоков, если пользователь их не просил.
-    Строго соблюдай контракт sub-intent и не подменяй локальный ответ архитектурным обзором.
-    Избегай расплывчатых и пустых формулировок вроде: "различные аргументы", "ряд аргументов", "различные подпакеты", "основные службы", "ключевой компонент", "играет роль", "представляет собой", если после них нет конкретики.
-    Не добавляй очевидные метафразы о том, что ответ основан на контексте или на видимом фрагменте, если это ничего не добавляет по сути.
-    Если сущность не найдена, остановись на факте not_found и не объясняй её предполагаемое назначение по одному только названию.
-    Не выводи пустые разделы, пустые списки и формулировки вида "кандидатов нет", если это не помогает ответу.
+    В payload есть `answer_contract`, `must_mention_flow_steps`, `must_mention_ordered_steps`, `must_mention_calls`, `must_mention_sequence_edges`, `fact_gaps`. Ответ обязан описывать поток как упорядоченную последовательность шагов из этих полей. Не заявляй полноту потока, если в fact_gaps указано иное. Не делай неподтверждённых утверждений.
 
-    Проследи поток выполнения или поток данных по найденным артефактам.
-    Строй ответ вокруг `must_mention_flow_steps`, `must_mention_calls` и `must_mention_sequence_edges` из payload.
-    Старайся описывать шаги последовательно и коротко, без лишних подзаголовков: сначала, затем, после этого, в конце.
-    Не склеивай шаги, если между ними нет прямой связи в коде или явно подтверждённого отношения в извлечённых данных.
-    Если поток восстанавливается только частично, так и скажи, опираясь на `fact_gaps`, и не заявляй, что flow восстановлен полностью.
-    Не заменяй конкретные шаги общими словами вроде "обрабатывает запрос", "передаёт данные" или "инициализирует службы", если можно назвать конкретный вызов, метод или route.
-    Не используй сильные формулировки вроде "полностью восстанавливается", "полный поток виден", если payload показывает только часть цепочки.
+    Отвечай только по коду из контекста. Пиши естественным языком, без лишних markdown-секций.
+    Опиши шаги по порядку, используя конкретные имена из `must_mention_ordered_steps` или `must_mention_flow_steps`: источник, глагол (вызывает, создаёт и т.д.), цель. Не заменяй их общими фразами ("обрабатывает запрос", "передаёт данные", "инициализирует службы") — называй конкретные вызовы/методы/route из payload.
+    Запрещены формулировки вроде "полностью восстанавливается", "полный поток виден", "полностью прослеживается", если в fact_gaps сказано, что последовательность частичная или данных недостаточно. Если поток частичный — явно скажи об этом в конце.
+    Не склеивай шаги без прямой связи в payload. Не добавляй шаги, которых нет в must_mention_*.
+  docs_explain_answer: |
+    Ты объясняешь документацию системы.
+
+    На вход приходит JSON с полями:
+    - question
+    - intent
+    - sub_intent
+    - documents
+    - facts
+    - relations
+
+    Правила:
+    - Используй только предоставленные факты
+    - Не додумывай
+    - Если данных недостаточно, скажи это явно
+    - Объясняй структурировано
+
+    Формат ответа:
+    1. Краткое описание
+    2. Основные элементы
+    3. Как это работает
+    4. Связи с другими частями системы (если есть)
+  docs_general_answer: |
+    Ты отвечаешь на общий вопрос по документации проекта.
+
+    На вход приходит JSON с полями:
+    - question
+    - intent
+    - sub_intent
+    - documents
+    - facts
+    - relations
+
+    Правила:
+    - Используй только предоставленные документы и факты
+    - Не додумывай отсутствующие детали
+    - Если данных недостаточно, скажи это прямо
+    - Дай короткий понятный ответ без лишней структуры
+  docs_openapi_answer: |
+    Ты генерируешь OpenAPI спецификацию по документации API.
+
+    На вход приходит JSON с полями:
+    - question
+    - intent
+    - sub_intent
+    - documents
+    - facts
+    - relations
+    - api_contract
+
+    Правила:
+    - Используй только данные из документации
+    - Не придумывай поля
+    - Если данных нет, не заполняй
+    - Верни ТОЛЬКО YAML без пояснений
+
+    Формат:
+    paths:
+      /path:
+        method:
+          summary: ...
+          requestBody:
+          responses:
+  docs_openapi_fragment_answer: |
+    Ты генерируешь часть OpenAPI schema по документации API.
+  docs_template_generation: |
+    Ты генерируешь проект документации по системной аналитике по заданному шаблону.
+
+    На вход приходит JSON с полями:
+    - question
+    - template_id
+    - title
+    - sections
+    - attachments
+    - files
+    - context
+
+    Правила:
+    - Строго следуй структуре шаблона
+    - Не выдумывай факты, которых нет во входе
+    - Если данных недостаточно, в соответствующем разделе явно укажи "Недостаточно данных"
+    - Верни Markdown документ с заголовком и секциями из шаблона
+  docs_fallback_answer: |
+    Ты отвечаешь на нетиповой вопрос в контуре документации и аналитики.
+
+    На вход приходит JSON с полями:
+    - question
+    - intent
+    - attachments
+    - confluence_urls
+
+    Правила:
+    - Дай короткий и честный ответ
+    - Если вопрос лучше перевести в один из специализированных workflow, мягко скажи об этом
+    - Не придумывай факты, если контекста недостаточно
+
+    На вход приходит JSON с полями:
+    - question
+    - intent
+    - sub_intent
+    - documents
+    - facts
+    - relations
+    - api_contract
+
+    Правила:
+    - Только schema
+    - Без полного OpenAPI документа
+    - Используй только данные из payload
+    - Не придумывай поля
+    - Верни ТОЛЬКО YAML без пояснений
   rag_intent_router_v2: |
     Ты intent-router для layered RAG.
     На вход ты получаешь JSON с полями:
@@ -261,20 +312,75 @@ prompts:
     - last_query: предыдущий запрос пользователя
     - allowed_intents: допустимые intent'ы
 
-    Выбери ровно один intent из allowed_intents.
+    Выбери ровно один intent из allowed_intents и один подходящий sub_intent.
     Верни только JSON без markdown и пояснений.
 
     Строгий формат ответа:
-    {"intent":"<one_of_allowed_intents>","confidence":<number_0_to_1>,"reason":"<short_reason>"}
+    {"intent":"<one_of_allowed_intents>","sub_intent":"<matching_sub_intent_or_empty_string>","confidence":<number_0_to_1>}
 
     Правила:
     - CODE_QA: объяснение по коду, архитектуре, классам, методам, файлам, блокам кода, поведению приложения по реализации.
-    - DOCS_QA: объяснение по документации, README, markdown, specs, runbooks, разделам документации.
+    - DOCUMENTATION_EXPLAIN: объяснение сущности, компонента, API метода, flow или связанных документов по документации.
+    - OPENAPI_GENERATION: генерация OpenAPI/Swagger/YAML/spec/schema по документации API.
+    - GENERAL_QA: слишком общий или нечеткий вопрос по документации/проекту, который нельзя уверенно отнести к explain/openapi.
     - GENERATE_DOCS_FROM_CODE: просьба сгенерировать, подготовить или обновить документацию по коду.
-    - PROJECT_MISC: прочие вопросы по проекту, не относящиеся явно к коду или документации.
+
+    Допустимые docs sub-intents:
+    - SYSTEM_FLOW_EXPLAIN
+    - COMPONENT_EXPLAIN
+    - API_METHOD_EXPLAIN
+    - ENTITY_EXPLAIN
+    - RELATED_DOCS_EXPLAIN
+    - OPENAPI_METHOD_GENERATE
+    - OPENAPI_FRAGMENT_GENERATE
+    - GENERIC_QA
 
     Приоритет:
     - Если пользователь просит именно подготовить документацию по коду, выбирай GENERATE_DOCS_FROM_CODE.
+    - Если есть openapi, swagger, yaml, schema или spec, выбирай OPENAPI_GENERATION.
+      Если запрос про request, response или schema, выбирай OPENAPI_FRAGMENT_GENERATE.
+      Иначе выбирай OPENAPI_METHOD_GENERATE.
+    - Если запрос про связанные документы, где еще описано, что еще посмотреть, какие страницы связаны, какие документы по теме, выбирай DOCUMENTATION_EXPLAIN и sub_intent RELATED_DOCS_EXPLAIN.
+    - Если есть объясни, как работает, что делает или что такое по документации, выбирай DOCUMENTATION_EXPLAIN.
+      Для API/endpoint/method выбирай API_METHOD_EXPLAIN.
+      Для flow/workflow/process выбирай SYSTEM_FLOW_EXPLAIN.
+      Для entity/сущности выбирай ENTITY_EXPLAIN.
+      Иначе выбирай COMPONENT_EXPLAIN.
     - Если пользователь спрашивает про конкретный класс, файл, метод или блок кода, выбирай CODE_QA.
-    - Если пользователь спрашивает про README, docs, markdown или конкретную документацию, выбирай DOCS_QA.
-    - Если сигнал неочевиден, выбирай PROJECT_MISC и confidence <= 0.6.
+    - Если пользователь спрашивает про README, docs, markdown или конкретную документацию без явного openapi, выбирай DOCUMENTATION_EXPLAIN.
+    - Если сигнал неочевиден, выбирай GENERAL_QA и confidence <= 0.6.
+  rag_docs_router_disambiguation_v1: |
+    Ты помогаешь разрешить неоднозначность в docs sub-intent router.
+
+    На вход приходит JSON:
+    - query
+    - normalized_query
+    - deterministic_primary_candidate
+    - deterministic_candidates
+    - ambiguity_reason
+    - matched_anchor_type
+    - query_entity_candidates
+    - query_anchor_candidates
+
+    Выбери ровно один sub_intent только из списка deterministic_candidates.
+    Не придумывай новые labels.
+
+    Допустимые labels:
+    - SYSTEM_FLOW_EXPLAIN
+    - COMPONENT_EXPLAIN
+    - API_METHOD_EXPLAIN
+    - ENTITY_EXPLAIN
+    - RELATED_DOCS_EXPLAIN
+    - GENERIC_QA
+    - OPENAPI_METHOD_GENERATE
+    - OPENAPI_FRAGMENT_GENERATE
+
+    Правила:
+    - Если запрос обзорный, про структуру документации, "что есть", "с чего начать", выбирай GENERIC_QA.
+    - Если запрос про runtime health, статус воркера, состояние runtime как понятие/сущность, выбирай ENTITY_EXPLAIN.
+    - Если запрос про процесс, health check flow, последовательность шагов, выбирай SYSTEM_FLOW_EXPLAIN.
+    - Если есть точный endpoint/path anchor, не уводи запрос в GENERIC_QA.
+    - Если есть CamelCase component-like token, предпочитай COMPONENT_EXPLAIN.
+
+    Верни только JSON:
+    {"sub_intent":"<one_of_candidates>","reason":"<short_reason>","confidence":"low|medium|high"}

src/app/modules/agent/llm/service.py

@@ -1,5 +1,6 @@
 import logging
 
+from app.modules.agent.observability.module_trace import ModuleTrace
 from app.modules.agent.llm.prompt_loader import PromptLoader
 from app.modules.shared.gigachat.client import GigaChatClient
 
@@ -18,10 +19,26 @@ class AgentLlmService:
         self._client = client
         self._prompts = prompts
 
-    def generate(self, prompt_name: str, user_input: str, *, log_context: str | None = None) -> str:
-        system_prompt = self._prompts.load(prompt_name)
-        if not system_prompt:
-            system_prompt = "You are a helpful assistant."
+    def build_request(self, prompt_name: str, user_input: str, *, log_context: str | None = None) -> dict[str, str]:
+        system_prompt = self._prompts.load(prompt_name) or "You are a helpful assistant."
+        return {
+            "prompt_name": prompt_name,
+            "system_prompt": system_prompt,
+            "user_prompt": user_input,
+            "log_context": log_context or "",
+        }
+
+    def generate(
+        self,
+        prompt_name: str,
+        user_input: str,
+        *,
+        log_context: str | None = None,
+        trace: ModuleTrace | None = None,
+    ) -> str:
+        request = self.build_request(prompt_name, user_input, log_context=log_context)
+        if trace is not None:
+            trace.log("request", request)
         if log_context:
             LOGGER.warning(
                 "graph llm input: context=%s prompt=%s user_input=%s",
@@ -29,7 +46,12 @@ class AgentLlmService:
                 prompt_name,
                 _truncate_for_log(user_input),
             )
-        output = self._client.complete(system_prompt=system_prompt, user_prompt=user_input)
+        output = self._client.complete(
+            system_prompt=request["system_prompt"],
+            user_prompt=request["user_prompt"],
+        )
+        if trace is not None:
+            trace.log("response", {"text": output})
         if log_context:
             LOGGER.warning(
                 "graph llm output: context=%s prompt=%s output=%s",

src/app/modules/agent/observability/module_trace.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class ModuleTraceLogger(Protocol):
+    def log_module(self, request_id: str, module: str, title: str, payload: dict | None = None) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleTrace:
+    request_id: str
+    module: str
+    logger: ModuleTraceLogger
+
+    def log(self, title: str, payload: dict | None = None) -> None:
+        self.logger.log_module(self.request_id, self.module, title, payload or {})
+
+
+@dataclass(frozen=True, slots=True)
+class RequestTraceContext:
+    request_id: str
+    logger: ModuleTraceLogger
+
+    def module(self, name: str) -> ModuleTrace:
+        return ModuleTrace(request_id=self.request_id, module=name, logger=self.logger)

src/app/modules/agent/orchestration/adapters/intent_router_adapter.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from app.modules.agent.observability.module_trace import ModuleTrace
+from app.modules.agent.intent_router_v2 import IntentRouterV2
+
+
+class IntentRouterAdapter:
+    def __init__(self, router: IntentRouterV2) -> None:
+        self._router = router
+
+    def route(self, user_query: str, conversation_state, repo_context, trace: ModuleTrace | None = None):
+        if trace is not None:
+            trace.log("started", {"question": user_query})
+        result = self._router.route(user_query, conversation_state, repo_context)
+        if trace is not None:
+            trace.log(
+                "completed",
+                {
+                    "intent": result.intent,
+                    "sub_intent": result.query_plan.sub_intent,
+                    "matched_intent_source": result.matched_intent_source,
+                },
+            )
+        return result

src/app/modules/agent/orchestration/adapters/llm_chat_adapter.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import asyncio
+
+from app.modules.agent.observability.module_trace import ModuleTrace
+from app.modules.agent.llm.service import AgentLlmService
+
+
+class LlmChatAdapter:
+    def __init__(self, llm: AgentLlmService, prompt_name: str = "simple_llm_answer") -> None:
+        self._llm = llm
+        self._prompt_name = prompt_name
+
+    @property
+    def prompt_name(self) -> str:
+        return self._prompt_name
+
+    def build_request(self, message: str, request_id: str) -> dict[str, str]:
+        return self._llm.build_request(
+            self._prompt_name,
+            message,
+            log_context=f"agent:{request_id}",
+        )
+
+    async def generate(self, message: str, request_id: str, trace: ModuleTrace | None = None) -> str:
+        return await asyncio.to_thread(
+            self._llm.generate,
+            self._prompt_name,
+            message,
+            log_context=f"agent:{request_id}",
+            trace=trace,
+        )

src/app/modules/agent/orchestration/adapters/task_runtime_adapter.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from app.core.exceptions import AppError
+from app.modules.agent.task_runtime.facade import AgentTaskRuntimeFacade
+from app.modules.api.domain.models.agent_session import AgentSession
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+from app.schemas.common import ModuleName
+
+
+class TaskRuntimeAdapter:
+    def __init__(self, runtime: AgentTaskRuntimeFacade) -> None:
+        self._runtime = runtime
+
+    async def run(self, context: ExecutionContext) -> SimpleNamespace:
+        rag_session_id = context.session.active_rag_session_id
+        if not rag_session_id:
+            raise AppError(
+                "rag_session_not_bound",
+                "Agent session has no active rag_session_id for process v2.",
+                ModuleName.RAG,
+            )
+
+        def progress_cb(stage: str, message: str, kind: str = "task_progress", meta: dict | None = None):
+            payload = dict(meta or {})
+            payload.setdefault("kind", kind)
+            return context.publisher.publish_status(
+                context.request.request_id,
+                stage,
+                message,
+                payload,
+            )
+
+        return await self._runtime.run(
+            task_id=context.request.request_id,
+            dialog_session_id=context.session.session_id,
+            rag_session_id=rag_session_id,
+            mode="auto",
+            message=context.request.message,
+            attachments=[],
+            files=[],
+            progress_cb=progress_cb,
+        )

src/app/modules/agent/orchestration/context/execution_context.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from app.modules.api.domain.models.agent_request import AgentRequest
+from app.modules.api.domain.models.agent_session import AgentSession
+from app.modules.api.infrastructure.logging.request_trace_logger import RequestTraceLogger
+from app.modules.agent.observability.module_trace import RequestTraceContext
+from app.modules.agent.orchestration.messaging.client_message_publisher import ClientMessagePublisher
+
+
+@dataclass(slots=True)
+class ExecutionContext:
+    request: AgentRequest
+    session: AgentSession
+    publisher: ClientMessagePublisher
+    trace_logger: RequestTraceLogger
+    trace: RequestTraceContext
+    task_context: Any = None
+    route_result: Any = None
+    workflow_result: Any = None

src/app/modules/agent/orchestration/facade.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from app.core.exceptions import AppError
+from app.modules.api.domain.models.agent_request import AgentRequest
+from app.modules.api.domain.models.agent_session import AgentSession
+from app.modules.api.infrastructure.logging.request_trace_logger import RequestTraceLogger
+from app.modules.agent.observability.module_trace import RequestTraceContext
+from app.modules.api.infrastructure.stores.in_memory_request_store import InMemoryRequestStore
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+from app.modules.agent.orchestration.messaging.client_message_publisher import ClientMessagePublisher
+from app.modules.agent.orchestration.processes.registry import ProcessRegistry
+from app.modules.agent.orchestration.runtime.process_runner import ProcessRunner
+from app.schemas.common import ErrorPayload, ModuleName
+from app.schemas.orchestration import RequestExecutionStatus
+
+
+class OrchestrationFacade:
+    def __init__(
+        self,
+        request_store: InMemoryRequestStore,
+        process_registry: ProcessRegistry,
+        process_runner: ProcessRunner,
+        publisher: ClientMessagePublisher,
+        trace_logger: RequestTraceLogger,
+    ) -> None:
+        self._request_store = request_store
+        self._process_registry = process_registry
+        self._process_runner = process_runner
+        self._publisher = publisher
+        self._trace_logger = trace_logger
+
+    async def run(self, request: AgentRequest, session: AgentSession) -> None:
+        try:
+            process = self._process_registry.get(request.process_version)
+            if process is None:
+                raise AppError("process_not_found", f"Unsupported process version: {request.process_version}", ModuleName.AGENT)
+            request.status = RequestExecutionStatus.RUNNING
+            self._request_store.save(request)
+            self._trace_logger.start_request(request, session)
+            context = ExecutionContext(
+                request=request,
+                session=session,
+                publisher=self._publisher,
+                trace_logger=self._trace_logger,
+                trace=RequestTraceContext(request_id=request.request_id, logger=self._trace_logger),
+            )
+            await self._process_runner.run(context, process.steps())
+            request.status = RequestExecutionStatus.DONE
+            request.completed_at = datetime.now(timezone.utc)
+            self._request_store.save(request)
+            self._trace_logger.complete_request(request)
+        except Exception as exc:
+            request.status = RequestExecutionStatus.ERROR
+            request.completed_at = datetime.now(timezone.utc)
+            if isinstance(exc, AppError):
+                request.error = ErrorPayload(code=exc.code, desc=exc.desc, module=exc.module)
+            else:
+                request.error = ErrorPayload(
+                    code="api_runtime_error",
+                    desc="Agent request failed unexpectedly.",
+                    module=ModuleName.AGENT,
+                )
+            self._request_store.save(request)
+            self._trace_logger.fail_request(request)
+            await self._publisher.publish_status(
+                request.request_id,
+                "orchestrator",
+                "Во время обработки запроса произошла ошибка.",
+                {"code": request.error.code},
+            )

src/app/modules/agent/orchestration/messaging/client_message_publisher.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from app.modules.api.infrastructure.logging.request_trace_logger import RequestTraceLogger
+from app.modules.api.infrastructure.streaming.sse_event_channel import SseEventChannel
+from app.modules.agent.orchestration.messaging.status_message_factory import StatusMessageFactory
+from app.modules.agent.orchestration.messaging.user_message_factory import UserMessageFactory
+
+
+class ClientMessagePublisher:
+    def __init__(self, channel: SseEventChannel, trace_logger: RequestTraceLogger) -> None:
+        self._channel = channel
+        self._trace_logger = trace_logger
+        self._status = StatusMessageFactory()
+        self._user = UserMessageFactory()
+
+    async def publish_status(self, request_id: str, source: str, text: str, payload: dict | None = None) -> None:
+        event = self._status.create(request_id, source, text, payload)
+        self._trace_logger.log_event(event)
+        await self._channel.publish(event)
+
+    async def publish_user(self, request_id: str, source: str, text: str, payload: dict | None = None) -> None:
+        event = self._user.create(request_id, source, text, payload)
+        self._trace_logger.log_event(event)
+        await self._channel.publish(event)

src/app/modules/agent/orchestration/messaging/status_message_factory.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from app.modules.api.domain.events.client_event import ClientEventRecord
+from app.schemas.client_events import ClientEventType
+
+
+class StatusMessageFactory:
+    def create(self, request_id: str, source: str, text: str, payload: dict | None = None) -> ClientEventRecord:
+        return ClientEventRecord(
+            request_id=request_id,
+            type=ClientEventType.STATUS,
+            source=source,
+            text=text,
+            payload=payload or {},
+        )

src/app/modules/agent/orchestration/messaging/user_message_factory.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from app.modules.api.domain.events.client_event import ClientEventRecord
+from app.schemas.client_events import ClientEventType
+
+
+class UserMessageFactory:
+    def create(self, request_id: str, source: str, text: str, payload: dict | None = None) -> ClientEventRecord:
+        return ClientEventRecord(
+            request_id=request_id,
+            type=ClientEventType.USER,
+            source=source,
+            text=text,
+            payload=payload or {},
+        )

src/app/modules/agent/orchestration/processes/registry.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.processes.v1.process import V1Process
+from app.modules.agent.orchestration.processes.v2.process import V2Process
+
+
+class ProcessRegistry:
+    def __init__(self, v1_process: V1Process, v2_process: V2Process | None = None) -> None:
+        self._items = {"v1": v1_process}
+        if v2_process is not None:
+            self._items["v2"] = v2_process
+
+    def get(self, version: str):
+        return self._items.get(version)

src/app/modules/agent/orchestration/processes/v1/process.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class V1Process:
+    def __init__(self, steps: list) -> None:
+        self._steps = steps
+
+    def steps(self) -> list:
+        return list(self._steps)

src/app/modules/agent/orchestration/processes/v1/prompt_payload_builder.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import json
+
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+
+
+class V1PromptPayloadBuilder:
+    def build(self, context: ExecutionContext) -> str:
+        payload = {"question": context.request.message}
+        return json.dumps(payload, ensure_ascii=False, indent=2)

src/app/modules/agent/orchestration/processes/v1/prompts.yml

@@ -0,0 +1,12 @@
+prompts:
+  simple_llm_answer: |
+    Ты полезный AI-ассистент проекта.
+
+    На вход приходит JSON с полем:
+    - question
+
+    Правила:
+    - Отвечай как персонаж мемов из дагестана
+    - Если вопрос неясный, аккуратно укажи, чего не хватает
+    - Не выдумывай несуществующие факты о проекте
+    - Формулируй ответ как обычное сообщение пользователю

src/app/modules/agent/orchestration/processes/v1/simple_llm_workflow.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.adapters.llm_chat_adapter import LlmChatAdapter
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+from app.modules.agent.orchestration.processes.v1.prompt_payload_builder import V1PromptPayloadBuilder
+
+
+class SimpleLlmWorkflow:
+    workflow_id = "simple_llm"
+
+    def __init__(
+        self,
+        llm: LlmChatAdapter,
+        prompt_payload_builder: V1PromptPayloadBuilder | None = None,
+    ) -> None:
+        self._llm = llm
+        self._payload_builder = prompt_payload_builder or V1PromptPayloadBuilder()
+
+    async def run(self, context: ExecutionContext) -> dict:
+        workflow_trace = context.trace.module("task_workflow")
+        workflow_trace.log("started", {"workflow_id": self.workflow_id})
+        prompt_payload = self._payload_builder.build(context)
+        answer = await self._llm.generate(
+            prompt_payload,
+            context.request.request_id,
+            trace=context.trace.module("llm"),
+        )
+        result = {
+            "workflow_id": self.workflow_id,
+            "prompt_name": self._llm.prompt_name,
+            "prompt_payload": prompt_payload,
+            "answer": answer,
+        }
+        workflow_trace.log(
+            "completed",
+            {
+                "workflow_id": self.workflow_id,
+                "prompt_name": self._llm.prompt_name,
+                "answer_length": len(answer),
+            },
+        )
+        return result

src/app/modules/agent/orchestration/processes/v1/steps/bootstrap_step.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+
+
+class BootstrapStep:
+    async def run(self, context: ExecutionContext) -> None:
+        context.trace.module("orchestrator").log(
+            "bootstrap",
+            {"status": "started", "process_version": context.request.process_version},
+        )
+        await context.publisher.publish_status(
+            context.request.request_id,
+            "orchestrator",
+            "Запрос принят и поставлен в обработку.",
+        )
+        await context.publisher.publish_status(
+            context.request.request_id,
+            "orchestrator",
+            "Запускаю процесс обработки v1.",
+            {"process_version": context.request.process_version},
+        )
+        context.trace.module("orchestrator").log("bootstrap", {"status": "completed"})

src/app/modules/agent/orchestration/processes/v1/steps/execute_llm_workflow_step.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+from app.modules.agent.orchestration.processes.v1.simple_llm_workflow import SimpleLlmWorkflow
+
+
+class ExecuteLlmWorkflowStep:
+    def __init__(self, workflow: SimpleLlmWorkflow) -> None:
+        self._workflow = workflow
+
+    async def run(self, context: ExecutionContext) -> None:
+        request = context.request
+        await context.publisher.publish_status(
+            request.request_id,
+            "task_workflow",
+            f"Запускаю workflow {self._workflow.workflow_id}.",
+        )
+        await context.publisher.publish_status(
+            request.request_id,
+            "prompt_builder",
+            "Формирую prompt payload для LLM.",
+        )
+        result = await self._workflow.run(context)
+        request.answer = str(result.get("answer") or "")
+        context.workflow_result = result
+        await context.publisher.publish_status(
+            request.request_id,
+            "llm_process",
+            "Ответ от LLM получен.",
+            {
+                "workflow_id": result.get("workflow_id"),
+                "prompt_name": result.get("prompt_name"),
+                "answer_length": len(request.answer),
+            },
+        )

src/app/modules/agent/orchestration/processes/v1/steps/finalize_step.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+
+
+class FinalizeStep:
+    async def run(self, context: ExecutionContext) -> None:
+        request = context.request
+        context.trace.module("orchestrator").log("finalize", {"status": "started"})
+        await context.publisher.publish_user(
+            request.request_id,
+            "agent",
+            request.answer or "",
+        )
+        await context.publisher.publish_status(
+            request.request_id,
+            "orchestrator",
+            "Обработка запроса завершена.",
+        )
+        context.trace.module("orchestrator").log("finalize", {"status": "completed"})

src/app/modules/agent/orchestration/processes/v1/steps/run_llm_step.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.adapters.llm_chat_adapter import LlmChatAdapter
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+
+
+class RunLlmStep:
+    def __init__(self, llm: LlmChatAdapter) -> None:
+        self._llm = llm
+
+    async def run(self, context: ExecutionContext) -> None:
+        request = context.request
+        context.trace_logger.log_step(request.request_id, "run_llm", "started")
+        await context.publisher.publish_status(
+            request.request_id,
+            "llm_process",
+            "Отправляю запрос пользователя в LLM.",
+        )
+        answer = await self._llm.generate(request.message, request.request_id)
+        request.answer = answer
+        await context.publisher.publish_status(
+            request.request_id,
+            "llm_process",
+            "Ответ от LLM получен.",
+        )
+        context.trace_logger.log_step(request.request_id, "run_llm", "completed", {"answer_length": len(answer)})

src/app/modules/agent/orchestration/processes/v2/README.md

@@ -0,0 +1,189 @@
+# Process V2
+
+`v2` is the current default orchestration process for agent requests.
+
+It is designed as a small stage-based pipeline:
+
+1. accept request
+2. route intent
+3. run intent-specific workflow
+4. publish final user response
+
+The process definition lives in [process.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/process.py).
+
+## Step Map
+
+### 1. Bootstrap
+
+File:
+[bootstrap_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v1/steps/bootstrap_step.py)
+
+Responsibility:
+- announce request acceptance
+- announce selected process version
+- initialize trace logging
+
+SSE source:
+- `orchestrator`
+
+### 2. Intent Router
+
+File:
+[route_intent_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/route_intent_step.py)
+
+Responsibility:
+- build task runtime context
+- enrich request context
+- call `IntentRouterV2`
+- persist `route_result` into orchestration context
+
+SSE source:
+- `intent_router`
+
+Main status messages:
+- request is being routed
+- final `intent / sub_intent`
+
+### 3. Workflow Execution
+
+Base behavior:
+[workflow_step_base.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/workflow_step_base.py)
+
+Intent-specific steps:
+- [execute_documentation_workflow_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/execute_documentation_workflow_step.py)
+- [execute_openapi_workflow_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/execute_openapi_workflow_step.py)
+- [execute_general_qa_workflow_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/execute_general_qa_workflow_step.py)
+- [execute_fallback_workflow_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v2/steps/execute_fallback_workflow_step.py)
+
+Responsibility:
+- choose workflow by `route_result.intent`
+- run the selected workflow
+- expose workflow diagnostics through SSE
+- store workflow result in orchestration context
+
+Workflow mapping:
+
+| Intent | Workflow class | Notes |
+|---|---|---|
+| `DOCUMENTATION_EXPLAIN` | `DocsQaWorkflow` | docs explanation pipeline |
+| `OPENAPI_GENERATION` | `OpenApiWorkflow` | OpenAPI generation from docs evidence |
+| `GENERAL_QA` | `GeneralQaWorkflow` | general docs-oriented QA |
+| any other intent | `FallbackWorkflow` | safety fallback |
+
+Published SSE stages:
+- `task_workflow`
+- `rag_retrieval`
+- `evidence_gate`
+- `workflow_result`
+
+### 4. Finalize
+
+File:
+[finalize_step.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/processes/v1/steps/finalize_step.py)
+
+Responsibility:
+- publish final `user` event with answer text
+- publish terminal status message
+- let facade mark request as `done`
+
+SSE sources:
+- `agent`
+- `orchestrator`
+
+## Intent Routing
+
+Router adapter:
+[intent_router_adapter.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/orchestration/adapters/intent_router_adapter.py)
+
+Underlying implementation:
+[router.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/agent/intent_router_v2/router.py)
+
+The router decides:
+- `intent`
+- `sub_intent`
+- retrieval profile
+- retrieval layers and constraints
+- evidence policy
+
+For docs-oriented requests the main active intents are:
+- `DOCUMENTATION_EXPLAIN`
+- `OPENAPI_GENERATION`
+- `GENERAL_QA`
+
+## Retrieval And Evidence Gate
+
+`v2` does not implement retrieval itself inside orchestration.
+
+Instead it delegates execution to workflow classes that internally use the existing docs pipeline:
+
+- [docs_qa.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/agent/task_runtime/workflows/docs_qa.py)
+- [openapi.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/agent/task_runtime/workflows/openapi.py)
+- [general_qa.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/agent/task_runtime/workflows/general_qa.py)
+
+These workflows currently rely on:
+- `DocsQAPipelineRunner`
+- docs retrieval planning
+- docs evidence builder
+- docs gate logic
+
+Important:
+- docs retrieval and gate logic still live in the existing docs runtime layer
+- orchestration `v2` only makes those stages explicit at transport/process level
+
+## SSE Contract In V2
+
+Client-visible message categories:
+- `status`
+- `user`
+- `system`
+
+Currently used in `v2`:
+
+- `status` from `orchestrator`
+- `status` from `intent_router`
+- `status` from `task_workflow`
+- `status` from `rag_retrieval`
+- `status` from `evidence_gate`
+- `status` from `workflow_result`
+- `user` from `agent`
+
+Typical sequence:
+
+1. request accepted
+2. process `v2` started
+3. routing started
+4. route selected
+5. workflow started
+6. retrieval diagnostics
+7. evidence gate diagnostics
+8. workflow result summary
+9. final user answer
+10. processing completed
+
+## Trace Logging
+
+Per-request trace files are written by:
+[request_trace_logger.py](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/src/app/modules/api/infrastructure/logging/request_trace_logger.py)
+
+Location:
+[runtime_traces/agent_requests](/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/runtime_traces/agent_requests)
+
+Each request trace contains:
+- request metadata
+- user message
+- process steps
+- emitted events
+- final result or error
+
+## Extension Points
+
+Recommended next extensions:
+
+1. add a dedicated workflow step for `GENERATE_DOCS_FROM_CODE`
+2. move docs gate diagnostics into strongly typed orchestration payloads
+3. split workflow execution into smaller orchestration stages:
+   - retrieval
+   - evidence assembly
+   - gate
+   - answer generation
+4. add session-level trace aggregation in addition to request-level logs

src/app/modules/agent/orchestration/processes/v2/process.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class V2Process:
+    def __init__(self, steps: list) -> None:
+        self._steps = steps
+
+    def steps(self) -> list:
+        return list(self._steps)

src/app/modules/agent/orchestration/processes/v2/prompt_payload_builder.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import json
+
+from app.modules.agent.runtime.docs_qa_pipeline.models import DocsEvidenceBundle, OpenAPIResult
+
+
+class V2PromptPayloadBuilder:
+    def build(
+        self,
+        *,
+        question: str,
+        intent: str,
+        sub_intent: str,
+        evidence_bundle: DocsEvidenceBundle,
+        api_contract: OpenAPIResult | None = None,
+    ) -> str:
+        payload = {
+            "question": question,
+            "documents": list(evidence_bundle.documents),
+            "facts": list(evidence_bundle.facts),
+            "entities": list(evidence_bundle.entities),
+            "workflows": list(evidence_bundle.workflows),
+            "relations": list(evidence_bundle.relations),
+            "chunks": list(evidence_bundle.chunks),
+        }
+        if api_contract is not None:
+            payload["api_contract"] = {
+                "path": api_contract.path,
+                "method": api_contract.method,
+                "request_schema": api_contract.request_schema,
+                "response_schema": api_contract.response_schema,
+                "diagnostics": dict(api_contract.diagnostics),
+            }
+        return json.dumps(payload, ensure_ascii=False, indent=2)

src/app/modules/agent/orchestration/processes/v2/prompt_selector.py

@@ -0,0 +1,18 @@
+"""Выбор prompt для process-local workflow v2."""
+
+from __future__ import annotations
+
+
+class V2PromptSelector:
+    _DOCS_INTENT_PROMPTS = {
+        "DOCUMENTATION_EXPLAIN": "documentation_explain_answer",
+        "GENERAL_QA": "general_qa_answer",
+    }
+
+    def select(self, *, intent: str = "DOCUMENTATION_EXPLAIN", sub_intent: str, answer_mode: str) -> str:
+        intent_key = (intent or "DOCUMENTATION_EXPLAIN").upper()
+        if intent_key in {"OPENAPI_GENERATION", "OPENAPI_FROM_DOCUMENTATION"}:
+            if sub_intent.upper() == "OPENAPI_FRAGMENT_GENERATE":
+                return "openapi_fragment_answer"
+            return "openapi_answer"
+        return self._DOCS_INTENT_PROMPTS.get(intent_key, "documentation_explain_answer")

src/app/modules/agent/orchestration/processes/v2/prompts.yml

@@ -0,0 +1,96 @@
+prompts:
+  documentation_explain_answer: |
+    Ты объясняешь документацию системы.
+
+    На вход приходит JSON с полями:
+    - question
+    - documents
+    - facts
+    - entities
+    - workflows
+    - relations
+    - chunks
+
+    Правила:
+    - Используй только предоставленные факты
+    - Не додумывай
+    - Если данных недостаточно, скажи это явно
+    - Объясняй структурировано
+
+    Формат ответа:
+    1. Краткое описание
+    2. Основные элементы
+    3. Как это работает
+    4. Связи с другими частями системы (если есть)
+  general_qa_answer: |
+    Ты отвечаешь на общий вопрос по документации проекта.
+
+    На вход приходит JSON с полями:
+    - question
+    - documents
+    - facts
+    - entities
+    - workflows
+    - relations
+    - chunks
+
+    Правила:
+    - Используй только предоставленные документы и факты
+    - Не додумывай отсутствующие детали
+    - Если данных недостаточно, скажи это прямо
+    - Дай короткий понятный ответ без лишней структуры
+  openapi_answer: |
+    Ты генерируешь OpenAPI спецификацию по документации API.
+
+    На вход приходит JSON с полями:
+    - question
+    - documents
+    - facts
+    - entities
+    - workflows
+    - relations
+    - chunks
+    - api_contract
+
+    Правила:
+    - Используй только данные из документации
+    - Не придумывай поля
+    - Если данных нет, не заполняй
+    - Верни ТОЛЬКО YAML без пояснений
+
+    Формат:
+    paths:
+      /path:
+        method:
+          summary: ...
+          requestBody:
+          responses:
+  openapi_fragment_answer: |
+    Ты генерируешь часть OpenAPI schema по документации API.
+
+    На вход приходит JSON с полями:
+    - question
+    - documents
+    - facts
+    - entities
+    - workflows
+    - relations
+    - chunks
+    - api_contract
+
+    Правила:
+    - Используй только данные из документации
+    - Не придумывай отсутствующие поля
+    - Верни только содержимое нужного фрагмента
+  fallback_answer: |
+    Ты формируешь безопасный fallback-ответ.
+
+    На вход приходит JSON с полями:
+    - question
+    - attachments
+    - confluence_urls
+
+    Правила:
+    - Если специализированный workflow не выбран, честно скажи об ограничении
+    - Используй только данные из payload
+    - Не выдумывай детали проекта

src/app/modules/agent/orchestration/processes/v2/steps/execute_documentation_workflow_step.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.processes.v2.steps.workflow_step_base import WorkflowStepBase
+
+
+class ExecuteDocumentationWorkflowStep(WorkflowStepBase):
+    intent_name = "DOCUMENTATION_EXPLAIN"

src/app/modules/agent/orchestration/processes/v2/steps/execute_fallback_workflow_step.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+from app.modules.agent.orchestration.processes.v2.steps.workflow_step_base import WorkflowStepBase
+
+
+class ExecuteFallbackWorkflowStep(WorkflowStepBase):
+    intent_name = "FALLBACK"
+
+    def should_run(self, context: ExecutionContext) -> bool:
+        route_result = context.route_result
+        if route_result is None:
+            return False
+        return str(route_result.intent or "").upper() not in {
+            "DOCUMENTATION_EXPLAIN",
+            "OPENAPI_GENERATION",
+            "GENERAL_QA",
+        }

src/app/modules/agent/orchestration/processes/v2/steps/execute_general_qa_workflow_step.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.processes.v2.steps.workflow_step_base import WorkflowStepBase
+
+
+class ExecuteGeneralQaWorkflowStep(WorkflowStepBase):
+    intent_name = "GENERAL_QA"

src/app/modules/agent/orchestration/processes/v2/steps/execute_openapi_workflow_step.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.processes.v2.steps.workflow_step_base import WorkflowStepBase
+
+
+class ExecuteOpenApiWorkflowStep(WorkflowStepBase):
+    intent_name = "OPENAPI_GENERATION"

src/app/modules/agent/orchestration/processes/v2/steps/route_intent_step.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import asyncio
+
+from app.core.exceptions import AppError
+from app.modules.agent.task_runtime.context import TaskRuntimeContextBuilder
+from app.modules.agent.task_runtime.enrichment import ContextEnrichmentService
+from app.modules.agent.orchestration.adapters.intent_router_adapter import IntentRouterAdapter
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+from app.modules.agent.orchestration.v2_progress import build_progress_callback
+from app.schemas.common import ModuleName
+
+
+class RouteIntentStep:
+    def __init__(
+        self,
+        router: IntentRouterAdapter,
+        context_builder: TaskRuntimeContextBuilder,
+        enrichment: ContextEnrichmentService,
+    ) -> None:
+        self._router = router
+        self._context_builder = context_builder
+        self._enrichment = enrichment
+
+    async def run(self, context: ExecutionContext) -> None:
+        rag_session_id = context.session.active_rag_session_id
+        if not rag_session_id:
+            raise AppError(
+                "rag_session_not_bound",
+                "Agent session has no active rag_session_id for process v2.",
+                ModuleName.RAG,
+            )
+        request = context.request
+        loop = asyncio.get_running_loop()
+        task_context = self._context_builder.build(
+            task_id=request.request_id,
+            dialog_session_id=context.session.session_id,
+            rag_session_id=rag_session_id,
+            mode="auto",
+            message=request.message,
+            attachments=[],
+            files=[],
+            progress_cb=build_progress_callback(loop, context.publisher, request.request_id),
+            trace=context.trace,
+        )
+        task_context.enriched_context = self._enrichment.enrich(task_context)
+        context.task_context = task_context
+        await context.publisher.publish_status(
+            request.request_id,
+            "intent_router",
+            "Маршрутизирую запрос и определяю целевой workflow.",
+        )
+        route_result = await asyncio.to_thread(
+            self._router.route,
+            request.message,
+            task_context.conversation_state,
+            task_context.repo_context,
+            context.trace.module("intent_router"),
+        )
+        task_context.route_result = route_result
+        context.route_result = route_result
+        await context.publisher.publish_status(
+            request.request_id,
+            "intent_router",
+            f"Маршрут выбран: {route_result.intent} / {route_result.query_plan.sub_intent}.",
+            {
+                "intent": route_result.intent,
+                "sub_intent": route_result.query_plan.sub_intent,
+                "matched_intent_source": route_result.matched_intent_source,
+            },
+        )

src/app/modules/agent/orchestration/processes/v2/steps/run_task_workflow_step.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.adapters.task_runtime_adapter import TaskRuntimeAdapter
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+
+
+class RunTaskWorkflowStep:
+    def __init__(self, runtime: TaskRuntimeAdapter) -> None:
+        self._runtime = runtime
+
+    async def run(self, context: ExecutionContext) -> None:
+        request = context.request
+        context.trace_logger.log_step(request.request_id, "task_runtime", "started")
+        await context.publisher.publish_status(
+            request.request_id,
+            "orchestrator",
+            "Запускаю pipeline v2: intent router, rag retrieval и task workflow.",
+            {"process_version": request.process_version},
+        )
+        result = await self._runtime.run(context)
+        request.answer = result.answer or ""
+        context.trace_logger.log_step(
+            request.request_id,
+            "task_runtime",
+            "completed",
+            {
+                "result_type": getattr(result.result_type, "value", str(result.result_type)),
+                "meta": getattr(result, "meta", {}) or {},
+            },
+        )

src/app/modules/agent/orchestration/processes/v2/steps/workflow_step_base.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+
+
+class WorkflowStepBase:
+    intent_name = ""
+
+    def __init__(self, workflow, step_name: str) -> None:
+        self._workflow = workflow
+        self._step_name = step_name
+
+    def should_run(self, context: ExecutionContext) -> bool:
+        route_result = context.route_result
+        return bool(route_result) and str(route_result.intent or "").upper() == self.intent_name
+
+    async def run(self, context: ExecutionContext) -> None:
+        request = context.request
+        task_context = context.task_context
+        await context.publisher.publish_status(
+            request.request_id,
+            "task_workflow",
+            f"Запускаю workflow {self._workflow.workflow_id}.",
+            {"intent": context.route_result.intent, "sub_intent": context.route_result.query_plan.sub_intent},
+        )
+        result = await asyncio.to_thread(self._workflow.run, task_context)
+        context.workflow_result = result
+        request.answer = result.answer or ""
+        diagnostics = dict(result.meta.get("diagnostics") or {})
+        await self._publish_diagnostics(context, diagnostics, result)
+
+    async def _publish_diagnostics(self, context: ExecutionContext, diagnostics: dict[str, Any], result: Any) -> None:
+        request_id = context.request.request_id
+        if diagnostics:
+            await context.publisher.publish_status(
+                request_id,
+                "rag_retrieval",
+                "RAG retrieval завершен.",
+                {
+                    "planned_layers": list(diagnostics.get("planned_layers") or diagnostics.get("layers_used") or []),
+                    "executed_layers": list(diagnostics.get("executed_layers") or []),
+                    "non_empty_layers": list(diagnostics.get("non_empty_layers") or diagnostics.get("docs_layers_with_hits") or []),
+                },
+            )
+            await context.publisher.publish_status(
+                request_id,
+                "evidence_gate",
+                "Evidence gate оценен.",
+                {
+                    "decision": diagnostics.get("gate_decision"),
+                    "reason": diagnostics.get("gate_decision_reason"),
+                    "missing": list(diagnostics.get("gate_missing_requirements") or []),
+                    "satisfied": list(diagnostics.get("gate_satisfied_requirements") or []),
+                },
+            )
+        await context.publisher.publish_status(
+            request_id,
+            "workflow_result",
+            f"Workflow {self._workflow.workflow_id} завершен.",
+            {
+                "workflow_id": self._workflow.workflow_id,
+                "result_type": getattr(result.result_type, "value", str(result.result_type)),
+                "answer_length": len(result.answer or ""),
+            },
+        )

src/app/modules/agent/orchestration/runtime/process_runner.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from app.modules.agent.orchestration.context.execution_context import ExecutionContext
+
+
+class ProcessRunner:
+    async def run(self, context: ExecutionContext, steps: list) -> None:
+        for step in steps:
+            should_run = getattr(step, "should_run", None)
+            if callable(should_run) and not should_run(context):
+                continue
+            await step.run(context)

src/app/modules/agent/orchestration/v2_progress.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import asyncio
+
+from app.modules.agent.orchestration.messaging.client_message_publisher import ClientMessagePublisher
+
+
+def build_progress_callback(loop: asyncio.AbstractEventLoop, publisher: ClientMessagePublisher, request_id: str):
+    def progress_cb(stage: str, message: str, kind: str = "task_progress", meta: dict | None = None) -> None:
+        payload = dict(meta or {})
+        payload.setdefault("kind", kind)
+        asyncio.run_coroutine_threadsafe(
+            publisher.publish_status(request_id, stage, message, payload),
+            loop,
+        )
+
+    return progress_cb

src/app/modules/agent/runtime/__init__.py

@@ -1,6 +1,7 @@
 """Публичный API runtime: оркестрация роутинг → retrieval → evidence gate → генерация ответа."""
 
 from app.modules.agent.runtime.executor import AgentRuntimeExecutor
+from app.modules.agent.runtime.docs_qa_pipeline import DocsQAPipelineRunner
 from app.modules.agent.runtime.models import (
     RuntimeDraftAnswer,
     RuntimeExecutionState,
@@ -11,6 +12,7 @@ from app.modules.agent.runtime.steps.retrieval import RuntimeRepoContextFactory,
 
 __all__ = [
     "AgentRuntimeExecutor",
+    "DocsQAPipelineRunner",
     "RuntimeDraftAnswer",
     "RuntimeExecutionState",
     "RuntimeFinalResult",

src/app/modules/agent/runtime/docs_qa_pipeline/__init__.py

@@ -0,0 +1,9 @@
+from app.modules.agent.runtime.docs_qa_pipeline.models import DocsDiagnostics, DocsQAPipelineResult, OpenAPIResult
+from app.modules.agent.runtime.docs_qa_pipeline.pipeline import DocsQAPipelineRunner
+
+__all__ = [
+    "DocsDiagnostics",
+    "DocsQAPipelineRunner",
+    "DocsQAPipelineResult",
+    "OpenAPIResult",
+]