@nitra/cursor 12.9.0 → 12.11.0

package/.claude-template/settings.template.json

@@ -16,32 +16,10 @@
         "hooks": [
           {
             "type": "command",
-            "command": "npx --no @nitra/cursor post-tool-use-check",
+            "command": "npx --no @nitra/cursor hook --post-tool-use",
             "timeout": 300
           }
         ]
-      },
-      {
-        "matcher": "Edit|Write|MultiEdit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npx --no @nitra/cursor lint-doc-files --hook",
-            "timeout": 120
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npx --no @nitra/cursor lint-doc-files --git",
-            "timeout": 120
-          }
-        ]
       }
     ]
   }

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [12.11.0] - 2026-06-25
+
+### Changed
+
+- Додано перевірку на наявність `CHANGELOG.md` та його формату в workspace-ах
+
+## [12.10.0] - 2026-06-24
+
+### Changed
+
+- Оновлено LLM-виклик для повернення багатого об'єкта з reasoning та thinkingBudget
+
 ## [12.9.0] - 2026-06-24
 
 ### Changed

package/bin/n-cursor.js

@@ -7,17 +7,13 @@
  *   `npx \@nitra/cursor`             — завантажити cursor-правила (синк); якщо в корені вже є `.n-cursor.json`,
  *                                     спочатку зчитується конфіг і за потреби дописується `$schema`
  *   `npx \@nitra/cursor rename-yaml-extensions` — k8s `*.yml` → `*.yaml`, `.github` `*.yaml` → `*.yml` (опції: `--dry-run`, `--root=…`; див. bin/rename-yaml-extensions.mjs)
- *   `npx \@nitra/cursor post-tool-use-check` — точка входу PostToolUse hook Claude Code: читає stdin JSON,
- *                                     дістає `tool_input.file_path`, маршрутизує його у відповідні правила
- *                                     (`*.mjs` → `js-lint`, `*.vue` → `js-lint style vue` тощо) і викликає
- *                                     `fix` лише з ними. Прописується автоматично в `.claude/settings.json`.
+ *   `npx \@nitra/cursor hook --post-tool-use` — PostToolUse hook: per-file lint правила для зміненого файлу (stdin JSON `tool_input.file_path`). Прописується автоматично в `.claude/settings.json`.
+ *   `npx \@nitra/cursor hook --stop`           — Stop hook: per-file lint по всіх змінених файлах (git diff HEAD + untracked).
  *   `npx \@nitra/cursor lint`        — data-driven оркестратор lint+конформності по `rules/<id>/meta.json` (`lint: per-file|full`):
  *                                     за замовчуванням fix-by-default по дельті vs origin (лише `per-file` правила); `--full` =
  *                                     весь репо (`per-file` ∪ `full`); `--read-only` = без мутацій/LLM (CI); позиційні
  *                                     (не-флаг) аргументи — фільтр правил конформності (мапить колишній `fix <rule>`).
  *                                     CI = `lint --read-only --full` (весь репо, нуль мутацій/LLM).
- *   `npx \@nitra/cursor lint-doc-files`  — детермінований детектор застарілості файлових док (`stale`: `missing`|`crc-mismatch`); правило doc-files (ignore-glob у `npm/rules/doc-files/js/docgen-ignore.mjs`; тека `docs/` поряд із джерелом). Режими: повний (exit 1), `--json` (exit 0), `--missing-only`, `--hook`/`--git` (hook-протокол, exit 2), `--degraded`
- *   `npx \@nitra/cursor fix-doc-files`   — JS-оркестрована генерація файлових док (роутинг local/cloud) зі штампом CRC (`--limit`/`--from`/`--overwrite`); `--stamp` — детерміноване перештампування CRC без LLM
  *   `npx \@nitra/cursor doc-aggregate modules` — JSON-лістинг логічних модулів (межі за `package.json`) для Tier 2 скілу doc-aggregate
  *   `npx \@nitra/cursor skill list`     — скіли пакета без синку в проєкт
  *   `npx \@nitra/cursor skill taze`     — промпт на stdout
@@ -74,7 +70,7 @@ import { fileURLToPath } from 'node:url'
 
 import { buildAgentsCommandBulletItems } from '../scripts/build-agents-commands.mjs'
 import { formatGeneratedMarkdownLines, renderAgentsTemplate } from '../scripts/lib/generated-markdown.mjs'
