@nitra/cursor 12.8.9 → 12.10.0

package/rules/text/main.mdc

@@ -6,40 +6,7 @@ version: '1.30'
 
 Правило охоплює весь текстовий стек проєкту: форматування (oxfmt), перевірку правопису (cspell), shell-скрипти (shellcheck), `.env`-файли (dotenv-linter), Markdown (markdownlint-cli2), JSON/YAML/TOML-схеми (v8r) та CI-workflow.
 
-[text-vscode](./js/vscode.mdc)
-
-[text-oxfmt](./js/oxfmt.mdc)
-
-[text-forbidden-prettier](./js/forbidden-prettier.mdc)
-
-[text-cspell](./js/cspell.mdc)
-
-[text-markdownlint](./js/markdownlint.mdc)
-
-[text-shellcheck](./js/shellcheck.mdc)
-
-[text-dotenv-linter](./js/dotenv-linter.mdc)
-
-[text-v8r](./js/v8r.mdc)
-
-[text-package-json](./js/package-json.mdc)
-
-[text-ci-lint-text](./js/ci-lint-text.mdc)
-
 ## Швидкий gate через conftest
 
 Rego-пакети, що перевіряються через conftest (auto-discovered за `target.json` поряд із `.rego`):
 
-[text-policy-cspell](./policy/cspell/cspell.mdc)
-
-[text-policy-lint_text](./policy/lint_text/lint_text.mdc)
-
-[text-policy-markdownlint](./policy/markdownlint/markdownlint.mdc)
-
-[text-policy-oxfmtrc](./policy/oxfmtrc/oxfmtrc.mdc)
-
-[text-policy-package_json](./policy/package_json/package_json.mdc)
-
-[text-policy-vscode_extensions](./policy/vscode_extensions/vscode_extensions.mdc)
-
-[text-policy-vscode_settings](./policy/vscode_settings/vscode_settings.mdc)

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

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

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

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

package/rules/vue/docs/index.md

@@ -8,5 +8,4 @@ resource: npm/rules/vue/
 
 | Файл                | Тип       |
 | ------------------- | --------- |
-| [fix.mjs](fix.md)   | JS Module |
 | [main.mjs](main.md) | JS Module |

package/rules/vue/docs/main.md

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

package/rules/vue/main.mdc

@@ -9,32 +9,10 @@ alwaysApply: false
 
 Правило охоплює стандарти написання Vue 3 SFC з Composition API, конфігурацію Vite-проєкту, UI-бібліотеки, заборонені патерни та вимоги до тестування.
 
-[vue-composition-api](./js/composition-api.mdc)
-
-[vue-quasar-ui](./js/quasar-ui.mdc)
-
-[vue-structure](./js/structure.mdc)
-
-[vue-vite-config](./js/vite-config.mdc)
-
-[vue-vite-env](./js/vite-env.mdc)
-
-[vue-vue-imports](./js/vue-imports.mdc)
-
-[vue-node-imports](./js/node-imports.mdc)
-
-[vue-testing](./js/testing.mdc)
-
-[vue-nheader-layout](./js/nheader-layout.mdc)
-
-[vue-tfm-translations](./js/tfm-translations.mdc)
-
 ## Швидкий gate через conftest
 
 Rego-перевірки (запускаються через `npx @nitra/cursor fix vue`):
 
-[vue-package_json](./policy/package_json/package_json.mdc)
-
 ## Перевірка
 
 `npx @nitra/cursor fix vue` — перевіряє залежності, `vite.config`, наявність **`src/vite-env.d.ts`** з `/// <reference types="vite/client" />` та **`jsconfig.json`** у корені Vue-пакета; обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім'я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/rules/vue/js/packages/vue-forbidden-imports.mjs`).

package/rules/worktree/docs/index.md

@@ -8,5 +8,4 @@ resource: npm/rules/worktree/
 
 | Файл                | Тип       |
 | ------------------- | --------- |
-| [fix.mjs](fix.md)   | JS Module |
 | [main.mjs](main.md) | JS Module |

package/rules/worktree/docs/main.md

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

package/scripts/docs/auto-rules.md

@@ -8,8 +8,6 @@ docgen:
   score: 90
 ---
 
