@nitra/cursor 12.8.4 → 12.8.6

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

@@ -10,22 +10,22 @@ docgen:
 
 ## Огляд
 
-Модуль ініціалізує та налаштовує середовище для покриття коду, перевіряючи конфігурації, зокрема `mutation.json` та `package.json`. Він створює або оновлює конфігураційні файли Stryker, Vue-макросів та Vitest для кожного знайденого кореневого каталогу JavaScript. Функція `check` виконує перевірку, ігноруючи каталоги `node_modules`. Поведінка модуля фіксується за маркером (test.mdc). Модуль перехоплює помилки (fail-safe) і не кидає винятків назовні.
+Модуль перевіряє готовність JavaScript-проєктів до виконання тестів. Він збирає кореневі каталоги проєктів, використовуючи публічну функцію `check` для валідації. Перевірка гарантує наявність необхідних конфігураційних файлів, зокрема `mutation.json` та `package.json`, у кожному знайденому проєкті. Модуль свідомо пропускає каталоги `node_modules`. Він також додає відповідні артефакти тестів до `.gitignore` у коренях проєктів. (test.mdc)
 
 ## Поведінка
 
 1. Викликається `check` для ініціалізації процесу перевірки.
-2. Перевіряється, чи у конфігурації дозволено перевірку JavaScript. Якщо ні, процес завершується успішно.
-3. Знаходяться всі кореневі каталоги JavaScript у робочому просторі. Якщо їх немає, процес завершується з помилкою.
-4. Перевіряється наявність усіх канонічних базових конфігураційних файлів. Якщо хоча б один відсутній, процес завершується з помилкою.
-5. Для кожного знайденого кореневого каталогу JavaScript:
-    а. Визначається, чи містить цей каталог файли Vue.
-    б. Створюється або оновлюється конфігураційний файл Stryker для цього каталогу. Якщо файл відсутній, він копіюється з канонічного базового файлу, замінюючи ім'я конфігурації Vitest на фактичне ім'я конфігу каталогу. Якщо файл існує, він залишається без змін.
-    в. Якщо каталог містить файли Vue і конфігураційний файл Stryker вже існував, виконується аугментація конфігурації. Це додає локальний плагін Vue-макросів до конфігурації Stryker, якщо він відсутній.
-    г. Створюється або оновлюється конфігураційний файл плагіна Vue-макросів.
-    д. Створюється або оновлюється конфігураційний файл Vitest для каталогу, використовуючи фактичне ім'я конфігу.
-6. Виконується гарантія, що файли з результатами тестів Stryker та покриття (lcov) не потрапляють у систему контролю версій. Якщо додаються нові патерни до `.gitignore`, це фіксується як успіх (test.mdc).
-7. Процес завершується з кодом виходу, що відображає успіх або помилку.
+2. Перевіряється, чи у конфігурації дозволено виконання перевірок для JavaScript. Якщо ні, процес завершується з кодом, що вказує на пропуск.
+3. Збираються всі кореневі каталоги, що містять JavaScript-проєкти. Якщо жоден не знайдено, процес завершується з повідомленням про помилку (test.mdc).
+4. Перевіряється наявність усіх канонічних файлів конфігурації (baseline) у системі. Якщо хоча б один відсутній, процес завершується з повідомленням про помилку.
+5. Для кожного знайденого кореневого каталогу проєкту виконується наступне:
+   а. Визначається, чи містить проєкт файли `.vue`.
+   б. Створюється або оновлюється файл `stryker.config.mjs` у корені проєкту, копіюючи відповідний канонічний baseline. У цьому файлі замінюється посилання на конфігурацію Vitest на фактичне ім'я конфігурації проєкту.
+   в. Якщо проєкт містить файли `.vue` і файл `stryker.config.mjs` вже існував, виконується аугментація цього файлу. Аугментація додає плагін `vue-macros` до конфігурації, якщо він відсутній, зберігаючи при цьому форматування користувача.
+   г. Створюється або оновлюється файл `stryker-vue-macros-ignorer.mjs` у корені проєкту.
+   д. Створюється або оновлюється файл конфігурації Vitest у корені проєкту, використовуючи відповідний канонічний baseline.
+6. Виконується гарантування, що файли, що містять артефакти тестів Stryker та покриття (наприклад, `**/reports/stryker/`, `**/coverage/`), додані до `.gitignore` у корені проєкту. Якщо додано нові записи, виводиться повідомлення (test.mdc).
+7. Процес завершується з кодом, що вказує на успішне виконання або на виявлені порушення.
 
 ## Гарантії поведінки
 

