@nitra/cursor 5.3.4 → 5.4.0

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

@@ -26,7 +26,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "npx --no @nitra/cursor doc-files check --hook",
+            "command": "npx --no @nitra/cursor lint-doc-files --hook",
             "timeout": 120
           }
         ]
@@ -38,7 +38,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "npx --no @nitra/cursor doc-files check --git",
+            "command": "npx --no @nitra/cursor lint-doc-files --git",
             "timeout": 120
           }
         ]

package/.pi-template/extensions/n-cursor-adr/docs/index.md

@@ -2,39 +2,28 @@
 docgen:
   source: npm/.pi-template/extensions/n-cursor-adr/index.ts
   crc: 3233716f
+  score: 100
 ---
 
 # index.ts
 
 ## Огляд
 
-Огляд
-
-Файл слугує механізмом для підготовки даних сесії та ініціації виконання зовнішніх рішень. Він серіалізує поточний стан сесії для формування вхідного JSON і запускає відповідні скрипти для прийняття рішень.
+Файл збирає записи сесії, серіалізує їх у формат JSONL, записує у тимчасову директорію, а потім ініціює виконання скриптів хуків capture та normalize.
 
 ## Поведінка
 
-1. Запуск відбувається при події agent_end.
-2. Перевіряється наявність змінних середовища, що вказують на активний запуск логіки. Якщо перевірка позитивна, виконання зупиняється.
-3. Зчитуються записи сесії з `sessionManager`.
-4. Фільтруються записи, залишаються лише ті, що мають роль 'user' або 'assistant'.
-5. Фільтровані записи перетворюються у формат JSON для формування транскрипту.
-6. Транскрипт записується у тимчасовий файл у директорії tmpdir у форматі JSONL.
-7. Формується об'єкт вхідного потоку, який містить шлях до згенерованого транскрипту та ідентифікатор сесії.
-8. Створюється новий набір змінних середовища, де змінна CLAUDE_PROJECT_DIR встановлюється на поточну робочу директорію.
-9. Паралельно виконуються два окремі скрипти bash: capture-decisions.sh та normalize-decisions.sh.
-10. Обидва скрипти отримують вхідний JSON-пакет і виконуються через адаптер pi.exec.
-11. Виконування здійснюється асинхронно. Якщо скрипти відсутні, це може призвести до помилки, яка буде зареєстрована у результаті виконання.
-12. Помилки виконання ловляться, щоб забезпечити стабільність системи.
+1. Виклик події agent_end.
+2. Перевірка захисту від рекурсії через змінні середовища. Якщо встановлено змінні, виконання зупиняється.
+3. Серіалізація записів сесії. Зчитування записів з sessionManager та формування рядка JSONL.
+4. Запис JSONL файлу. Запис серіалізованого тексту у тимчасову директорію.
+5. Формування вхідного навантаження. Створення JSON об'єкта для передачі у башку.
+6. Передача виконання скриптів. Паралельний запуск двох окремих скриптів.
+    а. Виконання хука capture.
+    б. Виконання хука normalize.
+7. Обробка результатів. Очікування завершення обох виконання. Помилки обробляються у загальному режимі.
 
 ## Гарантії поведінки
 