-## Огляд
-
 Автоматично визначає правила та скіли для конфігурації `.n-cursor.json`, скануючи мета-дані з `npm/rules/<id>/main.json` та аналізуючи структуру проєкту, зокрема `package.json`. Система виводить `AUTO_RULE_ORDER` (алфавітно) та `AUTO_RULE_DEPENDENCIES` для кожного правила. Для кожного правила обчислюється специфікація активації (`specMatches`), яка може бути безумовною (`always`), заснованою на шаблонах файлів (`glob`), або предикатною. Процес враховує винятки (`disable-rules`) та виконує транзитивне розгортання залежностей. Збираються контент-факти (GQL, bun-sql, hasura) для точного застосування правил. Також відбувається автоматичне виявлення скілів з `./auto-skills.mjs`, після чого всі виявлені правила та скіли зливаються у конфіг, враховуючи міграцію ID.
 
 ## Поведінка

package/scripts/docs/auto-skills.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Визначає, які скіли мають автоматично активуватися, скануючи `npm/skills/` та аналізуючи `main.json` кожного скілу. Логіка активації базується на конфігурації скілу: скіл може активуватися завжди (`auto: "завжди"`), якщо всі перелічені правила виявлені (`auto: ["rule", …]`), або бути opt-in, якщо поле `auto` відсутнє у `main.json`. Це забезпечує, що визначення автоматичної активації скілів є детермінованим, оскільки `main.json` є джерелом правди. Результати сканування використовуються для встановлення `AUTO_SKILL_ORDER` та `AUTO_SKILL_RULE_DEPENDENCIES`, що впливає на роботу з `.n-cursor.json`.
 
 ## Поведінка

package/scripts/docs/hook.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: hook.mjs
+resource: npm/scripts/hook.mjs
+docgen:
+  crc: 602cd023
+  model: claude-sonnet-4-6
+  score: 100
+---
+
+Точка входу для хуків Claude Code. У режимі `--post-tool-use` зчитує `file_path` зі stdin JSON (PostToolUse hook), запускає lint для цього файлу та перевіряє актуальність файлової документації (`doc-files`). У режимі `--stop` визначає змінені файли (`git diff HEAD` + untracked) і запускає lint по всьому робочому дереву. Повертає exit-код у hook-протоколі (ненуль → 2).
+
+## Поведінка
+
+`runHookCli` виконує відповідну логіку залежно від переданого режиму:
+
+- **`--post-tool-use`**: читає stdin JSON → витягує `tool_input.file_path` → запускає `runLint` для цього файлу (read-only, усі per-file правила включно з `doc-files`) → повертає 2 при порушеннях.
+- **`--stop`**: визначає всі змінені файли через `collectChangedFiles` → запускає `runLint` (read-only) → повертає 2 при порушеннях.
+
+Якщо `file_path` відсутній у stdin або stdin порожній — завершується з кодом 0 (нема що перевіряти).
+
+## Публічний API
+
+- `extractFilePath(json)` — витягує `tool_input.file_path` зі stdin JSON Claude Code PostToolUse hook; повертає `null` якщо JSON відсутній або поле не знайдено.
+- `runHookCli(argv)` — CLI-точка входу для `n-cursor hook`; повертає Promise<number> (0 — чисто, 1 — невідомий режим, 2 — є порушення).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Не кидає винятків назовні: помилки stdin та parse-помилки повертають null/0.

package/scripts/docs/index.md

@@ -15,11 +15,10 @@ resource: npm/scripts/
 | [coverage-fix-extract.mjs](coverage-fix-extract.md)                                 | JS Module |
 | [coverage-fix.mjs](coverage-fix.md)                                                 | JS Module |
 | [ensure-nitra-cursor-dev-dependencies.mjs](ensure-nitra-cursor-dev-dependencies.md) | JS Module |
+| [hook.mjs](hook.md)                                                                 | JS Module |
 | [post-tool-use-check.mjs](post-tool-use-check.md)                                   | JS Module |