package/rules/test/js/docs/vitest-config-pool-forks.md

@@ -10,16 +10,22 @@ docgen:
 
 ## Огляд
 
-Модуль визначає, чи встановлено режим `pool: 'forks'` у конфігураційному файлі Vitest. Перевірка здійснюється у `vitest.config.mjs` або `vitest.config.js` кореневого репозиторію. Це забезпечує коректну поведінку при паралельному запуску тестових файлів. Результат перевірки фіксується у test.mdc.
+Визначає шлях до конфігураційного файлу Vitest. Перевіряє, чи встановлено в цьому файлі `pool: 'forks'`. (test.mdc)
+
+Поведінка:
+
+- Якщо конфігураційний файл не знайдено, завершує роботу з кодом, що вказує на помилку. (test.mdc)
+- Якщо конфігураційний файл знайдено, але в ньому відсутній ключ `pool: 'forks'`, завершує роботу з кодом, що вказує на помилку. (test.mdc)
+- Якщо конфігураційний файл знайдено і містить `pool: 'forks'`, завершує роботу з кодом 0. (test.mdc)
 
 ## Поведінка
 
-1. Визначається назва конфігураційного файлу Vitest, шукаючи спочатку `vitest.config.mjs`, а потім `vitest.config.js` у корені репозиторію.
-2. Якщо конфігураційний файл відсутній, виконується пропуск перевірки, і повертається код успіху.
-3. Якщо конфігураційний файл знайдено, його вміст зчитується.
-4. Перевіряється, чи містить вміст конфігураційного файлу рядок, що вказує на використання `pool: 'forks'`.
-5. Якщо рядок знайдено, фіксується успіх (test.mdc).
-6. Якщо рядок не знайдено, фіксується помилка (test.mdc), оскільки це необхідно для захисту від гонки у `process.cwd` між паралельними тестовими файлами.
+1. Визначається шлях до файлу конфігурації Vitest, шукаючи спочатку `vitest.config.mjs`, а потім `vitest.config.js` у корені репозиторію.
+2. Якщо конфігураційний файл відсутній, виконується пропуск перевірки, і повертається код виходу 0.
+3. Якщо файл знайдено, його вміст зчитується.
+4. Перевіряється, чи містить вміст конфігураційного файлу рядок, що вказує на встановлення `pool: 'forks'`.
+5. Якщо рядок знайдено, виконується успішне повідомлення (test.mdc).
+6. Якщо рядок не знайдено, виконується повідомлення про помилку (test.mdc), що вказує на необхідність додавання `pool: 'forks'` для захисту від гонки в умовах паралельного виконання тестів.
 7. Функція `check` повертає код виходу, що відображає результат перевірки (0 для успіху/пропуску, 1 для помилки).
 
 ## Публічний API

package/scripts/auto-rules.mjs

@@ -1,7 +1,7 @@
 /**
- * Автовизначення правил для `.n-cursor.json` за meta-даними з `npm/rules/<id>/meta.json`.
+ * Автовизначення правил для `.n-cursor.json` за meta-даними з `npm/rules/<id>/main.json`.
  *
- * Основна роль: `discoverRuleAutoActivation` читає `npm/rules/<id>/meta.json`, виводить
+ * Основна роль: `discoverRuleAutoActivation` читає `npm/rules/<id>/main.json`, виводить
  * `AUTO_RULE_ORDER` (алфавітно) і `AUTO_RULE_DEPENDENCIES` з meta, а потім для кожного правила
  * обчислює spec активації через `specMatches`: `always` — безумовно; `glob` — перевірка
  * файлів через `globToRegex`; `predicate` — незводимий предикат із реєстру `RULE_PREDICATES`
@@ -11,7 +11,7 @@
  *
  * Враховує винятки `disable-rules`: елементи зі списку не додаються автоматично.
  *
- * Автодетект скілів — у `./auto-skills.mjs` (умови — у `npm/skills/<skill>/meta.json`).
+ * Автодетект скілів — у `./auto-skills.mjs` (умови — у `npm/skills/<skill>/main.json`).
  * `mergeConfigWithAutoDetected` нижче приймає вже виявлені rules і skills і вливає
  * їх у конфіг із поправкою на legacy-id (`migrateRuleIds`).
  */