-- Доступ до файлу дозволений
-- Операція запису та модифікації даних дозволена
-- При виникненні помилок система перехоплює їх
-- Система не генерує винятків назовні
-- Система не використовує кешування
-- Система не виконує операцій з мережею
-- Логіка пропуску та обмеження швидкості залишається у бах (bash)
-- Логіка вибору LLM-CLI залишається у бах (bash)
-- Перевірка рекурсії здійснюється через змінні середовища встановлені бах перед запуском LLM CLI
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Не звертається до мережі.

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [5.4.0] - 2026-06-14
+
+### Added
+
+- doc-files: міграція скіл→правило `npm/rules/doc-files/` (git mv `js/`); нові команди `lint-doc-files` (детермінований детектор stale `missing`∪`crc-mismatch`, exit 1; режими `--json`/`--missing-only`/`--hook`/`--git`/`--degraded`) і `fix-doc-files` (local-only генерація + `--stamp`); `lint`-адаптер агрегатора (`lint:"quick"`); `doc-files <sub>` стає делегувальним deprecated-аліасом (plain `check` exit 2→1; `--hook`/`--git` лишають exit 2); hook-маркер `@nitra/cursor lint-doc-files` із cleanup legacy `doc-files check`; тонкий скіл doc-files.
+
+### Fixed
+
+- lint-js: 12 oxlint-помилок — RS\_\*-регекспи догори module scope і прибрані невикористані (docgen-extract, docgen-protected.test), повернуто JSDoc extractReasoning на місце (omlx), async без await (rule-predicates), сигнальний re-raise замість process.exit у with-lock (коректні коди 130/143), опис @returns (units-rs)
+- doc-files check <paths>: перший позиційний шлях мовчки губився без --max (порівняння зі значенням argv[maxIdx+1] при maxIdx=-1); значення прапорців тепер виключаються за індексом (--max, --root) + регресійні тести
+
 ## [5.3.4] - 2026-06-11
 
 ### Changed

package/bin/n-cursor.js

@@ -25,10 +25,9 @@
  *   `npx \@nitra/cursor lint-docker` — канонічний lint-docker (docker.mdc): `hadolint` по `Dockerfile`/`*.Dockerfile`
  *   `npx \@nitra/cursor lint-text`   — канонічний lint-text (text.mdc): `cspell` → `shellcheck` (з auto-fix) →
  *                                     `markdownlint-cli2 --fix` → `v8r` (json/json5/yaml/yml/toml)