-| [post-tool-use-fix.mjs](post-tool-use-fix.md)                                       | JS Module |
 | [rename-yaml-extensions.mjs](rename-yaml-extensions.md)                             | JS Module |
 | [skills-cli.mjs](skills-cli.md)                                                     | JS Module |
 | [sync-claude-config.mjs](sync-claude-config.md)                                     | JS Module |
 | [sync-setup-bun-deps-action.mjs](sync-setup-bun-deps-action.md)                     | JS Module |
 | [upgrade-nitra-cursor-and-install.mjs](upgrade-nitra-cursor-and-install.md)         | JS Module |
-| [worktree-cli.mjs](worktree-cli.md)                                                 | JS Module |

package/scripts/docs/post-tool-use-check.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Цей модуль є PostToolUse hook, який виконує read-only детект конформності всіх активованих правил після кожного редагування файлу (`Edit` / `Write` / `MultiEdit`). Він отримує шлях до файлу з вхідного JSON. Якщо файл відсутній, модуль завершує роботу з кодом 0. Інакше, він запускає детект конформності по всіх правилах, не виконуючи жодних мутацій чи викликів LLM. Код виходу 1 інформує про наявність порушень конформності, хоча PostToolUse не блокує поточний обмін.
 
 ## Поведінка

package/scripts/docs/sync-claude-config.md

@@ -3,13 +3,11 @@ type: JS Module
 title: sync-claude-config.mjs
 resource: npm/scripts/sync-claude-config.mjs
 docgen:
-  crc: 88f4080d
+  crc: 553933fa
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 85
 ---
 
-## Огляд
-
 Синхронізує конфігурацію Claude Code (`.claude/settings.json`, slash-команди з `commands/` темплейту, ADR Stop-hook) та Cursor hooks (`.cursor/hooks.json`) у поточний проєкт із темплейтів пакету `npm/.claude-template/`. Здійснює злиття конфігурацій: користувацькі поля зберігаються у `.claude/settings.json`, а дозволи (`permissions.allow`) зливаються через union. Керовані хуки, ідентифіковані командою-маркером `MANAGED_HOOK_COMMAND_MARKERS`, перезаписуються. Копіює ADR Stop-hook (`.claude/hooks/capture-decisions.sh`) та ADR normalize Stop-hook (`.claude/hooks/normalize-decisions.sh`) залежно від налаштувань у `.n-cursor.json`. Також зливає фрагмент `.gitignore` з канонічного шаблону, додаючи необхідні записи для ADR.
 
 ## Поведінка

package/scripts/docs/sync-setup-bun-deps-action.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Копіює composite GitHub Action `setup-bun-deps` з каталогу `github-actions/setup-bun-deps/` у корені tarball пакету `@nitra/cursor` у цільовий репозиторій за шлях `.github/actions/setup-bun-deps/action.yml`. Це забезпечує можливість для workflow з правил `ga`, `js` або `text` викликати цей action для налаштування залежностей Bun одразу після виконання `actions/checkout@v6`.
 
 ## Поведінка

package/scripts/hook.mjs