@@ -45,7 +45,7 @@ const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 const RULES_DIR = join(PACKAGE_ROOT, 'rules')
 
 /**
- * Скан `npm/rules/<id>/meta.json` → мапа id → RuleAutoSpec (лише правила з розпізнаним auto).
+ * Скан `npm/rules/<id>/main.json` → мапа id → RuleAutoSpec (лише правила з розпізнаним auto).
  * @param {string} [rulesDir] override для тестів
  * @returns {Record<string, import('./lib/rule-meta.mjs').RuleAutoSpec>} мапа автоактивації
  */
@@ -205,7 +205,7 @@ async function processFileEntry(absPath, root, facts) {
  * Обходить дерево проєкту, збираючи content-факти для предикатів автоувімкнення.
  *
  * `hasRegoFile` і `hasTempoDir` лишаються для зворотної сумісності з прямими читачами
- * фактів (тести, зовнішній код); саме автоувімкнення тепер data-driven через meta.json.
+ * фактів (тести, зовнішній код); саме автоувімкнення тепер data-driven через main.json.
  * @param {string} root абсолютний шлях кореня репозиторію
  * @returns {Promise<{
  *   hasBunSqlImport: boolean,
@@ -350,7 +350,7 @@ function specMatches(spec, ctx) {
 }
 
 /**
- * Визначає авто-правила згідно з `rules/<rule>/meta.json`.
+ * Визначає авто-правила згідно з `rules/<rule>/main.json`.
  * @param {object} params параметри аналізу
  * @param {string} params.root абсолютний шлях до кореня репозиторію
  * @param {string[]} params.availableRules перелік доступних правил з пакету

package/scripts/auto-skills.mjs

@@ -1,7 +1,7 @@
 /**
- * Автовизначення skills для `.n-cursor.json` за умовами з `npm/skills/<skill>/meta.json`.
+ * Автовизначення skills для `.n-cursor.json` за умовами з `npm/skills/<skill>/main.json`.
  *
- * `meta.json` — джерело правди (а не hardcoded мапа). Підтримуються три варіанти:
+ * `main.json` — джерело правди (а не hardcoded мапа). Підтримуються три варіанти:
  *
  *  - `auto: "завжди"` — скіл активується незалежно від інших правил
  *    (приклади: `fix`, `lint`, `llm-patch`, `publish-telegram`).
@@ -26,7 +26,7 @@ const SKILLS_DIR = join(PACKAGE_ROOT, 'skills')
  */
 
 /**
- * Сканує `npm/skills/<id>/meta.json`. Скіли без `meta.json` або без розпізнаного
+ * Сканує `npm/skills/<id>/main.json`. Скіли без `main.json` або без розпізнаного
  * `auto` не потрапляють у результат — їх вмикають лише вручну в конфізі.
  * @param {string} [skillsDir] override для тестів
  * @returns {Record<string, SkillAutoSpec>} мапа `skillId → spec`

package/scripts/docs/auto-rules.md

@@ -3,48 +3,34 @@ type: JS Module
 title: auto-rules.mjs
 resource: npm/scripts/auto-rules.mjs
 docgen:
-  crc: d50b922f
+  crc: ba75c709
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 90
 ---
 
-Файл читає метадані з `npm/rules/<id>/meta.json` для автоматичного визначення порядку та залежностей правил. Він обчислює spec активації для кожного правила, використовуючи дані з `RULE_PREDICATES` з `lib/rule-predicates.mjs`, визначає активні правила, обчислює залежності та об'єднує конфігурацію з виявленими правилами та поправками на legacy-id. Код спирається на конфіги `.n-cursor.json`, `meta.json` та `package.json`.
+## Огляд
 
-## Поведінка
-
-discoverRuleAutoActivation
-Читає meta-дані з файлів npm/rules/<id>/meta.json для визначення автоактивації правил.
-
-AUTO_RULE_ORDER
-Повертає алфавітний порядок для правил.
+Автоматично визначає правила та скіли для конфігурації `.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.
 
-AUTO_RULE_DEPENDENCIES
-Повертає граф залежностей між правилами.
-
-collectAutoRuleFacts
-Збирає контент-факти для предикатів, включаючи сканування GQL, Bun SQL та налаштувань Hasura.
-
-detectAutoRules
-Визначає активні правила на основі spec, перевіряючи їх проти згенерованих фактів.
+## Поведінка
 
-mergeConfigWithAutoDetected
-Доповнює конфігурацію, додаючи визначені автоправила та налаштування, з урахуванням legacy-ID; за наявності `availableRules`/`availableSkills` ще й відсіює з `rules`/`skills` неактуальні id, яких немає у пакеті (повертає їх у полі `pruned`).
+discoverRuleAutoActivation сканує директорію `rules` та виявляє мета-дані для автоматичного визначення правил.
+AUTO_RULE_ORDER надає стабільний алфавітний порядок для всіх правил, виявлених під час автоматичного визначення.
+AUTO_RULE_DEPENDENCIES визначає транзитивні залежності між правилами, виявленими під час автоматичного визначення.
+collectAutoRuleFacts обходить дерево проєкту, збираючи контент-факти про наявність певних структур (наприклад, GQL, Hasura, Rego).
+detectAutoRules визначає список правил, які мають бути активні, на основі мета-даних правил та зібраних контент-фактів, враховуючи виключення.
+mergeConfigWithAutoDetected об'єднує конфігурацію користувача з результатами автоматичного визначення правил та скілів, прибираючи з конфігу ті елементи, яких більше немає у пакеті.
 
 ## Публічний API
 
-discoverRuleAutoActivation — Скан `npm/rules/<id>/meta.json` → мапа id → RuleAutoSpec (лише правила з розпізнаним auto).
-AUTO_RULE_ORDER — Стабільний алфавітний порядок (замість хардкод-масиву).
-AUTO_RULE_DEPENDENCIES — Граф залежностей із meta (Type C) — замість хардкод-константи.
-collectAutoRuleFacts — Обходить дерево проєкту, збираючи content-факти для предикатів автоувімкнення.
-hasRegoFile — Флаг наявності файлу Rego.
-hasTempoDir — Флаг наявності директорії Tempo.
-hasBunSqlImport — Булеве значення про імпорт BunSQL.
-hasGqlTaggedTemplates — Булеве значення про наявність GQL-тегів.
-hasHasuraConfig — Булеве значення про конфігурацію Hasura.
+discoverRuleAutoActivation — Зчитує `main.json` для кожного правила у `npm/rules/<id>/` та створює список правил, які можуть активуватися автоматично.
+AUTO_RULE_ORDER — Визначає порядок застосування автоматичних правил за алфавітом.
+AUTO_RULE_DEPENDENCIES — Створює граф залежностей між автоматичними правилами, використовуючи метадані.
+collectAutoRuleFacts — Сканує структуру проєкту та збирає факти про вміст, необхідні для визначення, які автоматичні правила активувати.
+detectAutoRules — Визначає, які автоматичні правила доступні на основі файлу `main.json` кожного правила.
+mergeConfigWithAutoDetected — Обновлює конфігурацію, додаючи автоматично виявлені правила, і очищає список доступних правил/навичок від тих, що більше не існують у пакеті, фіксуючи видалені ID у полі `pruned`.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Свідомо пропускає шляхи: `.git`, `node_modules`.
-- Не звертається до мережі.

package/scripts/docs/auto-skills.md

@@ -3,175 +3,30 @@ type: JS Module
 title: auto-skills.mjs
 resource: npm/scripts/auto-skills.mjs
 docgen:
-  crc: 44328898
+  crc: 374d78b5
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль `npm/scripts/auto-skills.mjs` відповідає за **автовизначення (auto-activation) скілів** для файлу конфігурації `.n-cursor.json`. Він сканує директорію `npm/skills/` і для кожного скілу читає його `meta.json`, щоб визначити, чи має скіл активуватися автоматично — завжди або лише за наявності певних виявлених auto-правил (rules).
+## Огляд
 
-Ключова ідея модуля: **`meta.json` — єдине джерело правди**. У коді немає жорстко прописаної мапи відповідностей між скілами та правилами; усе зчитується з метаданих скіла. Раніше використовувався hardcoded `AUTO_SKILL_ORDER`, тепер він обчислюється динамічно — експорт залишено для зворотної сумісності.
+Визначає, які скіли мають автоматично активуватися, скануючи `npm/skills/` та аналізуючи `main.json` кожного скілу. Логіка активації базується на конфігурації скілу: скіл може активуватися завжди (`auto: "завжди"`), якщо всі перелічені правила виявлені (`auto: ["rule", …]`), або бути opt-in, якщо поле `auto` відсутнє у `main.json`. Це забезпечує, що визначення автоматичної активації скілів є детермінованим, оскільки `main.json` є джерелом правди. Результати сканування використовуються для встановлення `AUTO_SKILL_ORDER` та `AUTO_SKILL_RULE_DEPENDENCIES`, що впливає на роботу з `.n-cursor.json`.
 
-Підтримуються три формати поля `auto` у `meta.json`:
+## Поведінка
 
-- `auto: "завжди"` — скіл активується незавжди, незалежно від інших правил. Приклади за коментарями у файлі: `fix`, `lint`, `llm-patch`, `publish-telegram`.
-- `auto: ["rule", …]` — скіл активується, якщо **усі** перелічені правила вже виявлено auto-rules-модулем. Приклади за коментарями: `adr-normalize` залежить від `["adr"]`, `taze` — від `["bun"]`.
-- поле `auto` відсутнє або формат не розпізнано — скіл лише opt-in (тільки через `.n-cursor.json:skills`).
+discoverSkillAutoActivation сканує директорію `npm/skills/` і визначає специфікації автоматичної активації скілів на основі вмісту `main.json` кожного скілу.
+AUTO_SKILL_ORDER надає стабільний алфавітний порядок усіх скілів, які мають визначену автоматичну активацію.
+AUTO_SKILL_RULE_DEPENDENCIES надає мапу скілів, які залежать від певних правил, для забезпечення зворотної сумісності.
+detectAutoSkills визначає, які скіли мають бути автоматично активовані, порівнюючи доступні скіли з виявленими правилами та специфікаціями активації.
 
-Сканування `npm/skills/` виконується **синхронно під час завантаження модуля**: це дає детермінізм результату і узгоджується з sync-API сусіднього модуля `auto-rules.mjs`. Результат кешується на час життя процесу (`SKILL_AUTO_ACTIVATION`).
+## Публічний API
 
-## Експорти / API
+discoverSkillAutoActivation — Знаходить скіли, які мають файл `main.json` у відповідній директорії, і які мають автоматичну активацію.
+AUTO_SKILL_ORDER — Забезпечує фіксований алфавітний порядок скілів, що автоматично активуються, для підтримки старої версії.
+AUTO_SKILL_RULE_DEPENDENCIES — Створює список скілів, що автоматично активуються і мають визначені правила залежностей.
+detectAutoSkills — Виявляє скіли, які мають автоматичну активацію на основі вмісту файлу `auto.md` у директорії скілу.
 
-Модуль експортує:
+## Гарантії поведінки
 
-| Символ                                                                 | Тип                                           | Призначення                                                              |
-| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
-| `discoverSkillAutoActivation(skillsDir?)`                              | function                                      | Сканує директорію зі скілами та повертає мапу `skillId → SkillAutoSpec`. |
-| `AUTO_SKILL_ORDER`                                                     | `readonly string[]` (frozen)                  | Стабільний алфавітний список id скілів, які мають авто-активацію.        |
-| `AUTO_SKILL_RULE_DEPENDENCIES`                                         | `Readonly<Record<string, readonly string[]>>` | Лише ті скіли, у яких `auto: [rule, …]` — мапа `skillId → rules[]`.      |
-| `detectAutoSkills({ availableSkills, detectedRules, disableSkills? })` | function                                      | Обчислює фінальний список авто-скілів за станом середовища.              |
-
-Тип `SkillAutoSpec` (визначається JSDoc-typedef):
-
-```js
-/** @typedef {{ always: true } | { rules: readonly string[] }} SkillAutoSpec */
-```
-
-Тобто кожен скіл, що пройшов парсинг, або має `always: true`, або несе масив `rules`.
-
-## Функції
-
-### `discoverSkillAutoActivation(skillsDir = SKILLS_DIR)`
-
-**Сигнатура:**
-
-```js
-function discoverSkillAutoActivation(skillsDir?: string): Record<string, SkillAutoSpec>
-```
-
-**Параметри:**
-
-- `skillsDir` _(string, optional)_ — шлях до директорії зі скілами. За замовчуванням — `SKILLS_DIR = join(PACKAGE_ROOT, 'skills')`, де `PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))` (тобто корінь npm-пакету). Параметр існує для override у тестах.
-
-**Повертає:** `Record<string, SkillAutoSpec>` — мапа `skillId (== ім'я піддиректорії) → spec`.
-
-**Поведінка:**
-
-1. Якщо `skillsDir` не існує — повертається порожній обʼєкт `{}`.
-2. Інакше викликається `readdirSync(skillsDir, { withFileTypes: true })`.
-3. Для кожного запису:
-   - пропускаються файли (не директорії) та все, що починається з `.` (наприклад, приховані).
-   - читається `meta.json` через `readSkillMetaRaw(...)`; якщо raw-обʼєкт відсутній (`null`/`undefined`) — скіл пропускається.
-   - поле `raw.auto` пропускається через `parseSkillAutoSpec(...)`; якщо розпізнано — записується в `out[entry.name]`.
-4. Скіли без розпізнаного `auto` **не потрапляють у результат** — вони можуть бути ввімкнені лише вручну через `.n-cursor.json:skills`.
-
-**Side effects:** sync I/O — `existsSync`, `readdirSync`, читання `meta.json` усередині `readSkillMetaRaw`. Інших побічних ефектів немає.
-
-### `detectAutoSkills({ availableSkills, detectedRules, disableSkills })`
-
-**Сигнатура:**
-
-```js
-function detectAutoSkills(params: {
-  availableSkills: string[],
-  detectedRules: string[],
-  disableSkills?: string[],
-}): { skills: string[] }
-```
-
-**Параметри:**
-
-- `availableSkills` _(string[])_ — перелік id скілів, доступних у поточній збірці пакету (без префіксу `n-`). Будь-який скіл, який є в `SKILL_AUTO_ACTIVATION`, але відсутній у `availableSkills`, **не активується**.
-- `detectedRules` _(string[])_ — id правил, що їх виявив auto-rules-крок; використовується як множина "виявлених" залежностей для специфікацій `{ rules: [...] }`.
-- `disableSkills` _(string[], optional)_ — список id скілів із `.n-cursor.json` із прапором `disable-skills`. За замовчуванням — заморожений пустий масив `DEFAULT_DISABLED_LIST`.
-
-**Повертає:** `{ skills: string[] }` — список id активованих скілів у **стабільному алфавітному порядку** (через `AUTO_SKILL_ORDER.filter(...)`).
-
-**Алгоритм:**
-
-1. Нормалізує `availableSkills` у `Set` (lowercase, trim).
-2. Будує `Set` із `disableSkills` та `detectedRules`.
-3. Для кожної пари `[skillId, spec]` у `SKILL_AUTO_ACTIVATION`:
-   - якщо скіл не входить у `normalizedSkills` або входить у `disableSkillsSet` — пропуск.
-   - якщо `spec` має `always: true` **або** усі `spec.rules` присутні в `detectedRulesSet` — скіл додається до результуючого `detected`.
-4. Фінальний список будується через `AUTO_SKILL_ORDER.filter(id => detected.has(id))`, що гарантує детермінований алфавітний порядок та фільтрацію тільки тих id, які реально мають spec.
-
-**Side effects:** немає — функція чиста. Використовує тільки заздалегідь обчислений `SKILL_AUTO_ACTIVATION` і `AUTO_SKILL_ORDER`.
-
-## Внутрішні константи модуля
-
-- `PACKAGE_ROOT` — корінь npm-пакету: `dirname(dirname(fileURLToPath(import.meta.url)))`. Тобто два рівні вгору від `npm/scripts/auto-skills.mjs` → `npm/`.
-- `SKILLS_DIR` — `join(PACKAGE_ROOT, 'skills')`, тобто `npm/skills/`.
-- `SKILL_AUTO_ACTIVATION` — результат `discoverSkillAutoActivation()` під час імпорту модуля; кеш на час процесу.
-- `AUTO_SKILL_ORDER` — `Object.freeze(Object.keys(SKILL_AUTO_ACTIVATION).toSorted(localeCompare))`. Заморожений алфавітний список усіх скілів з auto-spec.
-- `AUTO_SKILL_RULE_DEPENDENCIES` — `Object.freeze(Object.fromEntries(...))`: похідна view, де лишаються тільки записи зі spec-формою `{ rules }`. Призначена для зворотної сумісності й для автодоку.
-- `DEFAULT_DISABLED_LIST` — `Object.freeze([])`, дефолтне значення для параметра `disableSkills`.
-
-## Залежності
-
-**Node.js стандартні модулі:**
-
-- `node:fs` — `existsSync`, `readdirSync` (синхронне сканування директорії).
-- `node:path` — `dirname`, `join`.
-- `node:url` — `fileURLToPath` (для отримання абсолютного шляху модуля з `import.meta.url`).
-
-**Локальні модулі:**
-
-- `./lib/skill-meta.mjs` — імпортуються:
-  - `readSkillMetaRaw(skillPath)` — читає сирий обʼєкт `meta.json` за шляхом до директорії скілу.
-  - `parseSkillAutoSpec(raw.auto)` — нормалізує значення `auto` у `SkillAutoSpec` (`{ always: true }`, `{ rules: [...] }` або `null`).
-
-**Файлова система (рантайм-залежності):**
-
-- Очікується наявність директорії `npm/skills/` із піддиректоріями `<skillId>/meta.json`. Відсутність директорії оброблена коректно (повертається `{}`).
-
-## Потік виконання / Використання
-
-### Завантаження модуля (init phase)
-
-1. `PACKAGE_ROOT` і `SKILLS_DIR` обчислюються на основі `import.meta.url`.
-2. Викликається `discoverSkillAutoActivation()` — це **синхронне** I/O під час імпорту: читається `npm/skills/`, з кожної піддиректорії — `meta.json`. Результат зберігається у `SKILL_AUTO_ACTIVATION`.
-3. `AUTO_SKILL_ORDER` і `AUTO_SKILL_RULE_DEPENDENCIES` похідні від цього кешу — обчислюються одноразово і заморожуються.
-
-### Виклик `detectAutoSkills` (runtime)
-
-Зазвичай викликається на етапі генерації / валідації `.n-cursor.json`. Послідовність:
-
-1. Зовнішній код визначає `availableSkills` (зі стану пакету / маніфесту) та `detectedRules` (через сусідній auto-rules pipeline).
-2. Опціонально передає `disableSkills` із конфігу користувача.
-3. Функція повертає `{ skills: [...] }` — фінальний відсортований список id, готовий до запису у конфіг.
-
-### Приклад використання
-
-```js
-import { detectAutoSkills, AUTO_SKILL_ORDER, AUTO_SKILL_RULE_DEPENDENCIES } from './auto-skills.mjs'
-
-const { skills } = detectAutoSkills({
-  availableSkills: ['fix', 'lint', 'adr-normalize', 'taze', 'publish-telegram'],
-  detectedRules: ['adr', 'bun'],
-  disableSkills: ['publish-telegram']
-})
-
-// skills буде у стабільному алфавітному порядку:
-// напр. ['adr-normalize', 'fix', 'lint', 'taze']
-// (publish-telegram вимкнено через disableSkills)
-```
-
-### Контракти й інваріанти
-
-- **Детермінізм:** порядок результату повністю визначається `AUTO_SKILL_ORDER`, який є `localeCompare`-сортованим snapshot-ом на момент імпорту.
-- **Безпека до відсутніх скілів:** скіли, доступні у `SKILL_AUTO_ACTIVATION`, але не присутні у `availableSkills`, ніколи не активуються.
-- **Кеш:** перечитати `npm/skills/` без перезавантаження модуля неможливо — функція `discoverSkillAutoActivation` тут лише для прямого виклику з тестів (передаючи інший `skillsDir`).
-- **Опт-аут:** `disableSkills` має пріоритет над `auto`-активацією.
-
-## Rebuild Test
-
-Уявімо, що файл загублено. За цим описом його можна відновити так:
-
-1. ESM-модуль із Node-імпортами `existsSync, readdirSync` із `node:fs`, `dirname, join` із `node:path`, `fileURLToPath` із `node:url`.
-2. Імпорт `parseSkillAutoSpec, readSkillMetaRaw` із `./lib/skill-meta.mjs`.
-3. Константи `PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))`, `SKILLS_DIR = join(PACKAGE_ROOT, 'skills')`.
-4. Експортована функція `discoverSkillAutoActivation(skillsDir = SKILLS_DIR)`: якщо `!existsSync(skillsDir)` → `{}`; інакше readdirSync з `withFileTypes`, ітерувати, пропускати не-директорії та `name.startsWith('.')`, читати `readSkillMetaRaw(join(skillsDir, entry.name))`, пропускати falsy, парсити `parseSkillAutoSpec(raw.auto)`, додавати в `out[entry.name]` тільки якщо парсер повернув spec.
-5. Константа модуля `SKILL_AUTO_ACTIVATION = discoverSkillAutoActivation()`.
-6. Експорт `AUTO_SKILL_ORDER = Object.freeze(Object.keys(SKILL_AUTO_ACTIVATION).toSorted((a,b) => a.localeCompare(b)))`.
-7. Експорт `AUTO_SKILL_RULE_DEPENDENCIES = Object.freeze(Object.fromEntries(Object.entries(SKILL_AUTO_ACTIVATION).filter(([, spec]) => 'rules' in spec).map(([id, spec]) => [id, spec.rules])))`.
-8. Константа `DEFAULT_DISABLED_LIST = Object.freeze([])`.
-9. Експортована функція `detectAutoSkills({ availableSkills, detectedRules, disableSkills = DEFAULT_DISABLED_LIST })`: побудувати `normalizedSkills = new Set(availableSkills.map(s => s.trim().toLowerCase()))`, `disableSkillsSet`, `detectedRulesSet`; пройти `Object.entries(SKILL_AUTO_ACTIVATION)`, пропустити коли скіл не у `normalizedSkills` або у `disableSkillsSet`, інакше додати до `detected` якщо `'always' in spec` або `spec.rules.every(d => detectedRulesSet.has(d))`; повернути `{ skills: AUTO_SKILL_ORDER.filter(id => detected.has(id)) }`.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

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

@@ -10,19 +10,20 @@ docgen:
 
 ## Огляд
 
-Копіює composite GitHub Action `setup-bun-deps` з каталогу `github-actions/setup-bun-deps/` у цільовий репозиторій (`.github/actions/setup-bun-deps/`). Це забезпечує можливість робочим процесам з правил `ga`, `js` та `text` викликати локально розміщений action (`uses: ./.github/actions/setup-bun-deps`) одразу після виконання `actions/checkout@v6`, використовуючи CLI `npx \@nitra/cursor`.
+Копіює 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`.
 
 ## Поведінка
 
 1. Перевіряє наявність шаблону composite action у корені встановленого пакету `@nitra/cursor`.
-2. Створює необхідну директорію для composite action у корені цільового репозиторію, ігноруючи шляхи `.github` та `.git`.
-3. Зчитує вміст шаблону composite action.
-4. Записує вміст шаблону у цільовий шлях composite action у корені цільового репозиторію, гарантуючи наявність завершального символу нового рядка.
+2. Створює необхідну директорію у корені цільового репозиторію для розміщення composite action.
+3. Зчитує вміст шаблону composite action з кореня встановленого пакету.
+4. Записує вміст шаблону composite action у цільовий шлях у корені репозиторію.
 5. Повертає підтвердження успішного запису та повний шлях до файлу.
+6. Не перевіряє шляхи `.github` чи `.git`.
 
 ## Публічний API
 
-syncSetupBunDepsAction — фіксує в `projectRoot` композитну дію з коренем встановленого `@nitra/cursor`.
+syncSetupBunDepsAction — фіксує у `projectRoot` композитну дію, що вказує на корінь встановленого `@nitra/cursor`.
 
 ## Гарантії поведінки