- *   `npx \@nitra/cursor doc-files scan`  — JSON-лістинг кодових файлів зі станом застарілості (`stale`: `missing`|`crc-mismatch`) для обовʼязкового скілу doc-files (ignore-glob у `npm/skills/doc-files/js/docgen-ignore.mjs`; тека `docs/` поряд із джерелом)
- *   `npx \@nitra/cursor doc-files check` — детектор застарілості для hook'ів (`--hook` PostToolUse, `--git` Stop-гейт із порогом `--max`); exit 2 — стале знайдено
- *   `npx \@nitra/cursor doc-files gen`   — JS-оркестрована генерація файлових док (роутинг local/cloud) зі штампом CRC у frontmatter (`--limit`/`--from`/`--overwrite`)
- *   `npx \@nitra/cursor doc-files stamp` — детерміновано (пере)штампувати CRC у наявних доках без 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`/`--retry-degraded`); `--stamp` — детерміноване перештампування CRC без LLM
+ *   `npx \@nitra/cursor doc-files <sub>` — DEPRECATED-аліас (scan|check|gen|stamp) → `lint-doc-files`/`fix-doc-files`
  *   `npx \@nitra/cursor doc-aggregate modules` — JSON-лістинг логічних модулів (межі за `package.json`) для Tier 2 скілу doc-aggregate
  *   `npx \@nitra/cursor skill list`     — скіли пакета без синку в проєкт
  *   `npx \@nitra/cursor skill taze`     — промпт на stdout
@@ -1595,7 +1594,7 @@ async function runSync() {
 /**
  * Команди, що мутують проєкт у CWD і вимагають кореня репо. `undefined`/`''` —
  * дефолтний sync; `check` — deprecated-alias `fix`. Решта (read-only `trace`,
- * `--root`-команди `doc-files`/`doc-aggregate`/`rename-yaml-extensions`, `worktree`,
+ * `--root`-команди `lint-doc-files`/`fix-doc-files`/`doc-files`/`doc-aggregate`/`rename-yaml-extensions`, `worktree`,
  * sub-лінтери) гард не зачіпає.
  */
 const ROOT_GUARDED_COMMANDS = new Set([undefined, '', 'fix', 'check', 'lint', 'coverage', 'change', 'release'])
@@ -1641,7 +1640,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, doc-files, doc-aggregate, rename-yaml-extensions) не зачіпаємо.
+  // `--root`-команди (trace, graph, lint-doc-files, fix-doc-files, doc-files, doc-aggregate, rename-yaml-extensions) не зачіпаємо.
   if (ROOT_GUARDED_COMMANDS.has(command)) {
     assertCwdIsProjectRoot(cwd(), describeRootGuardedAction(command))
   }
@@ -1810,36 +1809,58 @@ 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/lint/lint.mjs')
+      process.exitCode = await runLintDocFilesCli(args)
+
+      break
+    }
+    case 'fix-doc-files': {
+      // n-cursor fix-doc-files — local-only генерація файлових док (omlx) + CRC-штамп
+      // (--limit/--from/--overwrite/--retry-degraded); --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 'doc-files': {
-      // n-cursor doc-files scan|check|gen|stamp — обовʼязковий крок задачі (як lint):
-      // файлова дока поряд із джерелом, застарілість за CRC у frontmatter.
-      //   scan  — JSON-лістинг кодових файлів зі станом stale (missing|crc-mismatch);
-      //   check — детектор застарілості для hook'ів (--hook PostToolUse, --git Stop-гейт);
-      //   gen   — JS-оркестрована генерація доки (роутинг local/cloud) + CRC-штамп;
-      //   stamp — детерміновано (пере)штампувати CRC у наявних доках без LLM.
+      // Делегувальний аліас (deprecated): doc-files scan|check|gen|stamp →
+      // lint-doc-files / fix-doc-files. Зняття — наступний major (спека 2026-06-12).
+      // Зміна exit: plain `check` 2→1 (через lint-doc-files); --hook/--git зберігають 2.
+      console.error('⚠ `doc-files <sub>` застаріло — використовуй `lint-doc-files` / `fix-doc-files`.')
+      const rest = args.slice(1)
       switch (args[0]) {
         case 'scan': {
-          const { runDocFilesScanCli } = await import('../skills/doc-files/js/docgen-scan.mjs')
-          process.exitCode = runDocFilesScanCli(args.slice(1))
+          const { runLintDocFilesCli } = await import('../rules/doc-files/lint/lint.mjs')
+          process.exitCode = await runLintDocFilesCli(['--json', ...rest])
           break
         }
         case 'check': {
-          const { runDocFilesCheckCli } = await import('../skills/doc-files/js/docgen-scan.mjs')
-          process.exitCode = await runDocFilesCheckCli(args.slice(1))
+          const { runLintDocFilesCli } = await import('../rules/doc-files/lint/lint.mjs')
+          process.exitCode = await runLintDocFilesCli(rest)
           break
         }
         case 'gen': {
-          const { runDocFilesGenCli } = await import('../skills/doc-files/js/docgen-files-batch.mjs')
-          process.exitCode = await runDocFilesGenCli(args.slice(1))
+          const { runDocFilesGenCli } = await import('../rules/doc-files/js/docgen-files-batch.mjs')
+          process.exitCode = await runDocFilesGenCli(rest)
           break
         }
         case 'stamp': {
-          const { runDocFilesStampCli } = await import('../skills/doc-files/js/docgen-files-batch.mjs')
-          process.exitCode = runDocFilesStampCli(args.slice(1))
+          const { runDocFilesStampCli } = await import('../rules/doc-files/js/docgen-files-batch.mjs')
+          process.exitCode = runDocFilesStampCli(rest)
           break
         }
         default: {
-          console.error('Usage: npx @nitra/cursor doc-files <scan|check|gen|stamp> [--root <dir>]')
+          console.error('Usage: npx @nitra/cursor lint-doc-files | fix-doc-files [--root <dir>]')
           process.exitCode = 1
         }
       }
@@ -1869,7 +1890,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, fix, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, coverage-fix, taze, start-check, fix-t0, change, release, skill, worktree, lint-ci, trace, doc-files, doc-aggregate`
+        `   Очікується: (без аргументів) синхронізація правил, fix, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, lint-doc-files, fix-doc-files, coverage, coverage-fix, taze, start-check, fix-t0, change, release, skill, worktree, lint-ci, trace, doc-files, doc-aggregate`
       )
       process.exitCode = 1
     }

package/lib/docs/models.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/lib/models.mjs
-  crc: feb82992
+  crc: 181e2bf9
   score: 100
 ---
 
@@ -9,29 +9,40 @@ docgen:
 
 ## Огляд
 
