@7n/rules 1.0.0

package/scripts/docs/auto-rules.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: auto-rules.mjs
+resource: npm/scripts/auto-rules.mjs
+docgen:
+  crc: 6ce82609
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+Автоматично визначає правила та скіли для конфігурації `.n-rules.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.
+
+## Поведінка
+
+discoverRuleAutoActivation сканує директорію `rules` та виявляє мета-дані для автоматичного визначення правил.
+AUTO_RULE_ORDER надає стабільний алфавітний порядок для всіх правил, виявлених під час автоматичного визначення.
+AUTO_RULE_DEPENDENCIES визначає транзитивні залежності між правилами, виявленими під час автоматичного визначення.
+collectAutoRuleFacts обходить дерево проєкту, збираючи контент-факти про наявність певних структур (наприклад, GQL, Hasura, Rego).
+detectAutoRules визначає список правил, які мають бути активні, на основі мета-даних правил та зібраних контент-фактів, враховуючи виключення.
+mergeConfigWithAutoDetected об'єднує конфігурацію користувача з результатами автоматичного визначення правил та скілів, прибираючи з конфігу ті елементи, яких більше немає у пакеті.
+
+## Публічний API
+
+discoverRuleAutoActivation — Зчитує `main.json` для кожного правила у `npm/rules/<id>/` та створює список правил, які можуть активуватися автоматично.
+AUTO_RULE_ORDER — Визначає порядок застосування автоматичних правил за алфавітом.
+AUTO_RULE_DEPENDENCIES — Створює граф залежностей між автоматичними правилами, використовуючи метадані.
+collectAutoRuleFacts — Сканує структуру проєкту та збирає факти про вміст, необхідні для визначення, які автоматичні правила активувати.
+detectAutoRules — Визначає, які автоматичні правила доступні на основі файлу `main.json` кожного правила.
+mergeConfigWithAutoDetected — Обновлює конфігурацію, додаючи автоматично виявлені правила, і очищає список доступних правил/навичок від тих, що більше не існують у пакеті, фіксуючи видалені ID у полі `pruned`.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

package/scripts/docs/auto-skills.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: auto-skills.mjs
+resource: npm/scripts/auto-skills.mjs
+docgen:
+  crc: c27a242a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Визначає, які скіли мають автоматично активуватися, скануючи `npm/skills/` та аналізуючи `main.json` кожного скілу. Логіка активації базується на конфігурації скілу: скіл може активуватися завжди (`auto: "завжди"`), якщо всі перелічені правила виявлені (`auto: ["rule", …]`), або бути opt-in, якщо поле `auto` відсутнє у `main.json`. Це забезпечує, що визначення автоматичної активації скілів є детермінованим, оскільки `main.json` є джерелом правди. Результати сканування використовуються для встановлення `AUTO_SKILL_ORDER` та `AUTO_SKILL_RULE_DEPENDENCIES`, що впливає на роботу з `.n-rules.json`.
+
+## Поведінка
+
+discoverSkillAutoActivation сканує директорію `npm/skills/` і визначає специфікації автоматичної активації скілів на основі вмісту `main.json` кожного скілу.
+AUTO_SKILL_ORDER надає стабільний алфавітний порядок усіх скілів, які мають визначену автоматичну активацію.
+AUTO_SKILL_RULE_DEPENDENCIES надає мапу скілів, які залежать від певних правил, для забезпечення зворотної сумісності.
+detectAutoSkills визначає, які скіли мають бути автоматично активовані, порівнюючи доступні скіли з виявленими правилами та специфікаціями активації.
+
+## Публічний API
+
+discoverSkillAutoActivation — Знаходить скіли, які мають файл `main.json` у відповідній директорії, і які мають автоматичну активацію.
+AUTO_SKILL_ORDER — Забезпечує фіксований алфавітний порядок скілів, що автоматично активуються, для підтримки старої версії.
+AUTO_SKILL_RULE_DEPENDENCIES — Створює список скілів, що автоматично активуються і мають визначені правила залежностей.
+detectAutoSkills — Виявляє скіли, які мають автоматичну активацію на основі вмісту файлу `auto.md` у директорії скілу.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/scripts/docs/build-agents-commands.md

@@ -0,0 +1,37 @@
+---
+type: JS Module
+title: build-agents-commands.mjs
+resource: npm/scripts/build-agents-commands.mjs
+docgen:
+  crc: 434187b3
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+File: `/Users/vitalii/www/nitra/cursor/docs/n-doc-files/SKILL.md`
+
+Формує повний список команд для секції «Команди» у AGENTS.md. Джерело істини — `package.json` у корені цільового репозиторію, з поля `scripts` береться відомі ключі у стабільному порядку, додатково — усі `lint-*`, яких не було в основному списку. Наприкінці завжди додаються рядки про CLI `@7n/rules` (синхрон правил / programmatic check), на початку — рекомендована команда `bun i` за конвенціями monorepo.
+
+## Поведінка
+
+1. Викликається `buildAgentsCommandBulletItems` для формування переліку команд.
+2. Функція зчитує розділ `scripts` з `package.json` у корені проекту.
+3. Якщо `package.json` відсутній або має некоректний формат, функція повертає порожній набір даних.
+4. Створюється базовий перелік команд, що починається з команди встановлення залежностей `bun i`.
+5. Додаються команди зі стабільно визначеного списку ключових скриптів з `package.json` у порядку `test`, `lint`, `lint-js`, `lint-text`, `lint-ga`, `lint-k8s`, `lint-docker`, `start`, `dev`, `build`.
+6. Подалі додаються всі інші ключі скриптів, які починаються з `lint-` та не були додані у попередньому кроці, відсортовані лексикографічно.
+7. У кінці завжди додаються команди, пов'язані з CLI `@7n/rules` та `knip`.
+8. Повертається список елементів, готовий для формування Markdown-секції «Команди».
+
+## Публічний API
+
+buildAgentsCommandBulletItems — створює список команд для розділу `commands` у `AGENTS.template.md`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/scripts/docs/cli-entry.md

@@ -0,0 +1,36 @@
+---
+type: JS Module
+title: cli-entry.mjs
+resource: npm/scripts/cli-entry.mjs
+docgen:
+  crc: b51b5d0a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  retried: true
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль визначає, чи виконується поточний ESM-модуль як точка входу командного рядка (CLI). Він перевіряє, чи шлях, що був запущений безпосередньо через CLI, збігається з нормалізованим абсолютним шляхом модуля. Ця функціональність надається через публічний метод `isRunAsCli`. Модуль працює у безпечному режимі, перехоплюючи потенційні помилки та повертаючи порожнє значення (наприклад, `null`) замість викидання винятків. Операції не підтримують кешування.
+
+## Поведінка
+
+1. Викликається функція isRunAsCli, передається URL, що посилається на модуль-викликач.
+2. Якщо URL-викликач не надано, функція повертає хибне значення.
+3. Визначається шлях до файлу-викликача шляхом перетворення наданого URL на абсолютний шлях та нормалізації цього шляху.
+4. Визначається шлях до файлу, який був запущений безпосередньо через командний рядок.
+5. Шлях до запущеного файлу також нормалізується.
+6. Якщо шляхи до файлу-викликача та запущеного файлу збігаються, функція повертає істинне значення, що означає, що модуль виконується як точка входу CLI.
+7. Якщо виникає будь-яка помилка під час отримання шляхів, функція повертає хибне значення.
+
+## Публічний API
+
+isRunAsCli — визначає, чи викликається модуль як основна команда (точка входу), а не імпортується іншим кодом.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/docs/ensure-n-rules-dev-dependencies.md

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: ensure-n-rules-dev-dependencies.mjs
+resource: npm/scripts/ensure-n-rules-dev-dependencies.mjs
+docgen:
+  crc: 0b47c3b7
+  model: hand
+  score: 100
+---
+
+## Огляд
+
+Файл гарантує присутність інструменту `@7n/rules` у кореневому `package.json` проєкту — лише якщо проєкт ідентифікується як workspace-root за наявністю поля `workspaces` у `package.json` поруч із точкою запуску. Це забезпечує відтворюваність команд `npx @7n/rules` і скриптів з `node_modules/@7n/rules/scripts/` після `bun install` / `npm install`.
+
+Крім дописування відсутнього пакета, реалізовано **self-upgrade**: якщо `@7n/rules` уже присутній у `devDependencies` зі старішим числовим піном, він апгрейдиться до `^<версія встановленого CLI>` при кожному запуску. Це прибирає дрейф версії self-lint у споживачів.
+
+## Поведінка
+
+`readBundledPackageVersion` повертає версію пакета `@7n/rules` з його власного `package.json` або `null`, якщо файл не знайдено чи не вдалося розпарсити.
+
+`ensureNRulesInRootDevDependencies` знаходить кореневий `package.json` (workspace-root) і:
+
+- якщо `@7n/rules` **відсутній** у `devDependencies`/`dependencies` — дописує його в `devDependencies` як `^<bundledVersion>`;
+- якщо вже **присутній у `devDependencies`** зі старішим числовим піном — апгрейдить пін до `^<bundledVersion>` (ніколи не понижує; нечислові піни `workspace:*`/`latest`/git не чіпаються);
+- якщо присутній у `dependencies` (нестандартне розміщення) — лишає незмінним.
+
+Порівняння версій — за числовими компонентами `major.minor.patch` (`parseVersionParts` розбирає діапазон із опційним оператором `^`/`~`/`>=`/`<=`/`>`/`<`/`=`/`v`; `isBundledNewer` порівнює покомпонентно).
+
+## Публічний API
+
+`readBundledPackageVersion` — витягує `version` пакета `@7n/rules` з його `package.json`, або `null`.
+`ensureNRulesInRootDevDependencies(root, options?)` — гарантує актуальний пін `@7n/rules` у `devDependencies` кореневого `package.json`: додає за відсутності або апгрейдить старіший числовий пін. `options.bundledVersion` — версія для тестів; `options.silent` — не логувати. Повертає `true`, якщо `package.json` змінено на диску.
+
+## Гарантії поведінки
+
+- Перехоплює помилки читання/парсингу і не пропускає винятків назовні (fail-safe).
+- За помилок повертає `false`/`null` замість винятку.
+- Ніколи не понижує пін і не чіпає нечислові специфікатори версій.
+
+**Міграція перейменування:** `migrateLegacyPackageKey` переносить legacy-ключ `@nitra/cursor` → `@7n/rules` у devDependencies/dependencies (пін зберігається) перед звичайною ensure/self-upgrade логікою.

package/scripts/docs/hook.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: hook.mjs
+resource: npm/scripts/hook.mjs
+docgen:
+  crc: ea16c864
+  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-rules hook`; повертає Promise<number> (0 — чисто, 1 — невідомий режим, 2 — є порушення).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Не кидає винятків назовні: помилки stdin та parse-помилки повертають null/0.

