docs: clarify scope (generation-first) and index snapshot freshness

HELP.md

@@ -21,10 +21,14 @@
 ### Основні можливості:
 
 - ✅ **Генерація** правових позицій з текстів судових рішень
-- ✅ **Пошук** схожих позицій у базі даних Верховного Суду
-- ✅ **Аналіз** релевантності знайдених позицій
-- ✅ **Налаштування** промптів для персоналізації роботи AI
+- ✅ **Налаштування моделей** (вибір провайдера/моделі + режими «роздумів») і **поле коментаря** для уточнення генерації
+- ✅ **Налаштування промптів** для персоналізації роботи AI
 - ✅ **Пакетне тестування** для масової обробки даних
+- 🟡 **Пошук / Аналіз** (опціонально): може бути вимкнено у поставці, якщо це не входить у ТЗ
+
+⚠️ **Примітка про дані для пошуку:** якщо пошук увімкнений, індекси можуть завантажуватися з відкритого датасету `DocSA/legal-position-indexes`. Це тестовий snapshot приблизно **1.5 роки давності** і він може бути неактуальним.
+
+Докладніше: `docs/SCOPE_AND_DATA_FRESHNESS.md`
 
 ---
 
@@ -101,6 +105,10 @@
 ### Призначення
 Знайти схожі правові позиції Верховного Суду у базі даних.
 
+⚠️ **Статус функції:** пошук може бути **опціональним** у поставці (якщо він не входить у ТЗ). Якщо пошук вимкнено — це не впливає на роботу розділу «Генерація».
+
+⚠️ **Актуальність бази:** якщо пошук увімкнений і використовує індекси з `DocSA/legal-position-indexes`, врахуйте що це тестовий snapshot приблизно **1.5 роки давності** і він може не містити нових/оновлених позицій після дати snapshot.
+
 ### Два типи пошуку:
 
 #### 1. Пошук на основі правової позиції

README.md

@@ -15,6 +15,16 @@ python_version: "3.11"
 
 Інтелектуальний інструмент для аналізу судових рішень та формування правових позицій Верховного Суду України з використанням AI.
 
+## 🎯 Scope для поставки (LPD / Верховний Суд)
+
+Поточний фокус замовника — **модернізація функціонала генерації правових позицій** (розділ «Генерація» + налаштування моделей/«роздумів» + поле коментаря).
+
+- **In-scope (MVP):** генерація правових позицій + узгоджені налаштування моделей/Thinking/Comment.
+- **Out-of-scope (якщо не прописано в ТЗ):** пошук і порівняльний аналіз можуть розглядатися як *опціональні* (і за потреби вимикаються у customer build).
+- **Важливо про пошук:** якщо search/analysis увімкнено, індекси можуть завантажуватися з `DocSA/legal-position-indexes`, але це тестовий snapshot приблизно **1.5 роки давності** (може бути неактуальним).
+
+Докладніше: [`docs/SCOPE_AND_DATA_FRESHNESS.md`](docs/SCOPE_AND_DATA_FRESHNESS.md)
+
 ## 🚀 Основні можливості
 
 ### 💡 Генерація правових позицій

docs/SCOPE_AND_DATA_FRESHNESS.md

@@ -0,0 +1,58 @@
+# Scope, data freshness & expectations (LPD / Верховний Суд)
+
+Цей документ фіксує **межі поставки (scope)** та **очікування щодо даних**, щоб уникнути непорозумінь при передачі коду замовнику.
+
+## 1) In-scope (обов’язково для MVP)
+
+### 1.1 Генерація правових позицій
+- Вкладка/розділ: **«Генерація правових позицій»**.
+- Вхід: текст / URL / файл.
+- Вихід: **структурований JSON** з полями: `title`, `text`, `proceeding`, `category`.
+
+### 1.2 Налаштування моделей і режимів «роздумів»
+Для розділу генерації мають бути узгоджені (з порталом) параметри:
+- `provider` (openai | anthropic | gemini | deepseek)
+- `model`
+- `thinking_enabled` (true/false)
+- `thinking_level` (low | medium | high) — **уніфікований** рівень; деталізація/мапінг до провайдерів робиться в backend.
+- (опційно) `openai_verbosity` (low | medium | high) — якщо замовник хоче це в UI.
+
+### 1.3 Додаткове поле «Коментар» (опціонально)
+- UI: textarea **«Коментар до генерації (опціонально)»**.
+- Backend payload: `comment`.
+- Призначення: дати моделі коротку інструкцію/акцент (що підкреслити, який аспект важливий тощо).
+
+## 2) Out-of-scope (не є критерієм приймання MVP, якщо не зазначено в ТЗ)
+
+### 2.1 Пошук схожих позицій
+Функціонал пошуку (vector+BM25) може бути:
+- залишений у коді як **опціональний**, або
+- **вимкнений у customer build**, якщо замовнику зараз не потрібен.
+
+### 2.2 Порівняльний аналіз / прецедентний аналіз
+Аналіз результатів пошуку також вважається **опціональним**, якщо він не прописаний у ТЗ.
+
+## 3) Джерело індексів (search KB) та актуальність даних
+
+Якщо пошук увімкнений, застосунок може завантажувати індекси з HuggingFace Dataset:
+- `https://huggingface.co/datasets/DocSA/legal-position-indexes`
+
+### Важливий нюанс
+- Ця база індексів була отримана **приблизно 1.5 роки тому** як тестовий snapshot від ВС.
+- З того часу вона **не оновлювалася**.
+
+### Наслідки
+- Пошук/аналіз може **не знаходити** нові/оновлені позиції після дати snapshot.
+- Це **не дефект генерації**; це обмеження актуальності корпусу для retrieval-компоненти.
+
+### Як комунікуємо замовнику
+- У документації та Help UI має бути явна примітка: **search/analysis optional + data snapshot may be outdated**.
+- За потреби — показувати користувачу `Index snapshot: …` (якщо буде додано manifest/version).
+
+## 4) Якщо замовнику колись знадобиться актуалізація
+Це окремий потік робіт (не обов’язково для MVP):
+- хто надає нові дані (ВС / відповідальна сторона)
+- хто будує індекси
+- де вони зберігаються
+- частота оновлень (разово / періодично)
+