-Файл визначає глобальну класифікацію моделей для системи pi, встановлюючи конфігураційні моделі для локального та хмарного інференсу через змінні середовища (наприклад, `N_LOCAL_MIN_MODEL`). Значення моделі мають формат "provider/model-id".
-
-Система надає механізм каскадного вибору моделі через функцію `resolveModel`. Цей механізм послідовно перевіряє локальні тири (`LOCAL_MIN` $\rightarrow$ `LOCAL_AVG` $\rightarrow$ `LOCAL_MAX`), а потім хмарні тири, якщо попередні не визначені. Це забезпечує прозору роботу, навіть якщо локальні моделі відсутні. Прямі константи (наприклад, `LOCAL_MIN`) залишені для випадків, що вимагають явного контролю над вибором моделі.
+Файл визначає глобальну класифікацію моделей для pi. Конфігурація встановлюється через змінні середовища (наприклад, `N_LOCAL_MIN_MODEL`) та використовується для визначення, який провайдер буде викликаний. Кожен скіл посилається на потрібний тир, який використовується для вибору моделі.
 
 ## Поведінка
 
-LOCAL_MIN повертає модель для швидкого локального інференсу, або порожній рядок, якщо змінна середовища не встановлена.
-LOCAL_AVG повертає модель для середнього локального інференсу, або порожній рядок, якщо змінна середовища не встановлена.
-LOCAL_MAX повертає модель для максимального локального інференсу, або порожній рядок, якщо змінна середовища не встановлена.
-CLOUD_MIN повертає модель для мінімального хмарного інференсу, або порожній рядок, якщо змінна середовища не встановлена.
-CLOUD_AVG повертає модель для середнього хмарного інференсу, або порожній рядок, якщо змінна середовища не встановлена.
-CLOUD_MAX повертає модель для максимального хмарного інференсу, або порожній рядок, якщо змінна середовища не встановлена.
-resolveModel повертає перший непорожній model-id для запитаного тиру, каскадно перевіряючи локальні тири, а потім хмарний еквівалент, або порожній рядок, якщо жоден тир не задано.
+LOCAL_MIN
+Завантажує модель для мінімального локального виведення
+
+LOCAL_AVG
+Завантажує модель для середнього локального виведення
+
+LOCAL_MAX
+Завантажує модель для максимального локального виведення
+
+CLOUD_MIN
+Завантажує модель для мінімального хмарного виведення
+
+CLOUD_AVG
+Завантажує модель для середнього хмарного виведення
+
+CLOUD_MAX
+Завантажує модель для максимального хмарного виведення
+
+resolveModel
+Повертає перший непорожній model-id для запитаного тиру, каскадно перевіряючи локальні тири, а тоді хмарний еквівалент
 
 ## Публічний API
 
-LOCAL_MIN — Швидке виконання моделі на локальному пристрої.
-LOCAL_AVG — Середнє за продуктивністю виконання моделі на локальному пристрої.
-LOCAL_MAX — Найпотужніше виконання моделі на локальному пристрої.
-CLOUD_MIN — Найменш ресурсомістке виконання моделі в хмарі.
-CLOUD_AVG — Середній рівень продуктивності виконання моделі в хмарі.
-CLOUD_MAX — Найпотужніше виконання моделі в хмарі.
-resolveModel — Знаходить і повертає ідентифікатор моделі, починаючи з локальних варіантів, а потім переходячи до хмарних відповідників.
+LOCAL_MIN — Швидкий локальний inference. Напр.: ollama/gemma3:4b
+LOCAL_AVG — Середній локальний. Напр.: ollama/gemma4:26b-moe
+LOCAL_MAX — Максимальний локальний. Напр.: ollama/llama4-maverick
+CLOUD_MIN — Мінімальний хмарний. Напр.: openai/gpt-5.4-mini, google/gemini-2.5-flash, anthropic/claude-haiku-4-5
+CLOUD_AVG — Середній хмарний. Напр.: openai/gpt-5.4, google/gemini-2.5-pro, anthropic/claude-sonnet-4-6
+CLOUD_MAX — Максимальний хмарний. Напр.: openai/gpt-5.5, anthropic/claude-opus-4-8
+resolveModel — Знаходить перший непорожній model-id для запиту, починаючи з локальних, а потім переходить до хмарних варіантів.
 
 ## Гарантії поведінки
 