@@ -0,0 +1,71 @@
+/**
+ * Thin hook entrypoint для Claude Code hooks: зчитує контекст (stdin / git),
+ * делегує в `runLint({ readOnly: true })`, перекодовує exit-код у hook-протокол (1 → 2).
+ *
+ * Режими:
+ *   --post-tool-use  PostToolUse: file_path зі stdin JSON Claude Code.
+ *   --stop           Stop: робоче дерево vs HEAD (`git diff HEAD` + untracked).
+ */
+import { once } from 'node:events'
+import { cwd as processCwd } from 'node:process'
+
+import { runLint } from './lib/run-lint.mjs'
+import { collectChangedFiles } from './lib/changed-files.mjs'
+
+/**
+ * @returns {Promise<string>} вміст stdin або '' на TTY
+ */
+async function readStdin() {
+  if (process.stdin.isTTY) return ''
+  process.stdin.setEncoding('utf8')
+  const chunks = []
+  process.stdin.on('data', c => chunks.push(c))
+  try {
+    await once(process.stdin, 'end')
+  } catch {
+    // error на stdin — повертаємо що встигли
+  }
+  return chunks.join('')
+}
+
+/**
+ * Дістає `tool_input.file_path` зі stdin JSON Claude Code PostToolUse hook.
+ * @param {string} json сирий stdin
+ * @returns {string|null}
+ */
+export function extractFilePath(json) {
+  if (!json) return null
+  try {
+    const fp = JSON.parse(json)?.tool_input?.file_path
+    return typeof fp === 'string' && fp !== '' ? fp : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * CLI для `n-cursor hook`.
+ * @param {string[]} argv аргументи після 'hook'
+ * @returns {Promise<number>} exit-код (0 — чисто; 2 — є порушення hook-протокол)
+ */
+export async function runHookCli(argv) {
+  const cwd = processCwd()
+  const postToolUse = argv.includes('--post-tool-use')
+  const stop = argv.includes('--stop')
+
+  if (!postToolUse && !stop) {
+    process.stderr.write('hook: потрібен --post-tool-use або --stop\n')
+    return 1
+  }
+
+  if (postToolUse) {
+    const fp = extractFilePath(await readStdin())
+    if (!fp) return 0
+    const code = await runLint({ files: [fp], readOnly: true, cwd })
+    return code !== 0 ? 2 : 0
+  }
+
+  const files = collectChangedFiles(cwd)
+  const code = await runLint({ files, readOnly: true, cwd })
+  return code !== 0 ? 2 : 0
+}

package/scripts/lib/docs/check-mdc-template-refs.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Визначає список файлів шаблонів, що знаходяться у каталогах `fix` та `policy`, які не є цільовими посиланнями у файлі `<id>.mdc` як markdown link targets. Це дозволяє ідентифікувати ресурси шаблонів, які не були згадані в контексті правила.
 
 ## Поведінка

package/scripts/lib/docs/index.md

@@ -6,40 +6,39 @@ resource: npm/scripts/lib/
 
 # npm/scripts/lib
 
-| Файл | Тип |
-|---|---|
-| [assert-project-root.mjs](assert-project-root.md) | JS Module |
-| [changed-files.mjs](changed-files.md) | JS Module |
-| [check-mdc-template-refs.mjs](check-mdc-template-refs.md) | JS Module |
-| [check-reporter.mjs](check-reporter.md) | JS Module |
-| [diff-added-lines.mjs](diff-added-lines.md) | JS Module |
+| Файл                                                                        | Тип       |
+| --------------------------------------------------------------------------- | --------- |
+| [assert-project-root.mjs](assert-project-root.md)                           | JS Module |
+| [changed-files.mjs](changed-files.md)                                       | JS Module |
+| [check-mdc-template-refs.mjs](check-mdc-template-refs.md)                   | JS Module |
+| [check-reporter.mjs](check-reporter.md)                                     | JS Module |
+| [diff-added-lines.mjs](diff-added-lines.md)                                 | JS Module |
 | [discover-check-rules-from-cursor.mjs](discover-check-rules-from-cursor.md) | JS Module |
-| [discover-checkable-rules.mjs](discover-checkable-rules.md) | JS Module |
-| [ensure-tool.mjs](ensure-tool.md) | JS Module |
-| [generated-markdown.mjs](generated-markdown.md) | JS Module |
-| [gha-workflow.mjs](gha-workflow.md) | JS Module |
-| [inline-template-links.mjs](inline-template-links.md) | JS Module |
-| [list-project-rules-mdc.mjs](list-project-rules-mdc.md) | JS Module |
-| [list-rule-ids.mjs](list-rule-ids.md) | JS Module |
-| [load-cursor-config.mjs](load-cursor-config.md) | JS Module |
-| [mirror-parity.mjs](mirror-parity.md) | JS Module |
-| [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md) | JS Module |
-| [resolve-target-files.mjs](resolve-target-files.md) | JS Module |
-| [root-notice.mjs](root-notice.md) | JS Module |
-| [rule-meta-helpers.mjs](rule-meta-helpers.md) | JS Module |
-| [rule-meta.mjs](rule-meta.md) | JS Module |
-| [rule-predicates.mjs](rule-predicates.md) | JS Module |
-| [run-conftest-batch.mjs](run-conftest-batch.md) | JS Module |
-| [run-lint-step.mjs](run-lint-step.md) | JS Module |
-| [run-lint.mjs](run-lint.md) | JS Module |
-| [run-rule-cli.mjs](run-rule-cli.md) | JS Module |
-| [run-rule.mjs](run-rule.md) | JS Module |
-| [run-standard-lint.mjs](run-standard-lint.md) | JS Module |
-| [run-standard-rule.mjs](run-standard-rule.md) | JS Module |
-| [skill-meta.mjs](skill-meta.md) | JS Module |
-| [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md) | JS Module |
-| [template.mjs](template.md) | JS Module |
-| [timing-summary.mjs](timing-summary.md) | JS Module |
-| [workspaces.mjs](workspaces.md) | JS Module |
-| [worktree-notice.mjs](worktree-notice.md) | JS Module |
-| [worktree.mjs](worktree.md) | JS Module |
+| [discover-checkable-rules.mjs](discover-checkable-rules.md)                 | JS Module |
+| [ensure-tool.mjs](ensure-tool.md)                                           | JS Module |
+| [generated-markdown.mjs](generated-markdown.md)                             | JS Module |
+| [gha-workflow.mjs](gha-workflow.md)                                         | JS Module |
+| [inline-template-links.mjs](inline-template-links.md)                       | JS Module |
+| [list-project-rules-mdc.mjs](list-project-rules-mdc.md)                     | JS Module |
+| [list-rule-ids.mjs](list-rule-ids.md)                                       | JS Module |
+| [load-cursor-config.mjs](load-cursor-config.md)                             | JS Module |
+| [mirror-parity.mjs](mirror-parity.md)                                       | JS Module |
+| [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md)               | JS Module |
+| [resolve-target-files.mjs](resolve-target-files.md)                         | JS Module |
+| [root-notice.mjs](root-notice.md)                                           | JS Module |
+| [rule-meta-helpers.mjs](rule-meta-helpers.md)                               | JS Module |
+| [rule-meta.mjs](rule-meta.md)                                               | JS Module |
+| [rule-predicates.mjs](rule-predicates.md)                                   | JS Module |
+| [run-conftest-batch.mjs](run-conftest-batch.md)                             | JS Module |
+| [run-lint-step.mjs](run-lint-step.md)                                       | JS Module |
+| [run-lint.mjs](run-lint.md)                                                 | JS Module |
+| [run-rule-cli.mjs](run-rule-cli.md)                                         | JS Module |
+| [run-rule.mjs](run-rule.md)                                                 | JS Module |
+| [run-standard-lint.mjs](run-standard-lint.md)                               | JS Module |
+| [run-standard-rule.mjs](run-standard-rule.md)                               | JS Module |
+| [skill-meta.mjs](skill-meta.md)                                             | JS Module |
+| [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md)                   | JS Module |
+| [template.mjs](template.md)                                                 | JS Module |
+| [timing-summary.mjs](timing-summary.md)                                     | JS Module |
+| [workspaces.mjs](workspaces.md)                                             | JS Module |
+| [worktree-notice.mjs](worktree-notice.md)                                   | JS Module |

package/scripts/lib/docs/inline-template-links.md

@@ -3,24 +3,22 @@ type: JS Module
 title: inline-template-links.mjs
 resource: npm/scripts/lib/inline-template-links.mjs
 docgen:
-  crc: b659349c
+  crc: e1bed533
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-## Огляд
-
-Цей модуль реалізує механізми вбудовування контенту в текстові документи, використовуючи конфігурації з `package.json.snippet.json` та `package.json`. Він замінює посилання в тексті на вміст файлів-шаблонів, розташованих у каталозі правил, а також на вміст файлів з розширенням .mdc, які не є шаблонами. Функції дозволяють вставляти посилання на шаблони (`inlineTemplateLinks`) та включати вміст Markdown (`inlineMarkdownIncludes`).
+Модуль інтегрує зовнішній контент у текстовий вивід, використовуючи конфігурації з `package.json.snippet.json` та `package.json`. Він замінює посилання на шаблони в тексті на їхній вміст за допомогою `inlineTemplateLinks` та доповнює текст вмістом усіх знайдених файлів `.mdc` з директорій `js/` та `policy/<concern>/` за допомогою `appendDiscoveredMdcFiles`.
 
 ## Поведінка
 
-inlineTemplateLinks замінює посилання в тексті на вбудовані блоки з вмістом файлів, що містять шаблони, якщо ці файли знаходяться в каталозі правил.
-inlineMarkdownIncludes замінює посилання в тексті на вміст файлів з розширенням .mdc, якщо ці файли не є шаблонами.
+inlineTemplateLinks замінює посилання на шаблони в тексті на вбудовані блоки з вмістом відповідних файлів.
+appendDiscoveredMdcFiles додає вміст усіх знайдених файлів \*.mdc з директорій js/ та policy/<concern>/ до наданого тексту.
 
 ## Публічний API
 
-inlineTemplateLinks — Замінює посилання у Markdown, що містять `/template/`, на вбудовані блокові конструкції, зчитуючи вміст з вказаного файлу. Викидає помилку, якщо цільове посилання не знайдено.
-inlineMarkdownIncludes — Замінює посилання у Markdown, що закінчуються на `.mdc` (і не є шляхом `/template/`), на сирий вміст відповідного файлу Markdown. Викидає помилку, якщо цільове посилання не знайдено.
+inlineTemplateLinks — Замінює посилання у Markdown, що містять `/template/`, на вбудовані блоки, зчитуючи вміст з вказаного файлу. Викидає помилку, якщо цільове посилання не знайдено.
+appendDiscoveredMdcFiles — Додає всі знайдені файли з розширенням `.mdc` з підкаталогів `js/` та `policy/<concern>/`. Спочатку додаються файли з `js/` (у алфавітному порядку), а потім файли з підкаталогів `policy/` (у алфавітному порядку за назвою `concern`, а потім за назвою файлу).
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/list-project-rules-mdc.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Цей модуль визначає шлях до `.mdc`-файлів правил у проєкті-споживачі, що зберігаються у директорії, вказаній константою CURSOR_RULES_DIR. Він надає відсортований список імен цих файлів. Це винесення логіки з `bin/n-cursor.js` забезпечує розділення відповідальності між інструментом командного рядка та функцією перевірки конформності.
 
 ## Поведінка

package/scripts/lib/docs/list-rule-ids.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Перебирає директорії у `rules/` та фільтрує їх, вибираючи лише ті, що містять єдиний канонічний entrypoint (`rules/<id>/main.mjs`), згідно з ADR 2026-06-21. Функція повертає список ідентифікаторів правил, які відповідають цьому канону. Операція є лише для читання файлової системи.
 
 ## Поведінка

package/scripts/lib/docs/mirror-parity.md

@@ -3,31 +3,29 @@ type: JS Module
 title: mirror-parity.mjs
 resource: npm/scripts/lib/mirror-parity.mjs
 docgen:
-  crc: 093ff2bb
+  crc: 91a0c9f2
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 90
 ---
 
-## Огляд
-
-Модуль забезпечує паритет дзеркал правил, порівнюючи вміст `.cursor/rules/n-<id>.mdc` з канонічним вмістом `npm/rules/<id>/<id>.mdc`. Він визначає, які дзеркала відстежувати, формує очікуваний вміст цих дзеркал після застосування шаблонів (трансформу, що застосовує `readBundledRuleContent` $\rightarrow$ `inlineTemplateLinks`), та виявляє дрейф, що виникає, коли канонічний `.mdc` змінюється без регенерації дзеркала.
+Модуль реалізує механізм перевірки паралельності (parity) дзеркал правил. Він визначає список дзеркал, створює очікуваний вміст для кожного дзеркала, трансформуючи канонічний файл `npm/rules/<id>/<id>.mdc` з inlined-шаблонами — тим самим трансформом, що застосовує синк (`readBundledRuleContent` → `inlineTemplateLinks`). Механізм виявляє дрейф, коли фактичний вміст дзеркала `.cursor/rules/n-<id>.mdc` відрізняється від очікуваного, що виникає при зміні канонічного `.mdc` без регенерації дзеркала.
 
 ## Поведінка
 
 listManagedMirrors
-Визначає список керованих дзеркал правил, що мають канонічне джерело у `npm/rules`.
+Визначає список керованих дзеркал правил, які мають канонічне джерело в `npm/rules`.
 
 expectedMirrorContent
-Формує очікуваний вміст дзеркала, застосовуючи трансформації до канонічного файлу.
+Створює очікуваний вміст дзеркала, трансформуючи канонічний файл з вбудованими шаблонами.
 
 findMirrorDrift
-Виявляє ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного.
+Виявляє ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного вмісту, отриманого з канону.
 
 ## Публічний API
 
-listManagedMirrors — перераховує керовані дзеркала, які мають визначене основне джерело.
-expectedMirrorContent — визначає бажаний вміст дзеркала, використовуючи шаблонне заміщення даних.
-findMirrorDrift — знаходить ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного.
+listManagedMirrors — перераховує лише ті дзеркала, які мають визначене основне джерело (канон).
+expectedMirrorContent — визначає, як має виглядати вміст дзеркала, використовуючи канонічну версію з вбудованими шаблонами.
+findMirrorDrift — виявляє ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного.
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/read-n-cursor-config-lite.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Модуль надає легкий, лише для читання, інтерфейс для парсингу конфігурації `.n-cursor.json`. Він призначений для ізольованих, окремих викликів `check.mjs`. Модуль визначає стан кожного правила, ґрунтуючись на вмісті `.n-cursor.json`. Якщо файл відсутній, правило вважається активним (поведінка "open by default"). Якщо файл присутній, стан правила залежить від списків `rules` та `disableRules` у конфігурації. Модуль повертає об'єкт, що містить списки активних та вимкнених правил.
 
 ## Поведінка

package/scripts/lib/docs/rule-meta.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Парсер метаданих правил з `npm/rules/<id>/main.json` інтерпретує специфікації активації (`auto`) та області дії (`lint`). Він нормалізує логіку, визначену у `main.json.auto`, яка може бути константою `RULE_ALWAYS="завжди"`, списком залежностей, об'єктом з шаблоном `glob`, або предикатом. Код лише зчитує дані та не виконує операцій з файловою системою чи базами даних. При виникненні помилок він перехоплює їх, повертаючи безпечне значення замість винятків.
 
 ## Поведінка

package/scripts/lib/docs/run-lint.md

@@ -3,27 +3,26 @@ type: JS Module
 title: run-lint.mjs
 resource: npm/scripts/lib/run-lint.mjs
 docgen:
-  crc: 7d8f3637
+  crc: f574f097
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-## Огляд
-
-Модуль ініціалізує та керує процесом лінтування коду. Він визначає набір правил лінтування, спираючись на конфігурацію, описану в `meta.json`, та прапорець `full`, використовуючи активні правила з `.n-cursor.json`. Після визначення правил, він запускає лінтер-оркестрацію для виконання лінтування по всьому репозиторію або в режимі дельти. Модуль підтримує автоматичне форматування коду за допомогою `oxfmt`.
+Модуль керує процесом лінтування коду. Він визначає набір активних правил лінтування, використовуючи конфігурації з `meta.json` та `.n-cursor.json`. Модуль надає можливість вибрати ці правила за допомогою `selectLintRules` та ініціювати запуск перевірки коду за допомогою `runLint`.
 
 ## Поведінка
 
-selectLintRules вибирає і відсортовує ідентифікатори правил для лінтування на основі їхньої конфігурації лінту та прапорця `full`, враховуючи активні правила з `.n-cursor.json`.
-runLint запускає лінтер-оркестрацію, виконуючи лінтування в режимі дельти або по всьому репозиторію, залежно від прапорця `full`, і може виконувати форматування за допомогою `oxfmt` у режимі фіксації.
+selectLintRules визначає, які правила лінтуються на основі їхньої конфігурації та активності в `.n-cursor.json`, повертаючи відсортований список ID.
+runLint запускає лінтер-оркестрацію залежно від наданих опцій: виконує прогін для конкретних правил, перевіряє лише змінені файли, виконує повний прогін репозиторію або форматування.
 
 ## Публічний API
 
-selectLintRules — вибирає ідентифікатори правил для контексту, розташовуючи їх в алфавітному порядку.
+selectLintRules — вибирає ідентифікатори правил для контексту в алфавітному порядку.
 runLint — ініціює процес лінтування.
-  full — сканує весь репозиторій, порівнюючи його з базовою версією.
-  readOnly — лише виявляє проблеми без внесення змін, порівнюючи з базовою версією.
-  rules — виконує повне сканування лише для заданого набору правил.
+full — аналізує весь репозиторій, порівнюючи поточний стан із початковим.
+readOnly — лише виявляє проблеми, не вносячи змін.
+rules — виконує повний прогін лише для заданого набору правил у вказаному контексті.
+files — виконує перевірку лише для перелічених файлів у режимі хука.
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/run-rule-cli.md

@@ -8,8 +8,6 @@ docgen:
   score: 95
 ---
 
-## Огляд
-
 Standalone CLI runner для одного правила. Викликається з `rules/<id>/check.mjs` у блоці `if (import.meta.main)`, що робить його повним еквівалентом `bun rules/<id>/check.mjs` або `npx @nitra/cursor fix <id>`. Цей запуск є свідомим (debug / override) і виконується без whitelist-гейту. Ініціалізує кеш для проходження файлової системи та виконує стандартну перевірку, друкуючи summary результату та повертаючи aggregated exit-code.
 
 ## Поведінка

package/scripts/lib/docs/run-rule.md

@@ -3,25 +3,23 @@ type: JS Module
 title: run-rule.mjs
 resource: npm/scripts/lib/run-rule.mjs
 docgen:
-  crc: 7d0585e1
+  crc: c9b164c7
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 90
+  score: 100
 ---
 
-## Огляд
-
-Файл оркеструє виконання одного правила під CLI `fix`. Він послідовно застосовує гейт `applies` з `js/applies.mjs` для визначення придатності правила. Якщо гейт повертає `false`, правило не застосовується. Далі виконуються JS-концерни та Policy-концерни в алфавітному порядку. Резолвер `resolveTargetFiles` ділить кеш між концернами. Кожен concern створює власний репортер, а їхні exit-коди OR-уються в єдиний контракт, що забезпечує 0/1 результат для правила. Оркестратор спирається на конфігурації `target.json` та `.n-cursor.json`.
+Файл оркеструє виконання одного правила під CLI `fix`. Він послідовно застосовує `applies`-гейт, а потім виконує JS-концерни та Policy-концерни. Резолвер ділить кеш між концернами, а кожен concern має власний механізм звітності, що об'єднується в єдиний exit-код правила. Процес спирається на конфігураційні файли, зокрема `target.json` та `.n-cursor.json`.
 
 ## Поведінка
 
-runTemplateSubsetConcern виконує перевірку концерну, де канон визначається сніпетом у `target.json`, звіряючи його з актуальними файлами-таргетами.
+runTemplateSubsetConcern виконує перевірку концерну, де канон визначено у `target.json` як `template`, звіряючи вміст файлів-таргетів з шаблоном, визначеним у відповідному каталозі.
 
-runRule оркеструє виконання одного правила, послідовно застосовуючи applies-гейт, виконуючи JS-концерни та запускаючи policy-концерни, а також перевіряючи відсутність markdown-посилань.
+runRule оркеструє виконання одного правила, послідовно застосовуючи `applies`-гейт, виконуючи JS-концерни, запускаючи policy-концерни та перевіряючи відсутність markdown-посилань у `main.mdc`.
 
 ## Публічний API
 
-runTemplateSubsetConcern — Порівнює фактичний файл із канонічним шаблоном (з `target.json`) для перевірки, чи всі обов'язкові елементи присутні, дозволяючи додаткові.
-runRule — Виконує окреме правило, яке проходить через перевірки застосовності, JavaScript-концерни та політики.
+runTemplateSubsetConcern — Порівнює фактичний файл з канонічним шаблоном (`target.json:"check":"template"`), визначаючи, чи всі обов'язкові елементи з шаблону присутні у файлі.
+runRule — Виконує окреме правило, перевіряючи його відповідність через гейт, JavaScript-концерни та політики.
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/run-standard-lint.md

@@ -8,8 +8,6 @@ docgen:
   score: 90
 ---
 
-## Огляд
-
 Спільна точка входу для канонічних `lint-<rule>` підкоманд `@nitra/cursor`. Файл серіалізує та дедуплікує запуски лінту через `withLock`. `ruleId` визначається зі шляху незалежно від глибини виклику (наприклад, `rules/<id>`). Це дозволяє уніфікувати крос-cutting концерни. Інтеграція з боку правила виглядає так:
 
 - import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'