@nitra/cursor 12.6.1 → 12.8.0

package/rules/tauri/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/tauri/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль обробляє JS-запити та взаємодіє з MDC для отримання даних. При запуску через публічну функцію `run` він оркеструє застосування правил, завантажуючи конфігурації з meta.json, застосовуючи білий список та надаючи підсумок. Модуль є read-only і не здійснює записів у ФС/БД.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання перевірки включає застосування політики, обробку JS-запитань та посилання на MDC.
+3. Якщо код виконується як окрема утиліта (CLI), запускається оркестрація правила.
+4. Оркестрація правила виконує завантаження конфігурацій (наприклад, `meta.json`), застосовує білий список та надає підсумок.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує вимоги до JavaScript, перевіряє політику та посилання на MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/tauri/js/docs/index.md

@@ -6,7 +6,7 @@ resource: npm/rules/tauri/js/
 
 # npm/rules/tauri/js
 
-| Файл | Тип |
-|---|---|
+| Файл                                                | Тип       |
+| --------------------------------------------------- | --------- |
 | [cargo_mutants_config.mjs](cargo_mutants_config.md) | JS Module |
-| [tooling.mjs](tooling.md) | JS Module |
+| [tooling.mjs](tooling.md)                           | JS Module |

package/rules/tauri/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/test/docs/fix.md

@@ -12,12 +12,12 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Передача контексту прогону.
-    *   Виклик `runStandardRule` з використанням шляху до модуля.
-    *   Повернення результату.
+   - Передача контексту прогону.
+   - Виклик `runStandardRule` з використанням шляху до модуля.
+   - Повернення результату.
 2. Запуск у режимі CLI.
-    *   Виклик `runRuleCli` з використанням шляху до модуля.
-    *   Встановлення коду виходу процесу на результат.
+   - Виклик `runRuleCli` з використанням шляху до модуля.
+   - Встановлення коду виходу процесу на результат.
 
 ## Публічний API
 

package/rules/test/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/rules/test/
 
 # npm/rules/test
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/test/docs/main.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/test/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль виконує перевірку, обробляючи JS-запитання, політику та посилання на mdc. При запуску як окрема програма, він зчитує конфігурації з meta.json, застосовує білий список та підсумовує результати після застосування білого списку, визначаючи код виходу процесу. Функція run ініціює цей процес. Модуль є read-only і не пише у ФС/БД. Кешування відбувається у межах прогону.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання `run` застосовує логіку правила, включаючи обробку JS-запитань, політику та посилання на mdc.
+3. Якщо скрипт виконується як окрема програма (CLI), запускається оркестрація правила.
+4. Оркестрація правила зчитує конфігурації, включаючи `meta.json`, застосовує білий список та підсумовує результати.
+5. Результат оркестрації визначає код виходу процесу.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує перевірки, обробляє JS-залежності та політики, а також посилається на метадані.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/test/js/data/stryker_config/docs/index.md

@@ -6,8 +6,8 @@ resource: npm/rules/test/js/data/stryker_config/
 
 # npm/rules/test/js/data/stryker_config
 
-| Файл | Тип |
-|---|---|
-| [stryker-vue-macros-ignorer.mjs](stryker-vue-macros-ignorer.md) | JS Module |
-| [stryker.config.baseline.mjs](stryker.config.baseline.md) | JS Module |
+| Файл                                                              | Тип       |
+| ----------------------------------------------------------------- | --------- |
+| [stryker-vue-macros-ignorer.mjs](stryker-vue-macros-ignorer.md)   | JS Module |
+| [stryker.config.baseline.mjs](stryker.config.baseline.md)         | JS Module |
 | [stryker.config.vue.baseline.mjs](stryker.config.vue.baseline.md) | JS Module |

package/rules/test/js/data/vitest_config/docs/index.md

@@ -6,6 +6,6 @@ resource: npm/rules/test/js/data/vitest_config/
 
 # npm/rules/test/js/data/vitest_config
 
-| Файл | Тип |
-|---|---|
+| Файл                                                   | Тип       |
+| ------------------------------------------------------ | --------- |
 | [vitest.config.baseline.js](vitest.config.baseline.md) | JS Module |

package/rules/test/js/docs/index.md

@@ -6,11 +6,11 @@ resource: npm/rules/test/js/
 
 # npm/rules/test/js
 