package/scripts/docs/index.md

@@ -0,0 +1,22 @@
+---
+type: Directory Index
+title: npm/scripts
+resource: npm/scripts/
+---
+
+| Файл                                                                                | Тип       |
+| ----------------------------------------------------------------------------------- | --------- |
+| [auto-rules.mjs](auto-rules.md)                                                     | JS Module |
+| [auto-skills.mjs](auto-skills.md)                                                   | JS Module |
+| [build-agents-commands.mjs](build-agents-commands.md)                               | JS Module |
+| [cli-entry.mjs](cli-entry.md)                                                       | JS Module |
+| [ensure-n-rules-dev-dependencies.mjs](ensure-n-rules-dev-dependencies.md) | JS Module |
+| [hook.mjs](hook.md)                                                                 | JS Module |
+| [post-tool-use-check.mjs](post-tool-use-check.md)                                   | JS Module |
+| [rename-yaml-extensions.mjs](rename-yaml-extensions.md)                             | JS Module |
+| [skills-cli.mjs](skills-cli.md)                                                     | JS Module |
+| [smoke-check-imports.mjs](smoke-check-imports.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 |
+| [update-blue-oak.mjs](update-blue-oak.md)                                           | JS Module |
+| [upgrade-n-rules-and-install.mjs](upgrade-n-rules-and-install.md)         | JS Module |

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

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: post-tool-use-check.mjs
+resource: npm/scripts/post-tool-use-check.mjs
+docgen:
+  crc: 08b09b60
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Цей модуль є PostToolUse hook, який виконує read-only детект конформності всіх активованих правил після кожного редагування файлу (`Edit` / `Write` / `MultiEdit`). Він отримує шлях до файлу з вхідного JSON. Якщо файл відсутній, модуль завершує роботу з кодом 0. Інакше, він запускає детект конформності по всіх правилах, не виконуючи жодних мутацій чи викликів LLM. Код виходу 1 інформує про наявність порушень конформності, хоча PostToolUse не блокує поточний обмін.
+
+## Поведінка
+
+extractFilePath зчитує JSON із вхідного потоку та витягує відносний шлях до файлу, повертаючи його або `null` у разі невалідного JSON чи відсутності поля.
+runPostToolUseCheckCli зчитує вхідні дані, визначає шлях до файлу та виконує перевірку конформності всіх активованих правил, повертаючи код виходу 0, якщо порушень немає, або 1, якщо є порушення конформності.
+
+## Публічний API
+
+extractFilePath — витягує шлях до файлу з вхідних даних JSON, повертаючи `null`, якщо JSON недійсний або поле відсутнє.
+runPostToolUseCheckCli — ініціює перевірку після використання інструменту при запуску з `bin/n-rules.js` з аргументом `post-tool-use-check`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/docs/rename-yaml-extensions.md

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: rename-yaml-extensions.mjs
+resource: npm/scripts/rename-yaml-extensions.mjs
+docgen:
+  crc: 3c59a43f
+---
+
+Цей файл перейменовує розширення файлів YAML у репозиторіях, відповідно до узгоджених правил. Він автоматизує процес зміни розширення файлів `.yml` на `.yaml` для файлів, що відповідають певним шаблонам шляхів, зокрема для маніфестів Kubernetes та workflow-файлів GitHub. Це забезпечує узгодженість форматування YAML у репозиторії.
+
+## Поведінка
+
+- `posixRelFromRoot`: Обчислює відносний шлях від кореня, замінюючи `\` на `/`. Повертає `null`, якщо шлях поза коренем.
+- `pathMatchesK8sYml`: Перевіряє, чи шлях містить сегмент `k8s` та має розширення `.yml`.
+- `pathMatchesGithubYaml`: Перевіряє, чи шлях містить сегмент `.github` та має розширення `.yaml`.
+- `replaceExtension`: Замінює останнє розширення файлу на вказане, додаючи крапку.
+- `collectRenameOps`: Збирає операції перейменування, обходячи репозиторій, ігноруючи `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`.
+- `renameYamlExtensions`: Виконує перейменування, симулюючи або реалізуючи перейменування, на основі правил k8s/github, обходячи вказані каталоги.
+- `parseRenameYamlArgs`: Розбирає аргументи командного рядка `--dry-run` та `--root`.
+
+## Публічний API
+
+- posixRelFromRoot — Повертає відносний шлях від кореня файлової системи, або `null`, якщо шлях знаходиться за межами кореня.
+- pathMatchesK8sYml — Перевіряє, чи відповідає шлях формату YAML-маніфестів Kubernetes.
+- pathMatchesGithubYaml — Перевіряє, чи відповідає шлях формату YAML-файлів `.github`.
+- replaceExtension — Замінює розширення файлу на вказане.
+- renameYamlExtensions — Перейменовує YAML-файли відповідно до правил Kubernetes та `.github`.
+- parseRenameYamlArgs — Розбирає аргументи командного рядка для команди перейменування.
+
+## Гарантії поведінки
+
+- Файл `bin/rename-yaml-extensions.mjs` перейменовує розширення YAML файлів.
+- Перейменування відбувається за двома сценаріями:
+  - Файли з сегментом шляху `k8s` та суфіксом `.yml` перейменовуються на `.yaml`.
+  - Файли з сегментом `.github` та суфіксом `.yaml` перейменовуються на `.yml`.
+- Обхід шляхів: `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next` не обробляються.
+- Аргументи CLI: `--dry-run`, `--root`
+- Повертає `false` у разі невдачі.
+- Не кидає винятків.
+- Не використовує кешування.

package/scripts/docs/skills-cli.md

@@ -0,0 +1,35 @@
+---
+type: JS Module
+title: skills-cli.mjs
+resource: npm/scripts/skills-cli.mjs
+docgen:
+  crc: 5d954e7d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+---
+
+## Огляд
+
+Цей модуль забезпечує керування функціоналом скілів пакета `@7n/rules`. Він каталогізує доступні скіли на основі наявності файлу `SKILL.md` у відповідному пакеті. Для виконання скілу збирається контекст, що включає інструкції скілу та інформацію з конфігураційних файлів проєкту: `package.json`, `tsconfig.json`, `.n-rules.json` та `main.json`. Система дозволяє або вивести список доступних скілів (`npx @7n/rules skill list`), або ініціювати виконання обраного скілу (наприклад, `npx @7n/rules skill pi taze`), з можливістю передачі додаткових аргументів. Пріоритетним механізмом виконання є інтеграція з вбудованим pi-агентом, тоді як для забезпечення сумісності підтримуються застарілі виклики через зовнішні CLI (`cursor`, `claude`).
+
+## Поведінка
+
+Поведінка
+normalizeSkillId знімає префікс `n-` з імені скілу для приведення його до стандартного ID.
+listSkillIds отримує відсортований список ID скілів, які мають файл `SKILL.md` у вказаній директорії скілів.
+buildSkillPrompt збирає комплексний промпт для виконання скілу, об'єднуючи інструкцію скілу з конфігураційними файлами проєкту, такими як `package.json`, `tsconfig.json` та `.n-rules.json`.
+resolveBundledPackageRoot визначає абсолютний шлях до кореня пакету `@7n/rules`, використовуючи інформацію про поточний модуль.
+runSkillsCli виконує логіку командного інтерфейсу для керування скілами: може вивести список доступних скілів, зібрати промпт для скілу або ініціювати його виконання через вбудований pi-агент, використовуючи зовнішні CLI як резервний варіант.
+
+## Публічний API
+
+- normalizeSkillId — знімає префікс `n-` з імені скілу, приводячи його до id каталогу в пакеті.
+- listSkillIds — повертає відсортований список id скілів, що мають `SKILL.md`.
+- buildSkillPrompt — збирає промпт виконання: інструкція скілу + контекст проєкту (`package.json`, `tsconfig.json`, `.n-rules.json`); кидає, якщо скіл невідомий.
+- resolveBundledPackageRoot — абсолютний шлях до кореня встановленого пакета `@7n/rules`.
+- runSkillsCli — асинхронний entrypoint підкоманди `skill`: `list`, друк промпта на stdout, або виконання через `pi` (рекомендовано), `cursor`/`claude` (deprecated). Повертає exit-код.
+
+## Гарантії поведінки
+
+- Сам модуль лише читає файли й збирає промпт; **виконання** делегується агенту: `pi` (вбудований, мутує дерево, запускає bash) або зовнішнім `cursor`/`claude` CLI.
+- Тира моделі для `pi`-runner береться з `main.json.tier` скіла (дефолт `max`).
+- `cursor`/`claude` — deprecated: друкують попередження й лишаються як fallback, доки не налаштовано pi-модель.

package/scripts/docs/smoke-check-imports.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: smoke-check-imports.mjs
+resource: npm/scripts/smoke-check-imports.mjs
+docgen:
+  crc: b262a389
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Скрипт, що запускається після install через `node npm/scripts/smoke-check-imports.mjs`, динамічно імпортує кожен `.mjs`-файл пакету, щоб зловити зламані named exports, які проявляються лише на етапі завантаження модуля. Він працює як post-install smoke-check перед release/publish, свідомо пропускає `node_modules`, є fail-safe і не кидає винятків назовні.
+
+## Поведінка
+
+1. Після install скрипт обходить модулі пакету й відбирає лише `.mjs`-файли з бібліотечних частин, придатні для імпорту без запуску CLI-побічних ефектів.
+2. Свідомо пропускає артефакти й технічні зони на кшталт `node_modules`, щоб перевірка залишалась про реальний код пакету, а не про стороннє чи згенероване.
+3. Динамічно імпортує кожен відібраний модуль окремо, щоб виявити регресії залежностей, які проявляються лише на рівні завантаження модуля.
+4. Фіксує всі помилки імпорту й продовжує перевірку далі, щоб один збій не приховав інші проблемні модулі.
+5. Після завершення показує підсумок: скільки модулів імпортувались успішно, а скільки ні.
+6. Якщо є проблемні модулі, виводить їх список із короткою причиною і завершується з неуспішним статусом; якщо ні — підтверджує, що імпорт проходить чисто.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `node_modules`.

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

@@ -0,0 +1,84 @@
+---
+type: JS Module
+title: sync-claude-config.mjs
+resource: npm/scripts/sync-claude-config.mjs
+docgen:
+  crc: 35cf216c
+  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-rules.json`. Також зливає фрагмент `.gitignore` з канонічного шаблону, додаючи необхідні записи для ADR.
+
+## Поведінка
+
+MANAGED_HOOK_COMMAND_MARKER — Визначає маркер актуальних hook-ів пакета (`hook --post-tool-use`, `hook --stop`).
+LEGACY_POST_TOOL_USE_HOOK_COMMAND_MARKER — Визначає маркер застарілого хука `post-tool-use-check` для cleanup при ресинку.
+LEGACY_POST_TOOL_USE_FIX_HOOK_COMMAND_MARKER — Визначає маркер ще старішої мутуючої команди `post-tool-use-fix` для cleanup при ресинку.
+DOC_FILES_HOOK_COMMAND_MARKER — Визначає маркер для хука `lint-doc-files`.
+LEGACY_DOC_FILES_HOOK_COMMAND_MARKER — Визначає маркер для застарілого хука `doc-files check`.
+LEGACY_STOP_HOOK_COMMAND_MARKER — Визначає маркер для застарілого Stop-hook'а.
+ADR_HOOK_COMMAND_MARKER — Визначає маркер шляху до bash-скрипта ADR capture Stop-hook.
+ADR_NORMALIZE_HOOK_COMMAND_MARKER — Визначає маркер шляху до bash-скрипта ADR normalize Stop-hook.
+CURSOR_ADR_HOOK_COMMAND_MARKER — Визначає маркер шляху до bash-скрипта ADR capture Stop-hook у `.cursor/hooks.json`.
+CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER — Визначає маркер шляху до bash-скрипта ADR normalize Stop-hook у `.cursor/hooks.json`.
+MANAGED_HOOK_COMMAND_MARKERS — Містить список усіх маркерів, що ідентифікують керовані хуки пакета.
+PI_DIR — Визначає кореневу директорію для артефактів pi.dev у проєкті-споживачі.
+PI_EXTENSIONS_DIR — Визначає директорію для TS-extensions pi.dev у проєкті-споживачі.
+PI_TEMPLATE_DIR_NAME — Визначає назву директорії з темплейтом pi-template у пакеті.
+PI_EXTENSION_NAME — Визначає ім'я bundled pi-extension для ADR capture/normalize.
+ADR_GITIGNORE_SNIPPET_REL — Визначає відносний шлях до канонічного фрагмента `.gitignore` для ADR Stop-hook'ів у tarball пакета.
+mergeAllowList — Об'єднує списки дозволених дозволів, зберігаючи користувацькі записи першими.
+mergeHooks — Зливає секцію `hooks` з `.claude/settings.json`, видаляючи керовані групи з існуючої конфігурації.
+mergeSettings — Зливає конфігурацію `.claude/settings.json` з темплейту, зберігаючи користувацькі поля та оновлюючи керовані хуки.
+mergeCursorHooksConfig — Зливає конфігурацію `.cursor/hooks.json`, зберігаючи користувацькі записи та додаючи/видаляючи керовані ADR stop entries.
+syncCursorHooksConfig — Синхронізує `.cursor/hooks.json` для Cursor Agent stop-hooks, додаючи ADR entries за умовою.
+syncClaudeSettings — Синхронізує `.claude/settings.json` за темплейтом, зберігаючи користувацькі налаштування.
+syncAdrHookScript — Копіює канонічний bash-скрипт ADR capture Stop-hook з темплейту пакета у `.claude/hooks/`.
+syncAdrNormalizeHookScript — Копіює канонічний bash-скрипт ADR normalize Stop-hook з темплейту пакета у `.claude/hooks/`.
+syncAdrHookLibScripts — Копіює всі bash-скрипти з `lib/` темплейту у `.claude/hooks/lib/` проєкту.
+removeOrphanAdrHookLib — Видаляє директорію `.claude/hooks/lib/` з проєкту, якщо ADR-хуки вимкнені.
+syncPiExtensions — Копіює bundled pi.dev TS-extension `n-rules-adr` у `.pi/extensions/n-rules-adr/` проєкту.
+removeOrphanPiExtension — Видаляє директорію `.pi/extensions/n-rules-adr/` з проєкту, якщо ADR-хуки вимкнені.
+syncGitignoreAdrFragment — Дописує відсутні рядки з канонічного ADR-фрагмента до кореневого `.gitignore` проєкту.
+syncClaudeCommands — Копіює всі slash-команди з `.claude-template/commands/` у `.claude/commands/` проєкту.
+syncClaudeConfig — Виконує повну синхронізацію Claude Code-конфігу, включаючи ADR-хуки, `.gitignore` та pi-extension, залежно від правил.
+
+## Публічний API
+
+MANAGED_HOOK_COMMAND_MARKER — Позначає актуальні hook-и пакета.
+LEGACY_POST_TOOL_USE_HOOK_COMMAND_MARKER — Позначає застарілий хук `post-tool-use-check`, який прибирається при ресинку.
+LEGACY_POST_TOOL_USE_FIX_HOOK_COMMAND_MARKER — Позначає застарілу мутуючу команду `post-tool-use-fix`, яка прибирається при ресинку.
+DOC_FILES_HOOK_COMMAND_MARKER — Позначає хук для перевірки актуальності файлів документації.
+LEGACY_DOC_FILES_HOOK_COMMAND_MARKER — Позначає старий маркер для очищення хуків документації.
+LEGACY_STOP_HOOK_COMMAND_MARKER — Позначає старий маркер для очищення хука зупинки.
+ADR_HOOK_COMMAND_MARKER — Позначає шлях до скрипта для фіксації рішень ADR.
+ADR_NORMALIZE_HOOK_COMMAND_MARKER — Позначає шлях до скрипта для нормалізації рішень ADR.
+CURSOR_ADR_HOOK_COMMAND_MARKER — Позначає шлях до скрипта фіксації ADR у конфігурації Cursor.
+CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER — Позначає шлях до скрипта нормалізації ADR у конфігурації Cursor.
+MANAGED_HOOK_COMMAND_MARKERS — Групує всі маркери хуків, щоб відрізнити автоматичні записи від користувацьких.
+PI_DIR — Місце зберігання артефактів pi.dev у проєкті.
+PI_EXTENSIONS_DIR — Директорія для TS-розширень pi.dev у проєкті.
+PI_TEMPLATE_DIR_NAME — Назва папки з шаблоном pi у пакеті.
+PI_EXTENSION_NAME — Ім'я пакета pi-розширення для фіксації/нормалізації ADR.
+ADR_GITIGNORE_SNIPPET_REL — Відносний шлях до шаблону `.gitignore` для ADR.
+mergeAllowList — Об'єднує дозволені права доступу, зберігаючи порядок існуючих записів.
+mergeHooks — Об'єднує секцію хуків: видаляє автоматичні записи з існуючої конфігурації та додає записи з шаблону.
+mergeSettings — Створює об'єднаний файл налаштувань.
+mergeCursorHooksConfig — Об'єднує конфігурацію хуків Cursor, зберігаючи користувацькі записи та оновлюючи ADR-записи.
+syncCursorHooksConfig — Синхронізує конфігурацію зупинки для агента Cursor.
+syncClaudeSettings — Копіює налаштування Claude Code з шаблону, зберігаючи користувацькі дані.
+syncAdrHookScript — Копіює канонічний скрипт фіксації рішень ADR.
+syncAdrNormalizeHookScript — Копіює канонічний скрипт нормалізації рішень ADR.
+syncAdrHookLibScripts — Копіює всі допоміжні скрипти з шаблону в проєкт.
+removeOrphanAdrHookLib — Видаляє директорію з допоміжними скриптами ADR, якщо правило ADR вимкнено.
+syncPiExtensions — Копіює TS-розширення pi.dev у проєкт.
+removeOrphanPiExtension — Видаляє директорію з розширення pi, якщо правило ADR вимкнено.
+syncGitignoreAdrFragment — Додає необхідні рядки з канонічного фрагмента `.gitignore` до кореня проєкту.
+syncClaudeCommands — Копіює всі slash-команди з шаблону в директорію команд Claude.
+syncClaudeConfig — Виконує повну синхронізацію конфігурації Claude Code з шаблону.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `.git`.

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

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: sync-setup-bun-deps-action.mjs
+resource: npm/scripts/sync-setup-bun-deps-action.mjs
+docgen:
+  crc: bbd996d1
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Копіює composite GitHub Action `setup-bun-deps` з каталогу `github-actions/setup-bun-deps/` у корені tarball пакету `@7n/rules` у цільовий репозиторій за шлях `.github/actions/setup-bun-deps/action.yml`. Це забезпечує можливість для workflow з правил `ga`, `js` або `text` викликати цей action для налаштування залежностей Bun одразу після виконання `actions/checkout@v6`.
+
+## Поведінка
+
+1. Перевіряє наявність шаблону composite action у корені встановленого пакету `@7n/rules`.
+2. Створює необхідну директорію у корені цільового репозиторію для розміщення composite action.
+3. Зчитує вміст шаблону composite action з кореня встановленого пакету.
+4. Записує вміст шаблону composite action у цільовий шлях у корені репозиторію.
+5. Повертає підтвердження успішного запису та повний шлях до файлу.
+6. Не перевіряє шляхи `.github` чи `.git`.
+
+## Публічний API
+
+syncSetupBunDepsAction — фіксує у `projectRoot` композитну дію, що вказує на корінь встановленого `@7n/rules`.
+
+## Гарантії поведінки
+
+- Свідомо пропускає шляхи: `.github`, `.git`.

package/scripts/docs/update-blue-oak.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: update-blue-oak.mjs
+resource: npm/scripts/update-blue-oak.mjs
+docgen:
+  crc: e11f896a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 95
+---
+
+## Огляд
+
+Оновлює вбудований список ліцензій Blue Oak Council, звертаючись до мережі за даними з https://blueoakcouncil.org/list.json. Цей процес створює або оновлює файл npm/data/blue-oak.json, який містить SPDX-ідентифікатори ліцензій рівнів Model, Gold, Silver та Bronze. Запуск здійснюється вручну у `@7n/rules` за допомогою команди `bun npm/scripts/update-blue-oak.mjs`. Оновлення необхідне при апгрейді @7n/rules, оскільки нові permissive ліцензії з'являються рідко. Lead-рівень (найгірший, GPL-compatible) навмисно виключений.
+
+## Поведінка
+
+1. Завантажує дані з https://blueoakcouncil.org/list.json.
+2. Перевіряє успішність отримання даних. У разі невдачі припиняє виконання.
+3. Парсить отримані дані.
+4. Ітерує по рейтингах у даних.
+5. Вибирає лише рейтинги Model, Gold, Silver та Bronze.
+6. Збирає всі SPDX-ідентифікатори ліцензій, що належать до обраних рейтингів.
+7. Формує об'єкт, що містить версію та список зібраних SPDX-ідентифікаторів.
+8. Зберігає цей об'єкт у файл npm/data/blue-oak.json.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/scripts/docs/upgrade-n-rules-and-install.md

@@ -0,0 +1,36 @@
+---
+type: JS Module
+title: upgrade-n-rules-and-install.mjs
+resource: npm/scripts/upgrade-n-rules-and-install.mjs
+docgen:
+  crc: 715ef559
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Примусове підтягування останньої опублікованої версії інструменту `@7n/rules` з npm registry за адресою https://registry.npmjs.org/@7n/rules/latest для забезпечення коректної роботи системи. Якщо залежність вже визначена в `package.json` через механізми `workspace:`, `file:`, або `link:`, зміна в registry не відбувається і `bun i` не викликається, що зберігає конфігурацію монорепозиторію. Після встановлення виводом повертається шлях до `node_modules/@7n/rules`, якщо каталог з `package.json` існує, або резервний шлях до коріння поточного процесу CLI.
+
+## Поведінка
+
+Поведінка:
+shouldSkipNpmVersionUpgrade визначає, чи слід ігнорувати оновлення версії з npm для залежності, перевіряючи специфікатори, які вказують на локальні або не-npm джерела.
+fetchLatestNRulesVersionFromNpm отримує останню версію пакета `@7n/rules` з URL https://registry.npmjs.org/@7n/rules/latest, аналізуючи вміст res.json.
+resolveInstalledPackageRoot повертає шлях до каталогу `@7n/rules` у `node_modules` або шлях пакета з поточного процесу, якщо перший не знайдений.
+upgradeNRulesToLatestAndBunInstall оновлює залежність `@7n/rules` у `package.json` до останньої версії з npm, виконує `bun i` у корені проєкту, а потім повертає шлях до встановленого пакета. При цьому процес свідомо не перевіряє каталоги `node_modules`.
+
+## Публічний API
+
+shouldSkipNpmVersionUpgrade — Визначає, чи можна замінити поточний специфікатор версії залежності на стандарт `semver` з npm, зберігаючи безпеку.
+fetchLatestNRulesVersionFromNpm — Отримує актуальну версію пакета `@7n/rules` з реєстру npm (через поле `version` у JSON dist-tag `latest`), що доступно на https://registry.npmjs.org/@7n/rules/latest.
+resolveInstalledPackageRoot — Знаходить абсолютний шлях до встановленого пакета у директорії `node_modules`, або надає резервний шлях.
+upgradeNRulesToLatestAndBunInstall — Оновлює `@7n/rules` до останньої версії з npm (якщо це дозволено конфігурацією), виконує встановлення залежностей за допомогою `bun i`, і повертає корінь пакета для подальшої синхронізації конфігураційних файлів, таких як `mdc/`.
+
+## Гарантії поведінки
+
+- Свідомо пропускає шляхи: `node_modules`.
+
+**Міграція перейменування:** `migrateLegacyDependencyName` переносить legacy-ключ `@nitra/cursor` → `@7n/rules` у тій самій секції package.json перед оновленням версії; якщо registry ще не має `@7n/rules` (404 до першої публікації), версія береться з package.json пакету поточного процесу (fallback).