package/lib/docs/omlx-trace.md

@@ -0,0 +1,51 @@
+---
+docgen:
+  source: npm/lib/omlx-trace.mjs
+  crc: 3ff568d5
+  score: 100
+---
+
+# omlx-trace.mjs
+
+## Огляд
+
+Модуль збирає трасу викликів LLM, фіксуючи думки моделі та спостережуваний слід. Траса записується у локальний файл для ротації та готується для подальшої батч-агрегації. Дизайн-специфікація: docs/specs/2026-06-10-omlx-wire-trace-capture-design.md.
+
+## Поведінка
+
+MAX_MSG_CHARS
+Ліміт символів на одне message.content у записі
+
+ROTATE_BYTES
+Поріг недеструктивної ротації активного файлу в байтах
+
+tracePath
+Повертає шлях до trace-файлу або null
+
+capMessages
+Обрізає message.content та рахує sha256 повного масиву
+
+buildTraceRecord
+Будує нормалізований trace-запис
+
+rotateIfNeeded
+Недеструктивно ротує файл при перевищенні ROTATE_BYTES
+
+writeTrace
+Записує trace-запис у файл з ротацією та fail-safe
+
+## Публічний API
+
+MAX_MSG_CHARS — встановлює максимальну кількість символів для вмісту повідомлення.
+ROTATE_BYTES — визначає поріг для ініціювання ротації файлу.
+tracePath — зберігає шлях до файлу трасування або порожній рядок, якщо трасування вимкнено.
+N_CURSOR_LLM_TRACE — визначає пріоритет для вибору шляху трасування: спочатку перевіряється вимкнений перемикач, потім використовується явний шлях.
+buildTraceRecord — створює запис трасування, залишаючи порожні значення для полів, які недоступні.
+rotateIfNeeded — перейменовує файл при перевищенні ліміту, створюючи новий файл з послідовним індексом.
+writeTrace — записує один запис трасування, обробляючи шляхи, ротуючи дані за необхідності та обробляючи помилки вводу/виводу.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/lib/docs/omlx.md

@@ -1,32 +1,48 @@
 ---
 docgen:
   source: npm/lib/omlx.mjs
-  crc: e29efc97
+  crc: 0073bdfd
+  score: 90
 ---
 
-# omlx
+# omlx.mjs
 
 ## Огляд
 
-Спільний транспорт до локального omlx-сервера (OpenAI-сумісний MLX-inference на `http://127.0.0.1:8000/v1/chat/completions`). Text-only: сервер не підтримує інструменти, тож модуль шле лише повідомлення й читає текст відповіді.
+Файл забезпечує комунікацію з локальним omlx-сервером для отримання відповідей. Він маршрутизує запити, використовуючи конвенцію префікса для визначення, чи слід використовувати прямий HTTP виклик до omlx, чи CLI. Функції надають інструменти для роботи з API ключами та викликів до inference-сервера.
 
 ## Поведінка
 
-1. Виклик будує запит з повідомленнями, моделлю, температурою і лімітом виходу; model-id з префіксом `omlx/` нормалізується до чистого імені, порожній — замінюється дефолтною моделлю (`mlx-community--gemma-4-e2b-it-4bit`, override через `N_CURSOR_OMLX_MODEL`).
-2. Endpoint береться з `N_CURSOR_OMLX_URL` або дефолтний.
-3. Якщо на сервері ввімкнено API-ключ, він резолвиться в порядку: явний параметр виклику → `N_CURSOR_OMLX_KEY` → поле `auth.api_key` з локального `~/.omlx/settings.json` (читання fail-safe) — і шлеться як `Authorization: Bearer`. Без знайденого ключа заголовок не додається.
-4. Тимчасові обриви з'єднання (передача перервана, порожня відповідь, збій прийому) ретраяться до трьох спроб; решта помилок — виняток одразу.
-5. Помилка API у тілі відповіді, невалідний JSON чи порожній контент — виняток із діагностичним префіксом `omlx …`.
+DEFAULT_OMLX_URL: Дефолтний endpoint omlx
+
+resolveOmlxApiKey: Резолвить API ключ для omlx-сервера
+
+DEFAULT_OMLX_MODEL: Дефолтна модель для omlx
+
+isOmlxModel: Перевіряє, чи model-id адресує локальний omlx-бекенд
+
+omlxModelId: Прибирає префікс omlx/ з model-id
+
+extractReasoning: Витягує reasoning з message
+
+callOmlxRaw: Ядро прямого HTTP-виклику до omlx через curl
+
+callOmlx: Тонка обгортка для отримання тексту відповіді
 
 ## Публічний API
 