-| Файл | Тип |
-|---|---|
-| [cargo_mutants_config.mjs](cargo_mutants_config.md) | JS Module |
-| [location.mjs](location.md) | JS Module |
-| [no-process-chdir.mjs](no-process-chdir.md) | JS Module |
-| [no-relative-fs-path.mjs](no-relative-fs-path.md) | JS Module |
-| [stryker_config.mjs](stryker_config.md) | JS Module |
+| Файл                                                        | Тип       |
+| ----------------------------------------------------------- | --------- |
+| [cargo_mutants_config.mjs](cargo_mutants_config.md)         | JS Module |
+| [location.mjs](location.md)                                 | JS Module |
+| [no-process-chdir.mjs](no-process-chdir.md)                 | JS Module |
+| [no-relative-fs-path.mjs](no-relative-fs-path.md)           | JS Module |
+| [stryker_config.mjs](stryker_config.md)                     | JS Module |
 | [vitest-config-pool-forks.mjs](vitest-config-pool-forks.md) | JS Module |

package/rules/test/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/text/docs/fix.md

@@ -12,18 +12,18 @@ docgen:
 ## Поведінка
 
 1. Запуск правила.
-    *   Приймає контекст прогону.
-    *   Виконує застосування JS-занепокоєних.
-    *   Застосовує політику.
-    *   Генерує посилання MDC.
-    *   Повертає результат прогону.
+   - Приймає контекст прогону.
+   - Виконує застосування JS-занепокоєних.
+   - Застосовує політику.
+   - Генерує посилання MDC.
+   - Повертає результат прогону.
 2. Виконання у режимі CLI.
-    *   Виконується як автономний скрипт.
-    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
-    *   Виконує завантаження конфігурації.
-    *   Виконує перевірку дозволених записів.
-    *   Генерує зведену інформацію.
-    *   Визначає код виходу процесу.
+   - Виконується як автономний скрипт.
+   - Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+   - Виконує завантаження конфігурації.
+   - Виконує перевірку дозволених записів.
+   - Генерує зведену інформацію.
+   - Визначає код виходу процесу.
 
 ## Публічний API
 

package/rules/text/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/rules/text/
 
 # npm/rules/text
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/text/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/text/main.mjs
+docgen:
+  crc: deba6201
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+## Огляд
+
+CLI-обгортка над канонічним `lint-text` (text.mdc) забезпечує послідовний пайплайн перевірок для текстових файлів. Вона автоматично встановлює необхідні інструменти (`shellcheck`, `dotenv-linter`) через `ensureTool` (brew/scoop/GitHub Release per-platform) та перевіряє наявність `patch` для авто-фіксу. Пайплайн послідовно виконує: перевірку правопису (`cspell` з `@nitra/cspell-dict`), синтаксичну перевірку скриптів (`shellcheck` з авто-фіксом), перевірку конфігураційних файлів (`dotenv-linter` з авто-фіксом), форматування Markdown (`markdownlint-cli2` з авто-фіксом) та валідацію схем (`v8r`). Перший ненульовий код, отриманий у ланцюжку, повертається як код виходу, припиняючи подальші кроки. Функціональність експортується як `runLintTextCli` та викликається через `n-cursor lint text` (оркестраторний адаптер `lint`). Конфігурації, на які спирається код: meta.json.
+
+## Поведінка
+
+run: Викликається як check-поверхня, виконуючи стандартне правило.
+runLintTextCli: Виконує повний ланцюжок перевірок для тексту: `cspell`, `shellcheck`, `dotenv-linter`, `markdownlint-cli2` та валідацію схем через `v8r`. Автоматично встановлює `shellcheck` та `dotenv-linter` при першому прогоні. Повертає код першого кроку, що не пройшов.
+lint: Делегує виконання повного ланцюжка перевірок тексту через `runLintTextCli`, дозволяючи вказати режим лише детектування без авто-фіксу.
+
+## Публічний API
+
+run — Точка входу правила, що виконує перевірку логіки (JS-занепокложення → політика → посилання text.mdc).
+runLintTextCli — Публічна команда для CLI, яка серіалізує завдання лінтування з блокуванням та усуває дублікати на основі стану репозиторію.
+lint — Адаптер, що керує запуском лінтування тексту через `n-cursor lint text`, делегуючи роботу `runLintTextCli`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/text/{lint → js}/cspell-fix.mjs