-import { inlineMarkdownIncludes, inlineTemplateLinks } from '../scripts/lib/inline-template-links.mjs'
+import { appendDiscoveredMdcFiles, inlineTemplateLinks } from '../scripts/lib/inline-template-links.mjs'
 import {
   detectAutoRules,
   detectLegacyRuleIds,
@@ -86,7 +82,6 @@ import { detectAutoSkills } from '../scripts/auto-skills.mjs'
 import { readSkillMetaRaw } from '../scripts/lib/skill-meta.mjs'
 import { injectWorktreeNotice } from '../scripts/lib/worktree-notice.mjs'
 import { injectRootNotice } from '../scripts/lib/root-notice.mjs'
-import { runPostToolUseCheckCli } from '../scripts/post-tool-use-check.mjs'
 import { listProjectRulesMdcFiles } from '../scripts/lib/list-project-rules-mdc.mjs'
 import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
 import { assertCwdIsProjectRoot } from '../scripts/lib/assert-project-root.mjs'
@@ -423,7 +418,7 @@ async function readBundledRuleContent(rule, bundledRulesDir = BUNDLED_RULES_DIR)
   }
   const text = await readFile(bundledPath, 'utf8')
   const withTemplates = await inlineTemplateLinks(text, dirname(bundledPath))
-  return inlineMarkdownIncludes(withTemplates, dirname(bundledPath))
+  return appendDiscoveredMdcFiles(withTemplates, dirname(bundledPath))
 }
 
 /**
@@ -655,7 +650,7 @@ function buildClaudeDocFilesSectionLines() {
     '',
     '## Файлова документація (`doc-files` — обовʼязковий крок, як lint)',
     '',
-    'Після зміни чи додавання кодового файлу його файлова дока (`<dir>/docs/<stem>.md`) має бути **актуальною** — це **обовʼязковий крок кожної задачі**, нарівні з lint. Застарілість детермінується за **CRC** джерела у frontmatter доки. PostToolUse hook (`lint-doc-files --hook`) **сигналить** про дрейф після правки; Stop-hook (`lint-doc-files --git`) **блокує завершення** задачі за наявності застарілих док (виняток — масовий прогін понад поріг `N_CURSOR_DOC_FILES_GATE_MAX`, дефолт 50). Регенерація — `/doc-files` (JS-оркестрована, не диспатч субагентів). Агрегуюча дока (module-summary, доменні) — окремий скіл `/doc-aggregate`, за запитом.',
+    'Після зміни чи додавання кодового файлу його файлова дока (`<dir>/docs/<stem>.md`) має бути **актуальною** — це **обовʼязковий крок кожної задачі**, нарівні з lint. Застарілість детермінується за **CRC** джерела у frontmatter доки. PostToolUse hook (`hook --post-tool-use`) **сигналить** про дрейф після правки через per-file lint правила. Регенерація — `/doc-files` (JS-оркестрована, не диспатч субагентів). Агрегуюча дока (module-summary, доменні) — окремий скіл `/doc-aggregate`, за запитом.',
     ''
   ]
 }
@@ -1459,7 +1454,7 @@ async function runSync() {
 /**
  * Команди, що мутують проєкт у CWD і вимагають кореня репо. `undefined`/`''` —
  * дефолтний sync; `check` — deprecated-alias `fix`. Решта (read-only `trace`,
- * `--root`-команди `lint-doc-files`/`fix-doc-files`/`doc-files`/`doc-aggregate`/`rename-yaml-extensions`,
+ * `--root`-команди `doc-aggregate`/`rename-yaml-extensions`,
  * sub-лінтери) гард не зачіпає.
  */
 const ROOT_GUARDED_COMMANDS = new Set([undefined, '', 'lint', 'coverage', 'change', 'release'])