-- `callOmlx` — синхронний chat-виклик, повертає непорожній текст відповіді.
-- `isOmlxModel` / `omlxModelId` — перевірка і зняття префікса `omlx/`.
-- `resolveOmlxApiKey` — резолвінг API-ключа за описаним порядком джерел.
-- `DEFAULT_OMLX_URL` / `DEFAULT_OMLX_MODEL` — дефолти endpoint і моделі.
+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`. Без використання заголовків чи загальних фраз.
 
 ## Гарантії поведінки
 
-- Жодних `tools`/`tool_calls` у запиті — сумісність із text-only сервером.
-- Ролі повідомлень (`system`/`user`) передаються без злиття.
-- Виняток ніколи не ковтається: викликач завжди дізнається про збій.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/lib/omlx.mjs

@@ -69,6 +69,8 @@ export function omlxModelId(model) {
   return isOmlxModel(model) ? model.slice(OMLX_PREFIX.length) : model
 }
 
+const THINK_TAG_RE = /<think>([\s\S]*?)<\/think>/
+
 /**
  * Витягує reasoning (думки моделі) з omlx-`message`. Джерела за пріоритетом:
  *   - `field`     — окреме поле `message.reasoning_content` (Qwen3-Thinking тощо);
@@ -80,11 +82,6 @@ export function omlxModelId(model) {
  * @param {string|null} finishReason `choices[0].finish_reason`
  * @returns {{ reasoning: string|null, reasoningSource: 'field'|'think_tag'|'truncated'|null }} текст думок і його джерело
  */
-const THINK_TAG_RE = /<think>([\s\S]*?)<\/think>/
-
-/**
- *
- */
 export function extractReasoning(message, finishReason) {
   const field = message?.reasoning_content
   if (field && field.trim()) return { reasoning: field, reasoningSource: 'field' }

package/package.json

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

package/rules/abie/docs/fix.md

@@ -1,30 +1,36 @@
 ---
 docgen:
   source: npm/rules/abie/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
 # fix.mjs
 
 ## Огляд
 
-Файл виконує трансформацію вхідного запиту у структурований вивід формату Х. Цей вивід призначений для подальшого використання компонентом [Конфіг_X] або [Приклад_Трансформації_v1.2].
+Запуск правила приймає контекст прогону, застосовує JS-занепокоєні та політику, генерує посилання MDC та повертає результат прогону.
 
-## Поведінка
+Виконання у режимі CLI виконує повний еквівалент команди `npx @nitra/cursor fix <id>` та повертає код виходу.
 
-1. Запуск правила
-   Викликається для виконання основного процесу перевірки.
+## Поведінка
 
-2. Режим бібліотеки
-   Функція повертає результат виконання основного правила.
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних.
+    *   Застосовує політику.
+    *   Генерує посилання MDC.
+    *   Повертає результат прогону.
 
-3. Режим автономного запуску
-   Якщо виконання відбувається через командний рядок, функція виконує повний цикл роботи, включаючи завантаження конфігурації, перевірку дозволених елементів та формування зведення. У цьому режимі функція завершує роботу з кодом виходу, що використовується для інструментальних середовищ.
+2. Виконання у режимі CLI.
+    *   Виконується при запуску через CLI.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Повертає код виходу.
 
 ## Публічний API
 
-- run: Запускає правило, що переходить від applies до JS-concerns, policy та mdc-refs за допомогою runStandardRule.
-- Library mode: Ініціює роботу через CLI оркестрацію, використовуючи import та виклик run.
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
 ## Гарантії поведінки