@@ -143,12 +143,17 @@ export function runCspellText(cwd = process.cwd(), readOnly = false, llmFix = fa
   const words = unknownWords(first.out)
   const batch = words.slice(0, MAX_CLASSIFY_WORDS)
   if (words.length > MAX_CLASSIFY_WORDS) {
-    process.stdout.write(`ℹ️  cspell: класифікація перших ${MAX_CLASSIFY_WORDS}/${words.length} слів (решта — наступний прогін)\n`)
+    process.stdout.write(
+      `ℹ️  cspell: класифікація перших ${MAX_CLASSIFY_WORDS}/${words.length} слів (решта — наступний прогін)\n`
+    )
   }
 
   let text
   try {
-    text = callLlm([{ role: 'user', content: classifyPrompt(batch) }], model, { caller: 'cspell-classify', maxTokens: 4000 })
+    text = callLlm([{ role: 'user', content: classifyPrompt(batch) }], model, {
+      caller: 'cspell-classify',
+      maxTokens: 4000
+    })
   } catch (error) {
     process.stdout.write(`⚠️  cspell: omlx-класифікація впала (${error.message}) — без авто-словника\n`)
     process.stdout.write(first.out)

package/rules/text/js/docs/cspell-fix.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: cspell-fix.mjs
+resource: npm/rules/text/js/cspell-fix.mjs
+docgen:
+  crc: 7b40e8f9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Виявляє невідомі слова у тексті у ланцюжку lint-text із omlx-класифікацією (спека docs/specs/2026-06-15-opportunistic-llm-fix-tier.md), використовуючи конфігурації .cspell.json та meta.json. Класифікує знахідки за схемою omlx-класифікація, дописуючи валідні терміни до словника .cspell.json. Ймовірні одруки залишаються списком на рев'ю, оскільки fix-режим не переписує файли. Завершує процес повторною перевіркою, щоб визначити, чи залишилися нерозкласифіковані або ймовірні одруки. Перехоплює помилки (fail-safe), не кидаючи винятків назовні.
+
+## Поведінка
+
+unknownWords витягує унікальні невідомі слова з виводу cspell.
+appendWordsToDict додає класифіковані валідні слова до файлу .cspell.json, оновлюючи його словник.
+runCspellText запускає cspell для виявлення невідомих слів, а при увімкненні omlx-класифікації класифікує їх та дописує валідні слова у словник, після чого повторно перевіряє наявність помилок.
+
+## Публічний API
+
+unknownWords — Збирає унікальні слова, які не були знайдені у словнику cspell.
+appendWordsToDict — Додає зібрані слова до файлу `.cspell.json#words` у відсортованому та унікальному вигляді для перегляду у Git.
+runCspellText — Виконує перевірку тексту за допомогою cspell, класифікуючи слова та оновлюючи словник за новою схемою.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/rules/text/js/docs/formatting.md

@@ -3,61 +3,28 @@ type: JS Module
 title: formatting.mjs
 resource: npm/rules/text/js/formatting.mjs
 docgen:
-  crc: 67b016e2
+  crc: 34048813
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Перевіряє наявність файлів з конфігурацій. Код використовує дані з конфігів з extensions.json, settings.json, target.json, .oxfmtrc.json, .cspell.json та package.json для виконання операцій.
+Модуль перевіряє відповідність конфігураційних файлів та скриптів встановленим вимогам. Він перевіряє наявність конфігураційних файлів, на які спираються `package.json`, `extensions.json`, `target.json`, `.oxfmtrc.json` та `.cspell.json`. Модуль використовує функцію `check` для валідації налаштувань.
 
 ## Поведінка
 
-1. Перевірити наявність файлів з конфігурацій
-2. Перевірити наявність файлів з конфігурацій
-3. Перевірити наявність файлів з конфігурацій
-4. Перевірити наявність файлів з конфігурацій
-5. Перевірити наявність файлів з конфігурацій
-6. Перевірити наявність файлів з конфігурацій
-7. Перевірити наявність файлів з конфігурацій
-8. Перевірити наявність файлів з конфігурацій
-9. Перевірити наявність файлів з конфігурацій
-10. Перевірити наявність файлів з конфігурацій
-11. Перевірити наявність файлів з конфігурацій
-12. Перевірити наявність файлів з конфігурацій
-13. Перевірити наявність файлів з конфігурацій
-14. Перевірити наявність файлів з конфігурацій
-15. Перевірити наявність файлів з конфігурацій
-16. Перевірити наявність файлів з конфігурацій
-17. Перевірити наявність файлів з конфігурацій
-18. Перевірити наявність файлів з конфігурацій
-19. Перевірити наявність файлів з конфігурацій
-20. Перевірити наявність файлів з конфігурації
-21. Перевірити наявність файлів з конфігурації
-22. Перевірити наявність файлів з конфігурації
-23. Перевірити наявність файлів з конфігурації
-24. Перевірити наявність файлів з конфігурації
-25. Перевірити наявність файлів з конфігурації
-26. Перевірити наявність файлів з конфігурації
-27. Перевірити наявність файлів з конфігурації
-28. Перевірити наявність файлів з конфігурації
-29. Перевірити наявність файлів з конфігурації
-30. Перевірити наявність файлів з конфігурації
-31. Перевірити наявність файлів з конфігурації
-32. Перевірити наявність файлів з конфігурації
-33. Перевірити наявність файлів з конфігурації
-34. Перевірити наявність файлів з конфігурації
-35. Перевірити наявність файлів з конфігурації
-36. Перевірити наявність файлів з конфігурації
-37. Перевірити наявність файлів з конфігурації
-38. Перевірити наявність файлів з конфігурації
-39. Перевірити наявність файлів з конфігурації
-40. Перевірити наявність файлів з конфігурації
+1. Викликається функція check.
+2. Ініціалізується механізм збору результатів перевірки.
+3. Виконується перевірка файлу .v8rignore на відповідність вимогам.
+4. Виконується перевірка наявності текстових конфігураційних файлів: .oxfmtrc.json, .cspell.json, .markdownlint-cli2.jsonc, .vscode/extensions.json, .vscode/settings.json.
+5. Перевіряється абзац про український апостроф у файлах n-text.mdc або npm/mdc/text.mdc, якщо вони існують.
+6. Виконується перевірка CI-workflow у файлі .github/workflows/lint-text.yml на наявність кроку `n-cursor lint text --read-only`.
+7. Повертається код виходу, що відображає загальний статус перевірки.
 
 ## Публічний API
 
-check — перевіряє відповідність проєкту правилам text.mdc (text.mdc).
+check — порівнює структуру проєкту з вимогами text.mdc.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Свідомо пропускає шляхи: `.github`, `.git`.
-- Не звертається до мережі.

package/rules/text/js/docs/index.md

@@ -6,8 +6,12 @@ resource: npm/rules/text/js/
 
 # npm/rules/text/js
 
-| Файл | Тип |
-|---|---|
+| Файл                                            | Тип       |
+| ----------------------------------------------- | --------- |
+| [cspell-fix.mjs](cspell-fix.md)                 | JS Module |
 | [forbidden-prettier.mjs](forbidden-prettier.md) | JS Module |
-| [formatting.mjs](formatting.md) | JS Module |
-| [lint.mjs](lint.md) | JS Module |
+| [formatting.mjs](formatting.md)                 | JS Module |
+| [lint.mjs](lint.md)                             | JS Module |
+| [run-dotenv-linter.mjs](run-dotenv-linter.md)   | JS Module |
+| [run-shellcheck.mjs](run-shellcheck.md)         | JS Module |
+| [run-v8r.mjs](run-v8r.md)                       | JS Module |

package/rules/text/js/docs/run-dotenv-linter.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: run-dotenv-linter.mjs
+resource: npm/rules/text/js/run-dotenv-linter.mjs
+docgen:
+  crc: 4719ac66
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль запускає `dotenv-linter` для валідації конфігураційних файлів `.env*` відповідно до стандартів (наприклад, `LowercaseKey`). Процес включає два етапи: спочатку автоматичне виправлення порушень за допомогою `dotenv-linter fix`, а потім фінальну перевірку за допомогою `dotenv-linter check`. Інструмент очікується у системному PATH і не включається у залежності проєкту. Він рекурсивно шукає файли, виключаючи `node_modules` та `.envrc`. Якщо `dotenv-linter` відсутній, виводиться інструкція щодо його встановлення (наприклад, `brew install dotenv-linter`) та повертається код помилки. Усі деталі роботи можна знайти за посиланням https://git.io/JLbXn.
+
+## Поведінка
+
+1. `runDotenvLinter` перевіряє наявність інструменту `dotenv-linter` у системному шляху. Якщо інструмент відсутній, виводиться підказка для його встановлення (наприклад, `brew install dotenv-linter` для macOS або завантаження за адресою https://git.io/JLbXn для Linux) та повертається код виходу 1.
+2. Якщо інструмент знайдено, будується список виключених шляхів для сканування, включаючи `node_modules` та `.envrc`.
+3. Якщо режим роботи не є лише перевіркою (readOnly дорівнює `false`), виконується перший запуск `dotenv-linter` з опцією авто-фіксу. Цей запуск застосовує всі можливі виправлення до `.env*`-файлів, ігноруючи `.bak`-файли.
+4. Після застосування авто-фіксу, виконується фінальний запуск `dotenv-linter` з опцією перевірки.
+5. Якщо фінальна перевірка повертає ненульовий код виходу, це означає, що залишилися порушення, і повертається код виходу 1.
+6. Якщо фінальна перевірка повертає код виходу 0, операція успішна, і повертається код виходу 0.
+
+## Публічний API
+
+runDotenvLinter — запускає dotenv-linter з автоматичним виправленням та фінальною перевіркою конфігураційних файлів.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Свідомо пропускає шляхи: `node_modules`.

package/rules/text/js/docs/run-shellcheck.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: run-shellcheck.mjs
+resource: npm/rules/text/js/run-shellcheck.mjs
+docgen:
+  crc: 6b2daaa8
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Скрипт забезпечує відповідність shell-скриптів стандартам, виконуючи дві послідовні дії: спочатку застосовує автоматичні виправлення для проблем, виявлених `shellcheck` за допомогою формату виводу `diff` та команди `patch -p1` у корені проєкту; потім проводить фінальну перевірку всіх зібраних файлів. Скрипт збирає всі відстежувані shell-скрипти у робочому дереві, ігноруючи директорії `node_modules`. Якщо скриптів не знайдено, процес завершується з кодом 0. Якщо `shellcheck` або `patch` відсутні у PATH, скрипт завершується з кодом 1, надаючи підказки для їх встановлення. Після циклу автовиправлень будь-яке попередження чи помилка від `shellcheck` призводить до ненульового коду виходу.
+
+## Поведінка
+
+listShellScriptPaths повертає відсортований масив відносних шляхів до shell-скриптів у проєкті, виключаючи директорії `node_modules`.
+runShellcheckText запускає shellcheck: спочатку намагається автоматично виправити знайдені проблеми за допомогою `diff` та `patch`, а потім виконує фінальну перевірку всіх зібраних файлів.
+
+## Публічний API
+
+listShellScriptPaths — надає список шляхів до скриптів оболонки для перевірки.
+runShellcheckText — виконує перевірку коду за допомогою shellcheck з автоматичним виправленням.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Свідомо пропускає шляхи: `node_modules`.

package/rules/text/js/docs/run-v8r.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: run-v8r.mjs
+resource: npm/rules/text/js/run-v8r.mjs
+docgen:
+  crc: caf707a8
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Скрипт виконує єдиний виклик `v8r` для перевірки відповідності всіх файлів, які підтримує `v8r` (json, json5, yaml, yml, toml), визначеним контрактам. Це замінює необхідність у кількох окремих викликах `v8r`. Скрипт автоматично використовує каталог схем `@nitra/cursor`, який визначається у `v8r-catalog.json`. Якщо не надано додаткових аргументів, він шукає файли за типовими шаблонами у дереві проєкту. Механізм гарантує, що перевірка всіх розширень відбувається, навіть якщо один із глобів не знаходить файлів, оскільки він обходить проблему падіння `v8r` з кодом 98.
+
+## Поведінка
+
+DEFAULT_V8R_GLOBS — надає стандартний список патернів для пошуку файлів JSON, JSON5, YAML, YML та TOML.
+V8R_CATALOG_PATH — визначає абсолютний шлях до каталогу схем `v8r-catalog.json` у корені пакета `@nitra/cursor`.
+runV8rWithGlobs — послідовно запускає перевірку кожного наданого патерну за допомогою `v8r`, використовуючи `v8r-catalog.json` як конфігурацію схем. Повертає код завершення, відображаючи вивід лише при виявленні помилки.
+
+## Публічний API
+
+- DEFAULT_V8R_GLOBS — Містить стандартні шаблони для пошуку файлів, які обробляє v8r.
+- V8R_CATALOG_PATH — Вказує на розташування файлу `v8r-catalog.json` у корені пакета.
+- runV8rWithGlobs — Виконує послідовні запуски v8r для файлів, знайдених за шаблонами, повертаючи код завершення.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/text/{lint/lint.mjs → main.mjs}

@@ -13,21 +13,33 @@
  * з неінформативним повідомленням. ensureTool збирає всі відсутні бінарники до першого кроку.
  *
  * Перший ненульовий код з ланцюжка повертається як код виходу; наступні кроки не запускаються.
- * Експортовано як `runLintTextCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-text`.
+ * Експортовано як `runLintTextCli` — викликається через `n-cursor lint text` (оркестраторний адаптер `lint()` делегує сюди); окремої bin-підкоманди `lint-text` немає.
  *
  * Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) —
  * `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
  */
 import { platform } from 'node:process'
 
-import { runLintStep } from '../../../scripts/lib/run-lint-step.mjs'
-import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
-import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
-import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
-import { runCspellText } from './cspell-fix.mjs'
-import { runDotenvLinter } from './run-dotenv-linter.mjs'
-import { runShellcheckText } from './run-shellcheck.mjs'
-import { runV8rWithGlobs } from './run-v8r.mjs'
+import { runLintStep } from '../../scripts/lib/run-lint-step.mjs'
+import { resolveCmd } from '../../scripts/utils/resolve-cmd.mjs'
+import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+import { ensureTool } from '../../scripts/lib/ensure-tool.mjs'
+import { runCspellText } from './js/cspell-fix.mjs'
+import { runDotenvLinter } from './js/run-dotenv-linter.mjs'
+import { runShellcheckText } from './js/run-shellcheck.mjs'
+import { runV8rWithGlobs } from './js/run-v8r.mjs'
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня (applies → JS-concerns
+ * → policy → mdc-refs); `lint()` нижче — lint-поверхня (markdownlint/cspell/shellcheck/…), імпл інлайн тут.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
 
 /**
  * Опис залежності preflight-ом.
@@ -120,7 +132,9 @@ function runLintTextSteps(readOnly = false, llmFix = false) {
   const dotenvCode = runDotenvLinter(process.cwd(), readOnly)
   if (dotenvCode !== 0) return dotenvCode
 
-  const mdArgs = readOnly ? ['markdownlint-cli2', '**/*.md', '**/*.mdc'] : ['markdownlint-cli2', '--fix', '**/*.md', '**/*.mdc']
+  const mdArgs = readOnly
+    ? ['markdownlint-cli2', '**/*.md', '**/*.mdc']
+    : ['markdownlint-cli2', '--fix', '**/*.md', '**/*.mdc']
   const markdownlintCode = runLintStep('markdownlint', 'bunx', mdArgs)
   if (markdownlintCode !== 0) return markdownlintCode
 
@@ -136,3 +150,20 @@ function runLintTextSteps(readOnly = false, llmFix = false) {
  */
 export const runLintTextCli = (opts = {}) =>
   runStandardLint(import.meta.dirname, () => runLintTextSteps(opts.readOnly === true, opts.llmFix === true))
+
+/**
+ * Оркестраторний адаптер `n-cursor lint text`: делегує у `runLintTextCli`.
+ * @param {string[] | undefined} _files ігнорується (whole-repo аналіз)
+ * @param {string} [_cwd] корінь (ігнорується — CLI працює від process.cwd())
+ * @param {{ readOnly?: boolean, llmFix?: boolean }} [opts] readOnly → детект без авто-фіксу;
+ *   llmFix → opt-in omlx-класифікація cspell
+ * @returns {Promise<number>} exit code
+ */
+export function lint(_files, _cwd, opts = {}) {
+  return runLintTextCli({ readOnly: opts.readOnly === true, llmFix: opts.llmFix === true })
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/text/main.mjs — повний еквівалент `npx @nitra/cursor check text`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/tool-surface/docs/index.md

@@ -6,6 +6,7 @@ resource: npm/rules/tool-surface/
 
 # npm/rules/tool-surface
 
-| Файл | Тип |
-|---|---|
-| [fix.mjs](fix.md) | JS Module |
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [fix.mjs](fix.md)   | JS Module |
+| [main.mjs](main.md) | JS Module |