@@ -1501,7 +1496,7 @@ try {
   // .n-cursor.json + bun install, а fix/lint/coverage/change/release переписують файли в CWD —
   // усе це ключиться на cwd(). Запуск із піддиректорії git-репо (типово прямий
   // `bun npm/bin/n-cursor.js` не з кореня) зачепив би не той каталог → STOP. Read-only та
-  // `--root`-команди (trace, graph, lint-doc-files, fix-doc-files, doc-aggregate, rename-yaml-extensions) не зачіпаємо.
+  // `--root`-команди (trace, graph, doc-aggregate, rename-yaml-extensions) не зачіпаємо.
   if (ROOT_GUARDED_COMMANDS.has(command)) {
     assertCwdIsProjectRoot(cwd(), describeRootGuardedAction(command))
   }
@@ -1524,13 +1519,6 @@ try {
 
       break
     }
-    case 'post-tool-use-check': {
-      // @deprecated: використовуй `hook --post-tool-use`
-      const code = await runPostToolUseCheckCli()
-      process.exitCode = code
-
-      break
-    }
     case 'lint': {
       // Дві ортогональні осі: --full (scope: весь репо vs дельта vs origin) × --read-only (behavior).
       // Позиційні (не-флаг) аргументи — фільтр правил конформності (напр. `lint changelog`):
@@ -1614,29 +1602,6 @@ try {
 
       break
     }
-    case 'lint-doc-files': {
-      // n-cursor lint-doc-files — детермінований детектор застарілості файлових док
-      // (missing ∪ crc-mismatch). Режими: (повний) exit 1, --json exit 0, --missing-only,
-      //   --hook/--git/--degraded — hook-протокол (exit 2/0). Деталі — doc-files.mdc.
-      const { runLintDocFilesCli } = await import('../rules/doc-files/main.mjs')
-      process.exitCode = await runLintDocFilesCli(args)
-
-      break
-    }
-    case 'fix-doc-files': {
-      // n-cursor fix-doc-files — local-only генерація файлових док (omlx) + CRC-штамп
-      // (--limit/--from/--overwrite); --stamp — детерміноване
-      // перештампування source+crc без LLM. У CI не запускається (потрібна локальна модель).
-      if (args.includes('--stamp')) {
-        const { runDocFilesStampCli } = await import('../rules/doc-files/js/docgen-files-batch.mjs')
-        process.exitCode = runDocFilesStampCli(args.filter(a => a !== '--stamp'))
-      } else {
-        const { runDocFilesGenCli } = await import('../rules/doc-files/js/docgen-files-batch.mjs')
-        process.exitCode = await runDocFilesGenCli(args)
-      }
-
-      break
-    }
     case 'adr-normalize-local': {
       // Local-backend ADR-нормалізації: викликається з .claude/hooks/normalize-decisions.sh
       // як заміна single-shot LLM-виклику. Проганяє конвеєр (retrieval→edge-judge→
@@ -1669,7 +1634,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, hook, adr-normalize-local, lint (включно зі scope: lint ga|rego|k8s|docker|text), fix-doc-files, coverage, coverage-fix, analyze-escalation, taze, start-check, change, release, skill, trace, doc-aggregate`
+        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, hook, adr-normalize-local, lint (включно зі scope: lint ga|rego|k8s|docker|text), coverage, coverage-fix, analyze-escalation, taze, start-check, release, skill, trace, doc-aggregate`
       )
       process.exitCode = 1
     }

package/docs/stryker.config.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Цей файл конфігурує процес тестування та мутаційного аналізу, використовуючи Vitest як тестовий раннер. Він визначає, які файли підлягають мутації (у `scripts`, `rules`, `bin`) та які виключаються, спираючись на `mutation.json`. Конфігурація налаштовує Stryker для запуску лише тестів, що покривають мутовані рядки. Також конфігурація використовує `incremental.json` для збереження даних між запусками.
 
 ## Поведінка

package/lib/docs/llm.md

@@ -3,36 +3,31 @@ type: JS Module
 title: llm.mjs
 resource: npm/lib/llm.mjs
 docgen:
-  crc: 7b27f689
+  crc: 22d2906f
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Файл надає механізми для виклику великих мовних моделей. Маршрутизація вибору транспортного каналу залежить від префікса ідентифікатора моделі згідно з конвенцією `npm/lib/models.mjs`. Виклик LLM виконує виклик з визначеною маршрутизацією та запис трасування. Перевірка стану omlx сервера визначає доступність моделі.
+Файл є єдиною точкою LLM-викликів для JS-оркестраторів (див. ADR 260610-2228). Він маршрутизує запити виключно за префіксом `model-id` (конвенція `npm/lib/models.mjs`): `omlx/<model>` — прямий HTTP до локального omlx-сервера (`callOmlx`), будь-що інше — через `pi` CLI (хмарні провайдери або pi-дефолт). Рядок моделі сам визначає транспорт; відсутні env-перемикачі бекенду. Кожен виклик має **always-on** багатий JSONL-запис трасування (reasoning + слід). Для `omlx` захоплюються `content/reasoning/usage/finish_reason/attempts`, для `pi` — лише те, що надає CLI (rich-поля null). Код спирається на конфігурації, визначені у settings.json.
 
 ## Поведінка
 
-pickBackend
-Маршрутизує модель по префіксу до визначеного бекенда
-
-callLlm
-Виконує універсальний виклик LLM з маршрутизацією за моделью та wire-trace
-
-omlxHealthCheck
-Перевіряє стан omlx сервера для визначення доступності моделі
+pickBackend визначає, чи має бути використаний локальний omlx-сервер для виклику LLM, чи зовнішній CLI `pi`, на основі префікса `model-id`.
+callLlmRich виконує універсальний виклик LLM з маршрутизацією між omlx та `pi` CLI, завжди записуючи детальний слід (wire-trace) для обох каналів, і повертає вміст та монолог обробки.
+callLlm повертає лише текстовий вміст відповіді від LLM, використовуючи `callLlmRich` як внутрішню обгортку.
+classifyOmlxError класифікує помилку, отриману від omlx-сервера, як тимчасову, системну чи постійну, для прийняття рішення оркестратором.
+omlxHealthCheck виконує мінімальний перевірочний виклик до omlx-сервера для визначення його стану (працює, потребує ключа, перевантажений).
+preflightLocalModel перевіряє стан локальної omlx-моделі, щоб визначити, чи можна безпечно ініціювати виклик, надаючи зрозуміле повідомлення про проблеми з пам'яттю, автентифікацією чи доступністю сервера.
 
 ## Публічний API
 
-pickBackend — Бекенд для model-id: `omlx` — прямий HTTP, `pi` — CLI.
-callLlm — Універсальний виклик LLM з маршрутизацією за префіксом model-id і постійне відстеження (wire-trace) обох каналів.
-omlxHealthCheck — Перевірка omlx перед масовим прогоном через мінімальний чат-виклик (`max_tokens: 1`). Розрізняє стани:
-down — Сервер не відповідає (не запущений / не той порт).
-memory-guard — Модель не влазить у динамічну стелю пам'яті зайнятої машини — відкладає прогін.
-auth — Сервер вимагає API-ключ — виставляє `N_CURSOR_OMLX_KEY`.
-error — Інша помилка API.
-Порожній контент відповіді — означає, що сервер живий і модель завантажена.
+pickBackend — Визначає, який механізм зв'язку використовувати для моделі: прямий HTTP або CLI.
+callLlmRich — Виконує універсальний запит до LLM, маршрутизуючи його за префіксом моделі та відстежуючи трасування, повертаючи детальний об'єкт з відповіддю та логікою обґрунтування.
+callLlm — Викликає LLM, повертаючи лише текстовий вміст відповіді, зберігаючи сумісність зі старими споживачами.
+classifyOmlxError — Аналізує помилки omlx після вичерпання внутрішніх спроб, щоб визначити, чи потрібно ігнорувати, зупинити роботу (circuit-breaker) чи обробляти як звичайну помилку.
+omlxHealthCheck — Перевіряє готовність omlx-сервера мінімальним запитом, щоб визначити його стан: відсутність відповіді, обмеження пам'яті, відсутність ключа або інша помилка.
+preflightLocalModel — Перевіряє можливість використання локальної моделі для швидкого пропуску викликів, використовуючи файли документації та словники.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/lib/docs/omlx.md

@@ -3,44 +3,39 @@ type: JS Module
 title: omlx.mjs
 resource: npm/lib/omlx.mjs
 docgen:
-  crc: 9a14ddbe
-  score: 90
+  crc: 23163fe9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Файл забезпечує комунікацію з локальним omlx-сервером для отримання відповідей. Він маршрутизує запити, використовуючи конвенцію префікса для визначення, чи слід використовувати прямий HTTP виклик до omlx, чи CLI. Функції надають інструменти для роботи з API ключами та викликів до inference-сервера.
+Модуль реалізує логіку маршрутизації запитів до локального omlx-сервера, який надає OpenAI-сумісні відповіді за адресою `http://localhost:8000/v1/chat/completions`. Константа DEFAULT_OMLX_URL визначає цю базову адресу. Модуль визначає, чи є модель локальною, аналізуючи префікс у `model-id` (`omlx/<model>`). Якщо модель локальна, виконується прямий HTTP-запит до omlx. Якщо ж модель не локальна, запит спрямовується до pi CLI. При необхідності, API-ключ для omlx резолвиться з конфігураційного файлу settings.json або змінної N_CURSOR_OMLX_KEY і передається у заголовку `Authorization: Bearer …`. Обробка обмежується лише текстовим контентом, оскільки сервер не підтримує виклики інструментів.
 
 ## Поведінка
 
-DEFAULT_OMLX_URL: Дефолтний endpoint omlx
+DEFAULT_OMLX_URL надає стандартний URL для доступу до omlx-сервера, який є `http://127.0.0.1:8000/v1/chat/completions`.
+resolveOmlxApiKey визначає API-ключ для omlx-сервера, шукаючи його в опціях виклику, змінній середовища `N_CURSOR_OMLX_KEY` або в файлі `~/.omlx/settings.json`.
+isOmlxModel перевіряє, чи відповідає наданий model-id локальному omlx-бекенду, тобто чи починається він з префікса `omlx/`.
+omlxModelId видаляє префікс `omlx/` з model-id, якщо він присутній, для отримання чистого ідентифікатора для omlx API.
+extractReasoning витягує текст думок (reasoning) з відповіді omlx-сервера, надаючи його разом із джерелом вилучення (поле, тег ``або зрізаний контент).
+callOmlxRaw виконує блокуючий HTTP-виклик до omlx-сервера через`curl`, повторюючи спроби при транзієнтних помилках, і повертає багатий об'єкт з контентом, думками, використанням та статусом завершення.
+callOmlx викликає `callOmlxRaw` і повертає лише текстовий контент відповіді від omlx-сервера.
 
-resolveOmlxApiKey: Резолвить API ключ для omlx-сервера
-
-DEFAULT_OMLX_MODEL: Дефолтна модель для omlx
+## Публічний API
 
-isOmlxModel: Перевіряє, чи model-id адресує локальний omlx-бекенд
+DEFAULT_OMLX_URL — Дефолтний URL для звернення до omlx-сервера, який може бути перевизначений.
 
-omlxModelId: Прибирає префікс omlx/ з model-id
+resolveOmlxApiKey — Визначає ключ доступу до omlx-сервера, використовуючи пріоритет: явний ключ, змінна середовища, конфігурація з `settings.json` або відсутність ключа.
 
-extractReasoning: Витягує reasoning з message
+isOmlxModel — Визначає, чи ідентифікатор моделі вказує на локальний omlx-бекенд (за наявністю префікса `omlx/`).
 
-callOmlxRaw: Ядро прямого HTTP-виклику до omlx через curl
+omlxModelId — Видаляє префікс `omlx/` з ідентифікатора моделі, залишаючи чистий ідентифікатор для API.
 
-callOmlx: Тонка обгортка для отримання тексту відповіді
+extractReasoning — Витягує внутрішні роздуми моделі з відповіді omlx, шукаючи їх у спеціальному полі, тегу `` або в тексті, якщо відповідь була обрізана.
 
-## Публічний API
+callOmlxRaw — Здійснює прямий HTTP-запит до omlx, повертаючи повний об'єкт відповіді (включаючи контент, роздуми, використання та причину завершення). Автоматично повторює запит при тимчасових збоях.
 
-DEFAULT_OMLX_URL — дефолтний endpoint omlx (перевизначається як `N_CURSOR_OMLX_URL`).
-resolveOmlxApiKey — отримує API-ключ для omlx-сервера, коли ввімкнено автентифікацію (`auth.skip_api_key_verification: false`). Порядок: явний `apiKey` → env `N_CURSOR_OMLX_KEY` → `auth.api_key` з `~/.omlx/settings.json` (для локальної машини, з читанням як за замовчуванням; читання як за замовчуванням; безпечне читання) → `null` (відсутність заголовка).
-DEFAULT_OMLX_MODEL — дефолтна модель, якщо в ідентифікаторі залишився префікс `omlx/` (перевизначається як `N_CURSOR_OMLX_MODEL`).
-isOmlxModel — перевіряє, чи адресує цей model-id локальний omlx-бекенед (наявність префікса `omlx/`).
-omlxModelId — видаляє префікс `omlx/` — отримує чистий model-id для omlx API. Не-omlx-рядки повертаються без змін.
-extractReasoning — витягує обґрунтування з відповіді.
-callOmlxRaw — виконує прямий HTTP-виклик до omlx через `curl` (за допомогою `spawnSync`). Повертає збагачений об'єкт: контент, обґрунтування, використання, результат завершення та кількість спроб. Перезапускає лише тимчасові помилки curl (18 = закритий трансфер, 52 = порожня відповідь, 56 = збій при отриманні).
-callOmlx — тонко інкапсулює `callOmlxRaw` для споживачів, яким потрібен лише текст. Контракт: повертає вміст з `choices[0].message.content`. Без використання заголовків чи загальних фраз.
+callOmlx — Спрощує виклик до omlx, повертаючи лише текстовий вміст відповіді, ігноруючи інші деталі.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/lib/llm.mjs

@@ -52,14 +52,14 @@ function callPi(messages, model, timeoutMs) {
 
 /**
  * Універсальний LLM-виклик з маршрутизацією за префіксом model-id і always-on
- * wire-trace (обидва канали).
+ * wire-trace (обидва канали). Повертає **багатий** обʼєкт із вмістом і reasoning.
  * @param {Array<{role:string, content:string}>} messages OpenAI-style messages (system зберігається на omlx)
  * @param {string} model model-id; `omlx/<m>` → прямий HTTP, інакше → pi CLI
- * @param {{ timeoutMs?: number, temperature?: number, maxTokens?: number, url?: string, caller?: string }} [opts] timeout, температура, ліміт виходу, override URL, мітка викликача для trace
- * @returns {string} текст відповіді (непорожній на omlx; pi може повернути '')
+ * @param {{ timeoutMs?: number, temperature?: number, maxTokens?: number, url?: string, caller?: string, thinkingBudget?: number }} [opts] timeout, температура, ліміт виходу, override URL, мітка викликача для trace, бюджет thinking-токенів (лише omlx)
+ * @returns {{ content: string, reasoning: string|null, reasoningSource: string|null }} вміст відповіді і thinking-монолог
  */
-export function callLlm(messages, model, opts = {}) {
-  const { timeoutMs = DEFAULT_TIMEOUT_MS, temperature = 0.2, maxTokens, url, caller } = opts
+export function callLlmRich(messages, model, opts = {}) {
+  const { timeoutMs = DEFAULT_TIMEOUT_MS, temperature = 0.2, maxTokens, url, caller, thinkingBudget } = opts
   const backend = pickBackend(model)
   const resolvedCaller = caller ?? env.N_CURSOR_TRACE_CALLER ?? 'unknown'
   const t0 = Date.now()
@@ -71,7 +71,13 @@ export function callLlm(messages, model, opts = {}) {
     let usage = null
     let attempts = 1
     if (backend === 'omlx') {
-      const raw = callOmlxRaw(messages, model, { url, timeoutMs, temperature, ...(maxTokens ? { maxTokens } : {}) })
+      const raw = callOmlxRaw(messages, model, {
+        url,
+        timeoutMs,
+        temperature,
+        ...(maxTokens ? { maxTokens } : {}),
+        ...(thinkingBudget ? { thinkingBudget } : {})
+      })
       ;({ content, reasoning, reasoningSource, finishReason, usage, attempts } = raw)
     } else {
       content = callPi(messages, model, timeoutMs)
@@ -96,7 +102,7 @@ export function callLlm(messages, model, opts = {}) {
         error: null
       })
     )
-    return content
+    return { content, reasoning, reasoningSource }
   } catch (error) {
     writeTrace(
       buildTraceRecord({
@@ -117,6 +123,18 @@ export function callLlm(messages, model, opts = {}) {
   }
 }
 
+/**
+ * Тонка обгортка над `callLlmRich` — повертає лише рядок контенту. Зберігає
+ * backward-compatible контракт для споживачів, яким reasoning не потрібен.
+ * @param {Array<{role:string, content:string}>} messages OpenAI-style messages
+ * @param {string} model model-id
+ * @param {{ timeoutMs?: number, temperature?: number, maxTokens?: number, url?: string, caller?: string }} [opts]
+ * @returns {string} текст відповіді
+ */
+export function callLlm(messages, model, opts = {}) {
+  return callLlmRich(messages, model, opts).content
+}
+
 /** Фрагмент повідомлення omlx про memory-guard (динамічна стеля пам'яті). */
 const MEMORY_GUARD_MARKER = 'memory ceiling'
 /** Тип помилки omlx про відсутній/хибний API-ключ. */

package/lib/omlx.mjs

@@ -130,7 +130,7 @@ function parseOmlxResponse(stdout, attempt) {
  * transient-помилки (curl 18/28/52/56 + spawnSync ETIMEDOUT) із backoff 2s→8s.
  * @param {Array<{role:string, content:string}>} messages OpenAI-messages (system+user збережено)
  * @param {string} model model-id (з/без `omlx/`-префікса); порожній і без `fallbackModel` → throw
- * @param {{ url?: string, timeoutMs?: number, temperature?: number, maxTokens?: number, fallbackModel?: string, apiKey?: string, backoffMs?: number[] }} [opts] URL, timeout, температура, ліміт виходу, fallback-модель, API-ключ, backoff між ретраями (мс)
+ * @param {{ url?: string, timeoutMs?: number, temperature?: number, maxTokens?: number, fallbackModel?: string, apiKey?: string, backoffMs?: number[], thinkingBudget?: number }} [opts] URL, timeout, температура, ліміт виходу, fallback-модель, API-ключ, backoff між ретраями (мс), бюджет thinking-токенів (0 = вимкнено)
  * @returns {{ content:string, reasoning:string|null, reasoningSource:string|null, finishReason:string|null, usage:object|null, attempts:number }} багатий результат виклику
  * @throws {Error} на curl-помилці, не-200 exit, поганому JSON чи порожньому контенті
  */
@@ -142,14 +142,21 @@ export function callOmlxRaw(messages, model, opts = {}) {
     maxTokens = 4096,
     fallbackModel = env.N_CURSOR_OMLX_MODEL ?? '',
     apiKey,
-    backoffMs = BACKOFF_MS
+    backoffMs = BACKOFF_MS,
+    thinkingBudget = 0
   } = opts
 
   const m = omlxModelId(model) || fallbackModel
   if (!m) {
     throw new Error('omlx: модель не задано — постав N_LOCAL_MIN_MODEL (або N_CURSOR_OMLX_MODEL)')
   }
-  const body = JSON.stringify({ model: m, messages, max_tokens: maxTokens, temperature })
+  const body = JSON.stringify({
+    model: m,
+    messages,
+    max_tokens: maxTokens,
+    temperature,
+    ...(thinkingBudget > 0 ? { thinking_budget: thinkingBudget } : {})
+  })
   // Ключ локального сервера в argv допустимий: localhost-секрет власної машини,
   // короткоживучий процес; stdin уже зайнятий body (`--data-binary @-`).
   const key = resolveOmlxApiKey(apiKey)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "12.9.0",
+  "version": "12.11.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/abie/docs/main.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Модуль застосовує політику до JS-запитів, посилаючись на MDC-ресурси відповідно до конфігурації `meta.json`. При запуску як окремий інструмент (CLI) він виконує повний цикл обробки, завантажує конфігурації та формує підсумковий звіт. Модуль є Read-only, тобто не здійснює записів у файлову систему чи бази даних. Кешування даних відбувається у межах одного прогону.
 
 ## Поведінка

package/rules/abie/lib/docs/http-route.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Виконує крос-документну аналітику для підрахунку `backendRefs` до спільних сервісів (`auth-run-hl`, `file-link-hl`) у base-маніфестах пакета, що знаходяться поза overlay `ua`. Використовується фіксований список спільних сервісів, визначений через `ABIE_SHARED_CROSS_NS_BACKEND_NAMES`. Функція `analyzeAbieSharedBackendRefsInPackageK8s` підраховує ці посилання. Це забезпечує синхронізацію числа патчів namespace в overlay із кількістю base-reference, використовуючи `ua_http_route-концерном` для забезпечення узгодженості (abie.mdc).
 
 ## Поведінка

package/rules/abie/main.mdc

@@ -16,16 +16,6 @@ version: '1.22'
 
 Без цього запису `@nitra/cursor` пропускає всі abie-перевірки (JS-концерни та rego-полісі).
 
-[k8s-hc-yaml](./js/hc_pairing.mdc)
-
-[k8s-http-route-base](./js/http_route_base.mdc)
-
-[k8s-http-route-ua](./js/ua_http_route.mdc)
-
-[k8s-nodeselector](./js/ua_node_selector.mdc)
-
-[env-dns](./js/env_dns.mdc)
-
 ## `@nitra/abie-shared` у `devDependencies`
 
 У кореневому **`package.json`** abie-проєкту в **`devDependencies`** має бути **`@nitra/abie-shared`** — пакет зі спільними abie-ресурсами: канонічні GraphQL-схеми, скіли, типи (наприклад, шляхи `node_modules/@nitra/abie-shared/schema/...` для імпорту схем). Версію правило не фіксує — лише presence. Додати:
@@ -34,8 +24,6 @@ version: '1.22'
 bun add -d @nitra/abie-shared
 ```
 
-[firebase](./js/firebase_hosting.mdc)
-
 ## Git branches
 
 У **`.github/workflows/clean-merged-branch.yml`** у кроці **`phpdocker-io/github-actions-delete-abandoned-branches`** значення **`with.ignore_branches`** має містити **dev** та **ua** (разом з іншими гілками, якщо потрібно):
@@ -48,16 +36,6 @@ bun add -d @nitra/abie-shared
 
 Пакети (директорія в **`npm/policy/abie/`** → namespace → що перевіряє):
 
-[abie-http-route-base](./policy/http_route_base/http_route_base.mdc)
-
-[abie-health-check-policy](./policy/health_check_policy/health_check_policy.mdc)
-
-[abie-base-deployment-preem](./policy/base_deployment_preem/base_deployment_preem.mdc)
-
-[abie-clean-merged-ignore-branches](./policy/clean_merged_ignore_branches/clean_merged_ignore_branches.mdc)
-
-[abie-package-json-shared](./policy/package_json_shared/package_json_shared.mdc)
-
 Cross-file / FS-логіка лишається у JS-частинах (`js/<concern>.mjs`) — Rego не читає файлову систему й не робить cross-document резолюцію:
 
 - парність HCP↔Deployment у каталозі та modeline `hc.yaml` — `js/hc_pairing.mjs`;

package/rules/adr/docs/main.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Модуль виконує логіку перевірок, обробляючи JS-запити та звертаючись до MDC. При запуску як окремий інструмент, він ініціює повний цикл правил, включаючи завантаження конфігурацій з meta.json. Модуль має лише читачний доступ до файлової системи та баз даних. Під час виконання він використовує кешування у межах прогону для оптимізації.
 
 ## Поведінка

package/rules/adr/js/docs/hooks.md

@@ -3,40 +3,30 @@ type: JS Module
 title: hooks.mjs
 resource: npm/rules/adr/js/hooks.mjs
 docgen:
-  crc: 3f239faf
+  crc: 7195231e
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Файл надає публічну функцію `check` для валідації даних. Код використовує конфігурацію з файлу `.local.json` для визначення логіки. Функція працює у режимі, де невдачі повертають `false` або `null` замість генерації винятків. Повідомлення про події передаються за допомогою маркера (adr.mdc).
+## Огляд
 
-## Поведінка
-
-1. Перевірка канонічності скриптів
-   Проводиться перевірка наявності та відповідності логіки між скриптами, визначеними в артефактах, і їхніми канонічними версіями. У разі невідповідності повертається сигнал про необхідність повторного синхронізації.
-
-2. Валідація налаштувань проєкту
-   Перевіряється наявність файлу `.claude/settings.json` для підтвердження коректності конфігурації відповідно до вимог (adr.mdc).
-
-3. Перевірка конфігурації хуків Cursor
-   Перевіряється, чи містить конфігурацію Cursor необхідні стоп-хуки для кожного визначеного скрипта.
+Модуль перевіряє стан проєкту, валідуючи конфігураційні файли (`settings.json`, `hooks.json`, `settings.local.json`) та перевіряючи наявність структур для документації (adr.mdc). Перевірка включає перевірку наявності необхідних елементів, при цьому шляхи `.git` свідомо ігноруються.
 
-4. Перевірка ігнорування логів
-   Перевіряється вміст файлу `.gitignore` на відповідність ігнорування кожного лог-файлу хука.
-
-5. Перевірка покриття логів
-   Перевіряється, чи покриває конфігурація `.gitignore` всі необхідні лог-файли.
-
-6. Перевірка доступності CLI
-   Перевіряється наявність бінарних файлів `claude` або `cursor-agent` у системному PATH. Якщо жодного не знайдено, це інформується як попередження, оскільки хук працюватиме у режимі мовчки.
-
-## Публічний API
+## Поведінка
 
-check — перевіряє, чи відповідає проєкт вимогам adr.mdc (adr.mdc).
+1. Викликається `check` для запуску повного набору перевірок проєкту.
+2. Перевіряється наявність та збіг конфігураційних скриптів хуків у проєкті з канонічними версіями.
+3. Перевіряється наявність конфігурацій проєкту, зокрема `settings.json`.
+4. Перевіряється, чи містить конфігурація хуків проєкту (`hooks.json`) необхідні маркери для зупинення (stop-hook) кожного артефакту хука.
+5. Перевіряється, чи ігнорує файл `.gitignore` лог-файли кожного хука.
+6. Перевіряється, чи ігнорує файл `.gitignore` файли стану та блокування, пов'язані з нормалізацією хуків.
+7. Перевіряється наявність каталогу `docs/adr/` для зберігання ADR-ів.
+8. Перевіряється доступність LLM CLI (`claude` або `cursor-agent`) у системному шляху.
+9. Повертається код виходу, що відображає результати всіх перевірок.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдалої перевірки повертає `false`/`null` замість винятку.
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
 - Свідомо пропускає шляхи: `.git`.
-- Не звертається до мережі.