Синхронизация документации и кода

docs/specs/recognition.md

@@ -5,7 +5,8 @@
 По доступным сигналам определить: фильм или сериал; каноническое название
 и год; для сериала — сезон(ы) и соответствие файлов сериям; при включённых
 базах — провайдер и его id. На выходе — план раскладки, оценка уверенности
-и решение «авто или review».
+и решение «авто или review» (как оно встраивается в машину состояний —
+[workflow.md](workflow.md), состояния `recognizing`/`linking`/`review`).
 
 ## Сигналы
 
@@ -33,8 +34,10 @@
    пред-парс, возвращает структурированный план в нашей схеме. Хорошо
    берёт русские релиз-имена. Длинный список файлов усекаем/семплируем под
    контекст модели.
-3. **Сверка с базой** (если включена TMDB/TVDB): ищем по названию+году,
-   берём официальный id и каноническое имя, собираем кандидатов.
+3. **Сверка с базой** (если включена TMDB/TVDB/TVMaze): ищем по
+   названию+году, берём официальный id и каноническое имя, собираем
+   кандидатов. TVMaze — без ключа, только сериалы; внешний id
+   (TVDB/IMDb) из `externals` идёт в имя папки.
 4. **Оценка уверенности** и решение: авто или review.
 
 ## Структура ответа LLM (предварительная)
@@ -54,8 +57,8 @@ notes           пояснения, неоднозначности
 Сезон/серия — **на файле**: так выражаются мультисезонные паки,
 спецвыпуски и смешанные раскладки; отдельного скалярного `season` нет.
 `provider_hint` — только подсказка для поиска; итоговые `provider`
-(`tmdb|tvdb|none`) и `provider_id` появляются после сверки с базой и
-хранятся отдельно.
+(`tmdb|tvdb|tvmaze|none`) и `provider_id` появляются после сверки с базой
+и хранятся отдельно.
 
 ## Провайдер LLM
 
@@ -67,13 +70,13 @@ notes           пояснения, неоднозначности
   Chat Completions API (`base_url` + `api_key` + `model`). Подходят
   локальные серверы (LM Studio, llama.cpp, Ollama) и облачные совместимые
   провайдеры (DeepSeek, Qwen и др.).
-- **Структурированный вывод надёжно:** просим JSON по схеме
-  (`response_format` со схемой где поддерживается; иначе json-режим или
-  tool-call); на приёме срезаем ```-ограждения и извлекаем JSON,
-  **валидируем в Go**, ретраим со схемой-в-промпте до `llm.max_retries`;
-  если так и не распарсилось — уходим в **review** (не в `failed`) с
-  причиной «ответ LLM не разобран». Серверы заметно различаются по
-  поддержке строгих схем, особенно мелкие локальные модели.
+- **Структурированный вывод надёжно:** просим JSON-режим
+  (`response_format: {"type":"json_object"}`) — это поддерживают и мелкие
+  локальные модели, в отличие от строгих JSON Schema. На приёме срезаем
+  ```-ограждения и извлекаем JSON, **валидируем в Go** против нашей схемы;
+  при ошибке разбора ретраим, передавая модели саму ошибку и схему в
+  промпте, до `llm.max_retries`. Если так и не распарсилось — уходим в
+  **review** (не в `failed`) с причиной «ответ LLM не разобран».
 - Новые типы (напр. нативный `anthropic`) добавляются, не трогая
   `recognize`.
 
@@ -82,7 +85,7 @@ notes           пояснения, неоднозначности
 Авто-раскладка — только если выполнено **всё**:
 
 1. **Подтверждённый матч в базе** — единственный сильный результат
-   TMDB/TVDB по названию+году, давший `provider_id`. **Нет матча (или
+   TMDB/TVDB/TVMaze по названию+году, давший `provider_id`. **Нет матча (или
    база выключена) → всегда review.** Это и закрывает основной кейс
    (рус/аниме часто отсутствуют в базах), и снимает риск «LLM придумал».
 2. **Структурная валидация** без предупреждений: