Як читати відповідь¶

Кожна операція повертає конверт однакової форми. Головне в ньому — не data. У data лежить те, що знайшлось; у попередженнях — те, чи можна цьому вірити. Плутати їх дорого: саме тут різниця між «немає» і «не шукали».

Форма¶

{
  "ok": true,
  "v": 1,
  "data": { "...": "..." },
  "warnings": [ {"code": "…", "text": "…"} ],
  "stale":  {"is": true, "reasons": ["…"], "fix": "nysh cases build"},
  "coverage": [ {"source": "…", "taken": "2026-07-02", "rows": 9020} ],
  "next": [ {"op": "…", "why": "…"} ]
}

ok: false → замість data буде error.

warnings присутній завжди, навіть порожній. Поле, яке то з'являється, то зникає, змушує кожного читача писати захисну перевірку — а той, хто напише пряме звертання, зламається не на попередженні, а на його відсутності, тобто на найспокійнішій відповіді.

coverage — навпаки, лише коли є. Порожній список у відповіді «завести справу» означав би «ніде не шукали» там, де питання пошуку взагалі не стояло.

У MCP текст іде ПЕРЕД даними¶

Твоя відповідь складається так: спершу людський текст (попередження, застарілість, покриття, підказки), потім зображення, якщо було, і аж потім повний JSON.

Це зроблено навмисно: модель читає текст надійніше за службові поля, і саме тут ховається різниця між «знайдено нуль» і «знайдено нуль, бо зріз застарів». Не пропускай перший блок. Якщо попереджень немає, його просто не буде — і це теж інформація.

🔴 Нуль зі знаменником¶

Правило має дві половини, і обидві реалізовані в коді.

Перша: джерело, яке не могло шукати, не додає нуль до суми. Каталог, який не зібрано, не відповідає «нічого не знайдено» — він відмовляється відповідати й каже, чого бракує. Якщо шукати не змогло жодне джерело, прийде:

⚠ жодне джерело не змогло шукати — цей нуль НІЧОГО не означає

Друга: джерело, яке змогло, називає знаменник. Скільки одиниць переглянуто, з якого зрізу, які межі покриття.

Попередження, які міняють сенс нуля¶

код	що означає	що робити
`no_denominator`	нуль порожній: не шукало жодне джерело	не звітувати «немає»; полагодити те, чого бракує
`zero_with_denominator`	нуль справжній, і ось у чому шукали	звітувати «немає в X прогонах / Y справах», не «немає»
`stale_catalog`	шукали у вкладеному зрізі, знятому тоді-то	назвати дату зрізу в звіті
`source_unavailable`	конкретне джерело шукати не змогло	сказати, яке саме випало
`no_registry_yet`	реєстру ще немає — це нормальний стан нового простору, не поламка	`nysh cases build`
`case_dir_unknown`	реєстр не знає, де лежать скани справи	«0 переглянуто» тут не означає «нічого не дивились»

⚠ Знаменник не в одному місці. У catalog.search і search.run покриття лежить у data.coverage як звичайне поле — і тому не потрапляє в рядок 🔎 шукали в: першого блоку. Читай попередження; сподіватись на єдине уніфіковане поле не можна.

Ціна цієї недбалості вимірювана. Одного разу знаменник читався не з того поля, і на просторі з 506 прогонами та 320 669 сторінками відповідь звучала так: «не знайшлось у 506 прогонах (0 сторінок)». Формально правда; фактично — зруйноване головне правило, бо нуль у дужках знецінює все речення.

🔴 Застарілість¶

stale каже, що відповідь побудована на зрізі, який міг відстати:

⚠ ЗРІЗ ЗАСТАРІВ (у просторі щось міняли після збірки) — числу нижче
  вірити не можна. Полагодити: nysh cases build

Реєстр справ — зліпок кількох сховищ, і будь-який прогін, пошук чи твій власний запис робить його старим за хвилини. Застарілий зріз небезпечніший за відсутній: він виглядає як відповідь («декоду немає») там, де роботу зробили годину тому — і рішення «що робити далі» ухвалюють саме по ньому.

Є ще третій стан, окрім «свіжий» і «застарів»: unknown. Він означає «через застосунок нічого не міняли» — але файл, покладений у теку провідником, ніяк себе не виявляє. Тобто «застарів» тут швидке й надійне, а «свіжий» — ніколи не гарантія.

`next` — підказки, яких майже немає¶

Механізм «що робити далі» існує, але заповнений в одному місці: після pages.status тобі підкажуть занести переглянуте.

Не розраховуй, що конвеєр поведе себе сам. Порядок кроків — у docs/agents/workflows.md, і тримати його доводиться тобі.

Помилки¶

Помилка операції — це звичайна відповідь з ok: false, а не збій транспорту. Текст помилки писаний для людини й майже завжди містить дію:

секція «читання» вимкнена у профілі простору.
  увімкнути: nysh sections enable htr

Дві типові причини, які виглядають як поламка, але нею не є:

вимкнена секція — простір налаштований пресетом, у якому цієї частини немає. Перевір nysh sections на початку сесії, а не після відмови;
довга операція через MCP — див. docs/agents/surface.md.

Коротко¶

Читай перший текстовий блок повністю — він про довіру до чисел.
Нуль без знаменника не звітується як «немає».
stale.is == true знецінює числа, доки не перезібрано реєстр.
ok: false — частіше конфігурація, ніж поламка.