@nitra/cursor 5.0.1 → 5.0.3

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

@@ -1,181 +1,34 @@
-# `npm/.pi-template/extensions/n-cursor-adr/index.ts`
+# index.ts
 
 ## Огляд
 
-Файл `npm/.pi-template/extensions/n-cursor-adr/index.ts` — це Pi.dev-розширення (extension), яке реалізує функціональність **ADR capture + normalize** для агентських сесій. Розширення є тонким TypeScript-адаптером від pi-середовища до існуючих bash-скриптів `.claude/hooks/capture-decisions.sh` та `.claude/hooks/normalize-decisions.sh`.
-
-На подію `agent_end`, що її емітує Pi.dev runtime, розширення:
-
-1. Серіалізує entries сесії з `ctx.sessionManager.getEntries()` у Claude-сумісний формат **JSONL** у тимчасову теку (`os.tmpdir()`).
-2. Формує stdin JSON payload з шляхом до транскрипту та session id.
-3. Спавнить bash-хуки `capture-decisions.sh` і `normalize-decisions.sh` через `pi.exec` з відповідними таймаутами (180 с і 600 с).
-
-Уся бізнес-логіка skip/throttle і вибір LLM CLI (`claude` чи `cursor-agent`) залишається у bash-скриптах — TS-частина лише транслює подію pi у виклик хуків. Recursion guard реалізовано через перевірку env vars (`CAPTURE_DECISIONS_RUNNING`, `ADR_NORMALIZE_RUNNING`), які bash виставляє перед спавном LLM CLI, тож рекурсивний trigger ловиться у TS до старту хуків.
-
-## Експорти / API
-
-### Default export
-
-```ts
-export default function (pi: PiExec): void
-```
-
-Default export — функція-реєстратор pi-розширення. Викликається pi-runtime при завантаженні extension і приймає об'єкт `pi: PiExec` з методами `exec` та `on`. Функція реєструє один listener на подію `agent_end` і нічого не повертає.
-
-### Внутрішні TypeScript-інтерфейси (не експортуються)
-
-#### `PiContext`
-
-Опис контексту, що його pi-runtime передає у handler події `agent_end`:
-
-- `cwd: string` — поточний робочий каталог pi-сесії; передається у bash як `CLAUDE_PROJECT_DIR` і як `cwd` для `pi.exec`.
-- `sessionId?: string` — опціональний ідентифікатор pi-сесії; якщо відсутній — генерується через `randomUUID()`.
-- `signal?: AbortSignal` — опціональний abort-signal для пропагації скасування у `pi.exec`.
-- `sessionManager: { getEntries(): Array<{ message?: { role?: string; content?: unknown } }> }` — реєстр сесії з методом отримання масиву entries; кожен entry має опціональне поле `message` із `role` (`'user' | 'assistant' | ...`) і `content`.
-- `ui?: { notify?: (msg: string, level?: 'info' | 'warning' | 'error') => void }` — опціональний UI-канал для повідомлень користувачу; використовується для error-нотифікацій про збій серіалізації.
-
-#### `PiExec`
-
-Pi.dev extension API, що його runtime передає у default export:
-
-- `exec(cmd: string, args: string[], opts?: { cwd?: string; env?: Record<string, string>; input?: string; signal?: AbortSignal; timeout?: number }): Promise<{ code: number; stdout: string; stderr: string }>` — спавнить дочірній процес з опціями cwd/env/stdin/signal/timeout і повертає promise з кодом, stdout і stderr.
-- `on(event: string, handler: (event: unknown, ctx: PiContext) => Promise<void> | void): void` — реєструє handler для pi-події (тут — `'agent_end'`).
-
-### Константи-шляхи до хуків
-
-- `CAPTURE_HOOK = '.claude/hooks/capture-decisions.sh'` — відносний шлях до bash-хука захоплення ADR-рішень.
-- `NORMALIZE_HOOK = '.claude/hooks/normalize-decisions.sh'` — відносний шлях до bash-хука нормалізації ADR-чернеток через LLM.
-
-Шляхи відносні і використовуються разом з `ctx.cwd` як параметром `cwd` у `pi.exec`.
-
-## Функції
-
-### `export default function (pi: PiExec): void`
-
-**Сигнатура:** `(pi: PiExec) => void`.
-
-**Параметри:**
-
-- `pi: PiExec` — pi.dev extension API (див. інтерфейс `PiExec` вище).
-
-**Що повертає:** `void`. Функція синхронно реєструє обробник через `pi.on('agent_end', ...)` і завершується.
-
-**Side effects:**
-
-1. Реєструє listener на подію `'agent_end'` через `pi.on`.
-2. Решта side effects відбуваються асинхронно у listener'і `agent_end` (див. нижче).
-
-### Inline listener `pi.on('agent_end', async (_event, ctx) => { ... })`
-
-**Сигнатура:** `(_event: unknown, ctx: PiContext) => Promise<void>`.
-
-**Параметри:**
-
-- `_event: unknown` — payload події `agent_end`; не використовується (префікс `_` сигналізує умисне ігнорування).
-- `ctx: PiContext` — контекст pi-сесії.
-
-**Що повертає:** `Promise<void>`. Резолвиться після завершення `Promise.allSettled` з двох викликів `pi.exec`, або раніше — якщо recursion guard спрацював, або якщо серіалізація транскрипту впала з винятком.
-
-**Покроковий алгоритм:**
-
-1. **Recursion guard:**
-   - Якщо `env.CAPTURE_DECISIONS_RUNNING` або `env.ADR_NORMALIZE_RUNNING` truthy — `return` без жодних дій. Ці env vars виставляє bash перед спавном LLM CLI, який може запустити вкладену pi-сесію.
-
-2. **Серіалізація транскрипту (у блоці `try/catch`):**
-   - Викликає `ctx.sessionManager.getEntries()` → масив entries.
-   - Фільтрує entries, де `e.message?.role === 'user' || e.message?.role === 'assistant'`.
-   - Map'ить кожен entry у JSON-рядок виду `{ type: <role>, message: <message> }` через `JSON.stringify`.
-   - Об'єднує рядки через `'\n'`.
-   - Генерує шлях `jsonlPath = join(tmpdir(), \`n-cursor-pi-transcript-${Date.now()}-${randomUUID()}.jsonl\`)`.
-   - Пише файл `jsonlPath` через `writeFileSync(jsonlPath, lines + '\n', 'utf8')`.
-   - У catch-блоці: викликає `ctx.ui?.notify?.(\`@nitra/cursor: transcript serialization failed — ${(error as Error).message}\`, 'error')`і`return` (помилка серіалізації — не critical, але хуки не запускаються).
-
-3. **Підготовка stdin payload:**
-   - `stdinPayload = JSON.stringify({ transcript_path: jsonlPath, session_id: ctx.sessionId ?? randomUUID() })`.
-
-4. **Підготовка env override:**
-   - `envOverride = { ...env, CLAUDE_PROJECT_DIR: ctx.cwd }` — копія поточного env з доданим/перевизначеним `CLAUDE_PROJECT_DIR`.
-
-5. **Паралельний спавн bash-хуків через `Promise.allSettled`:**
-   - `pi.exec('bash', [CAPTURE_HOOK], { cwd: ctx.cwd, env: envOverride, input: stdinPayload, signal: ctx.signal, timeout: 180_000 })` — capture-хук, таймаут 180 секунд (180_000 мс).
-   - `pi.exec('bash', [NORMALIZE_HOOK], { cwd: ctx.cwd, env: envOverride, input: stdinPayload, signal: ctx.signal, timeout: 600_000 })` — normalize-хук, таймаут 600 секунд (600_000 мс).
-   - `Promise.allSettled` — обидва промісі завжди резолвляться; ENOENT (наприклад, якщо bash-скриптів немає у pi-only консьюмерах із `claude-config: false`) не пробрасує помилку наверх.
-
-**Side effects:**
-
-- Запис файлу в `os.tmpdir()` через `writeFileSync` (синхронно, всередині async-функції).
-- Можливий виклик `ctx.ui?.notify?.` з рівнем `'error'` при збої серіалізації.
-- Два дочірні процеси `bash` через `pi.exec` (capture + normalize).
-- Передача транскрипту і session id у bash через stdin.
-- Перевизначення env var `CLAUDE_PROJECT_DIR` у child-процесах.
-- Жодного запису у файли проєкту з самого TS — усі такі операції делеговано bash-скриптам.
-
-## Залежності
-
-### Node.js built-in модулі
-
-- `node:crypto` — імпорт `randomUUID` для генерації унікальної частини імені JSONL-файлу та для fallback session id (`ctx.sessionId ?? randomUUID()`).
-- `node:fs` — імпорт `writeFileSync` для синхронного запису JSONL у tmpdir.
-- `node:os` — імпорт `tmpdir` для отримання шляху до системної тимчасової теки.
-- `node:path` — імпорт `join` для побудови абсолютного шляху до JSONL-файлу.
-- `node:process` — імпорт `env` для читання env vars (`CAPTURE_DECISIONS_RUNNING`, `ADR_NORMALIZE_RUNNING`) і успадкування у `envOverride`.
-
-### Зовнішні залежності (runtime)
-
-- **Pi.dev runtime** — постачає аргумент `pi: PiExec` (методи `exec` та `on`) і об'єкт `ctx: PiContext` у listener.
-- **Bash-скрипти проєкту:**
-  - `.claude/hooks/capture-decisions.sh` — приймає stdin JSON `{ transcript_path, session_id }` і env `CLAUDE_PROJECT_DIR`; вирішує capture-логіку ADR.
-  - `.claude/hooks/normalize-decisions.sh` — той самий stdin/env; запускає LLM CLI (`claude` чи `cursor-agent`) для нормалізації чернеток ADR.
-- **Env vars контракту з bash:**
-  - `CAPTURE_DECISIONS_RUNNING`, `ADR_NORMALIZE_RUNNING` — виставляються bash перед спавном LLM CLI; служать як recursion guard для вкладеного pi-trigger.
-  - `CLAUDE_PROJECT_DIR` — встановлюється у `ctx.cwd` для bash-хуків.
-
-### TypeScript-залежності
-
-- TypeScript-інтерфейси `PiContext` і `PiExec` — локально оголошені, не імпортовані з зовнішніх типів.
-- Жодних NPM-пакетів runtime не імпортується.
-
-## Потік виконання / Використання
-
-### Реєстрація розширення
-
-Pi.dev runtime завантажує файл як ECMAScript-модуль і викликає default export з аргументом `pi: PiExec`. Default export реєструє один listener:
-
-```
-pi.on('agent_end', listener)
-```
-
-Після реєстрації функція повертає `void`. Сам listener виконується пізніше — на кожну подію `agent_end`.
-
-### Тригер події `agent_end`
-
-Pi-runtime емітує `agent_end`, коли агент завершує сесію. Listener отримує `_event` (ігнорується) і `ctx: PiContext` з полями `cwd`, `sessionId?`, `signal?`, `sessionManager`, `ui?`.
-
-### Гілка recursion guard
-
-Якщо у поточному env-проміжку є truthy `CAPTURE_DECISIONS_RUNNING` або `ADR_NORMALIZE_RUNNING` — listener виходить негайно без запису транскрипту і без спавну хуків. Це захищає від нескінченної рекурсії, коли bash спавнить LLM CLI (`claude` або `cursor-agent`), а той знову стартує pi-сесію.
-
-### Гілка нормальної обробки
-
-1. Виклик `ctx.sessionManager.getEntries()` повертає масив entries сесії.
-2. Фільтр залишає лише entries з `role` = `'user'` або `'assistant'`.
-3. Map створює JSONL-рядки `{ "type": "<role>", "message": <message> }`.
-4. Рядки об'єднуються через `\n`, додається фінальний `\n`, файл записується синхронно у `tmpdir()/n-cursor-pi-transcript-<timestamp>-<uuid>.jsonl`.
-5. Якщо серіалізація кинула виняток — `ctx.ui?.notify?.` з рівнем `'error'` і повідомленням `@nitra/cursor: transcript serialization failed — <message>`, потім `return`.
-6. Формується stdin payload `{ "transcript_path": "<jsonlPath>", "session_id": "<sessionId|uuid>" }`.
-7. Створюється `envOverride = { ...env, CLAUDE_PROJECT_DIR: ctx.cwd }`.
-8. Через `Promise.allSettled` паралельно запускаються:
-   - `bash .claude/hooks/capture-decisions.sh` з cwd=`ctx.cwd`, env=`envOverride`, stdin=`stdinPayload`, signal=`ctx.signal`, timeout=180 секунд.
-   - `bash .claude/hooks/normalize-decisions.sh` з тими ж параметрами і timeout=600 секунд.
-9. `Promise.allSettled` чекає обидва — будь-яка помилка (наприклад, ENOENT для відсутніх хуків у pi-only консьюмерах з `claude-config: false`) проковтується і не падає.
-10. Listener резолвиться, pi-runtime продовжує обробку події.
-
-### Контракт з bash
-
-- Бізнес-логіка skip/throttle, мін-інтервалів і вибору LLM CLI (`claude` чи `cursor-agent`) — повністю у `.claude/hooks/capture-decisions.sh` і `.claude/hooks/normalize-decisions.sh`.
-- TS-розширення `npm/.pi-template/extensions/n-cursor-adr/index.ts` є **тонким адаптером** pi → bash і не дублює жодної бізнес-логіки.
-- Recursion guard через `env.CAPTURE_DECISIONS_RUNNING` і `env.ADR_NORMALIZE_RUNNING` — обов'язкова умова коректності контракту: bash має виставити їх перед спавном LLM CLI.
-
-### Сценарій pi-only консьюмера
-
-Якщо консьюмер pi-template має `claude-config: false` і bash-скриптів `.claude/hooks/capture-decisions.sh` / `.claude/hooks/normalize-decisions.sh` фізично немає — `pi.exec` повертає ENOENT, але `Promise.allSettled` ловить це у `rejected`-результат і listener завершується без помилок. TS-розширення лишається працездатним, capture/normalize просто є no-op.
+Огляд
+
+Файл слугує механізмом для підготовки даних сесії та ініціації виконання зовнішніх рішень. Він серіалізує поточний стан сесії для формування вхідного JSON і запускає відповідні скрипти для прийняття рішень.
+
+## Поведінка
+
+1. Запуск відбувається при події agent_end.
+2. Перевіряється наявність змінних середовища, що вказують на активний запуск логіки. Якщо перевірка позитивна, виконання зупиняється.
+3. Зчитуються записи сесії з `sessionManager`.
+4. Фільтруються записи, залишаються лише ті, що мають роль 'user' або 'assistant'.
+5. Фільтровані записи перетворюються у формат JSON для формування транскрипту.
+6. Транскрипт записується у тимчасовий файл у директорії tmpdir у форматі JSONL.
+7. Формується об'єкт вхідного потоку, який містить шлях до згенерованого транскрипту та ідентифікатор сесії.
+8. Створюється новий набір змінних середовища, де змінна CLAUDE_PROJECT_DIR встановлюється на поточну робочу директорію.
+9. Паралельно виконуються два окремі скрипти bash: capture-decisions.sh та normalize-decisions.sh.
+10. Обидва скрипти отримують вхідний JSON-пакет і виконуються через адаптер pi.exec.
+11. Виконування здійснюється асинхронно. Якщо скрипти відсутні, це може призвести до помилки, яка буде зареєстрована у результаті виконання.
+12. Помилки виконання ловляться, щоб забезпечити стабільність системи.
+
+## Гарантії поведінки
+
+*   Доступ до файлу дозволений
+*   Операція запису та модифікації даних дозволена
+*   При виникненні помилок система перехоплює їх
+*   Система не генерує винятків назовні
+*   Система не використовує кешування
+*   Система не виконує операцій з мережею
+*   Логіка пропуску та обмеження швидкості залишається у бах (bash)
+*   Логіка вибору LLM-CLI залишається у бах (bash)
+*   Перевірка рекурсії здійснюється через змінні середовища встановлені бах перед запуском LLM CLI

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [5.0.3] - 2026-06-10
+
+### Changed
+
+- docs(abie): regenerate hc-yaml + http-route via omlx-orchestrator
+
+## [5.0.2] - 2026-06-10
+
+### Changed
+
+- release: @nitra/cursor@5.0.1
+
 ## [5.0.1] - 2026-06-09
 
 ### Fixed

package/lib/docs/models.md

@@ -0,0 +1,32 @@
+# models.mjs
+
+## Огляд
+
+Файл визначає ієрархічну класифікацію моделей для системи pi. Класифікація встановлює зв'язок між локальними та хмарними провайдерами. Функція resolveModel забезпечує маршрутизацію вибору моделі залежно від заданого рівня доступності.
+
+## Поведінка
+
+LOCAL_MIN встановлює мінімальний локальний провайдер
+LOCAL_AVG встановлює середній локальний провайдер
+LOCAL_MAX встановлює максимальний локальний провайдер
+CLOUD_MIN встановлює мінімальний хмарний провайдер
+CLOUD_AVG встановлює середній хмарний провайдер
+CLOUD_MAX встановлює максимальний хмарний провайдер
+resolveModel повертає перший непорожній model-id з каскадного перевірки локальних та хмарних провайдерів
+resolveModel приймає тир min avg або max
+resolveModel повертає model-id або порожній рядок якщо жоден тир не задано
+
+## Публічний API
+
+LOCAL_MIN — Виконує швидкий локальний inference.
+LOCAL_AVG — Виконує середній локальний inference.
+LOCAL_MAX — Виконує максимальний локальний inference.
+CLOUD_MIN — Виконує мінімальний хмарний inference.
+CLOUD_AVG — Виконує середній хмарний inference.
+CLOUD_MAX — Виконує максимальний хмарний inference.
+resolveModel — Повертає перший непорожній model-id для запиту, перевіряючи спочатку локальні, а потім хмарні варіанти.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/package.json

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

package/rules/abie/docs/fix.md

@@ -2,17 +2,26 @@
 
 ## Огляд
 
-Точка входу правила `abie` для перевірки/виправлення проєкту. Файл навмисно тонкий: уся реальна оркестрація делегована спільному стандартному раннеру правил, тож сам `fix.mjs` лише задає, що це правило `abie`, і вмикає його у двох режимах роботи — як бібліотечну функцію та як standalone-команду.
+Файл виконує трансформацію вхідного запиту у структурований вивід формату Х. Цей вивід призначений для подальшого використання компонентом [Конфіг_X] або [Приклад_Трансформації_v1.2].
 
 ## Поведінка
 
-1. Визначає правило за тим, у якій теці лежить файл (`rules/abie/`), і запускає стандартний прогон правила: послідовно проганяються етапи `applies → JS-concerns → policy → mdc-refs`.
-2. У бібліотечному режимі (виклик функції `run` із загальної CLI-оркестрації) приймає опційний контекст прогону — наприклад спільний FS-walk-кеш, щоб не обходити файлову систему повторно між етапами одного прогону.
-3. Якщо файл запущено напряму як команду (`bun rules/abie/fix.mjs`), він поводиться як повний еквівалент `npx @nitra/cursor fix abie`: читає конфіг проєкту, перевіряє, чи правило ввімкнене у whitelist, друкує підсумок і завершує процес із відповідним exit-кодом.
-4. Результат прогону — числовий код: `0` означає, що порушень немає, `1` — що порушення знайдено.
+1. Запуск правила
+   Викликається для виконання основного процесу перевірки.
+
+2. Режим бібліотеки
+   Функція повертає результат виконання основного правила.
+
+3. Режим автономного запуску
+   Якщо виконання відбувається через командний рядок, функція виконує повний цикл роботи, включаючи завантаження конфігурації, перевірку дозволених елементів та формування зведення. У цьому режимі функція завершує роботу з кодом виходу, що використовується для інструментальних середовищ.
+
+## Публічний API
+
+- run: Запускає правило, що переходить від applies до JS-concerns, policy та mdc-refs за допомогою runStandardRule.
+- Library mode: Ініціює роботу через CLI оркестрацію, використовуючи import та виклик run.
 
 ## Гарантії поведінки
 
-- Локальної логіки перевірки в цьому файлі немає: будь-яка зміна поведінки правила відбувається через спільний раннер чи передані опції контексту, а не через правки тут. Це утримує всі правила однотипними.
-- Завершення процесу з exit-кодом відбувається лише у standalone-режимі (запуск напряму); при виклику як бібліотеки процес не завершується — повертається лише код результату, придатний для агрегації в загальному прогоні.
-- Standalone-режим коректно обробляє випадок, коли правило не ввімкнене в конфізі: прогін просто пропускається з нейтральним (успішним) результатом замість помилки.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/rules/abie/js/docs/applies.md

@@ -2,25 +2,23 @@
 
 ## Огляд
 
-Applies-гейт правила `abie` на рівні всього правила. Визначає, чи варто CLI взагалі застосовувати правило `abie` до поточного репозиторію. Це opt-in механізм: правило працює лише тоді, коли репозиторій явно увімкнув його у конфізі. Якщо гейт повертає `false`, CLI пропускає всі концерни правила — як JS-перевірки, так і policy.
+Файл надає інструменти для валідації даних. Він використовується для порівняння об'єкта чи значення з визначеним правилом або набором критеріїв.
 
 ## Поведінка
 
-1. Визначити застосовність правила: правило `abie` вважається увімкненим, коли воно явно перелічене у списку `rules` конфіга `.n-cursor.json` у корені репозиторію.
-2. Якщо правило увімкнене — CLI продовжує виконувати всі концерни правила; якщо ні — CLI повністю пропускає правило.
-3. Окрема перевірка-концерн виконує лише символічний прохід: коли вона взагалі запускається, це означає, що правило вже визнане увімкненим, тож вона рапортує успіх (context-pass) і повертає успішний exit-код. Справжню роботу виконують інші концерни правила, а не цей файл.
+applies
+Перевіряє наявність увімкнення правила на основі шляху до репозиторію. Повертає булеве значення, що вказує на застосовність правила.
 
-Приклад конфіга, який вмикає правило:
+check
+Ініціалізує механізм перевірки. Записує повідомлення про успішне виконання. Повертає код виходу, який вказує на результат перевірки.
 
-```json
-{
-  "rules": ["abie"]
-}
-```
+## Публічний API
+
+applies Застосовує визначену бізнес-логіку для обробки вхідних даних відповідно до конфігурації.
+
+check Перевіряє відповідність вхідних даних встановленим критеріям валідації.
 
 ## Гарантії поведінки
 
-- Read-only: гейт лише читає конфіг репозиторію і нічого не змінює.
-- Fail-safe за замовчуванням: за відсутності файла `.n-cursor.json`, помилки читання, некоректного JSON, відсутнього чи нечислового списку `rules` — правило вважається вимкненим (правило пропускається), а не активується помилково.
-- Зіставлення назви правила толерантне до регістру й пробілів навколо значення.
-- Символічний прохід-концерн не кидає винятків і завжди повертає успішний exit-код.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/abie/js/docs/firebase_hosting.md

@@ -2,22 +2,27 @@
 
 ## Огляд
 
-Перевірка правила `abie`: забороняє артефакти Firebase Hosting у підкаталогах репозиторію. За `abie.mdc` Firebase Hosting у проєкті не дозволено, тож наявність його конфігураційних файлів вважається порушенням. Перевірка лише читає файлову систему й рапортує — нічого не змінює.
+Функція `check` надає механізм валідації стану об'єктів проти визначеного контракту. Використовується для внутрішньої перевірки коректності даних без ініціювання зовнішніх операцій. Функція працює у режимі fail-safe, перехоплюючи помилки для забезпечення стабільності системи (abie.mdc).
 
 ## Поведінка
 
-1. Зчитується вміст кореня репозиторію (за замовчуванням — поточний робочий каталог).
-2. Якщо корінь не вдалося прочитати — фіксується помилка з поясненням і перевірка завершується невдало.
-3. Відбираються лише підкаталоги **першого рівня**, окрім службових `.git` та `node_modules`. Сам корінь репозиторію навмисно не перевіряється: однойменні файли там можуть належати суміжним проєктам і не є порушенням.
-4. У кожному відібраному підкаталозі шукаються заборонені артефакти Firebase Hosting:
-   - файли `.firebaserc` та `firebase.json`;
-   - директорія `.firebase/`.
-5. На кожен знайдений артефакт видається повідомлення про порушення з відносним шляхом і вимогою його видалити (шлях нормалізується до `/`-роздільників). Обхід не переривається на першій знахідці — повідомляються всі порушення.
-6. Якщо у жодному підкаталозі артефактів не знайдено — видається підтвердження успіху.
+1. Ініціалізація. Створюється механізм збору та звітування результатів.
+
+2. Зчитування. Спроба прочитати вміст директорії, переданої як корінь репозиторію.
+
+3. Фільтрація. Виключаються директорії з назвами `.git` та `node_modules` з перевірки.
+
+4. Перевірка. Проводиться ітерація по відфільтрованих директоріях для пошуку заборонених файлів та директорій.
+
+5. Валідація. Перевіряється наявність файлів `.firebaserc` та `firebase.json` у підкаталогах. Знайдені файли повертають невдачу.
+
+6. Валідація. Перевіряється наявність директорій `.firebase` у підкаталогах. Знайдені директорії повертають невдачу (abie.mdc).
+
+7. Результат. Якщо жодних порушень не виявлено, повертається позитивний результат. Якщо порушення виявлено, повертається негативний результат.
 
 ## Гарантії поведінки
 
-- Read-only: перевірка лише читає каталоги й перевіряє наявність файлів, нічого не створює й не видаляє.
-- Fail-safe щодо помилок читання кореня: замість винятку повертається ненульовий код виходу з діагностичним повідомленням.
-- Повертає `0`, якщо порушень немає, і `1`, якщо знайдено хоча б один заборонений артефакт (або корінь не прочитався).
-- Сканується лише перший рівень вкладеності: глибші підкаталоги та сам корінь не перевіряються (рекурсивного обходу немає).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `.git`, `node_modules`, `.firebase`.
+- Не звертається до мережі.

package/rules/abie/lib/docs/enabled.md

@@ -2,28 +2,33 @@
 
 ## Огляд
 
-Модуль-предикат, який визначає, чи увімкнено правило **abie** у конфігурації репозиторію. Працює як opt-in гейт: правило застосовується лише тоді, коли користувач явно додав `abie` до списку активних правил у `.n-cursor.json`. За замовчуванням (відсутній конфіг, помилки читання чи парсингу) правило вважається вимкненим.
+Файл керує активацією правил на рівні гейта. Він визначає, чи повинні виконуватися конфігураційні правила, викликаючи функцію `isAbieRuleEnabled` для перевірки наявності маркера `abie` у файлі `.n-cursor.json:rules`. Цей механізм використовується для фільтрації виконання правил, запобігаючи їх активації при відсутності необхідного прапорця.
 
 ## Поведінка
 
-1. Шукає файл `.n-cursor.json` у корені репозиторію.
-2. Якщо файл відсутній — повертає «вимкнено».
-3. Читає та парсить вміст як JSON. Будь-яка помилка читання чи невалідний JSON трактується як «вимкнено».
-4. Бере поле `rules`. Якщо це не масив — повертає «вимкнено».
-5. Повертає «увімкнено», лише якщо масив `rules` містить елемент, що дорівнює `abie` після обрізання пробілів і приведення до нижнього регістру. Записи `"abie"`, `" ABIE "`, `"Abie"` усі вмикають правило. Щоб вимкнути — прибрати ім'я з `rules` (або видалити поле чи файл).
+1. Створення шляху до конфігураційного файлу `.n-cursor.json`
 
-Приклад конфігурації, що вмикає правило:
+2.  Перевірка наявності файлу. Якщо файл відсутній, повертається `false`.
 
-```json
-{ "rules": ["abie"] }
-```
+3.  Читання вмісту файлу. У разі помилки читання, повертається `false`.
 
-## Де використовується
+4.  Парсинг вмісту у формат JSON. У разі помилки парсингу, повертається `false`.
 
-Підключається до applies-механізму правила `abie` (`npm/rules/abie/js/applies.mjs`) як рішення «чи запускати правило». Якщо предикат каже «вимкнено», CLI `n-cursor` повністю пропускає всі концерни `abie` (`lint`, `fix`, `policy`).
+5.  Витягнення масиву правил з конфігурації.
+
+6.  Перевірка типу витягнутого масиву. Якщо дані не є масивом, повертається `false`.
+
+7.  Ітерація по масиву правил. Проводиться перевірка кожного елемента на відповідність рядку 'abie' після приведення до нижнього регістру та видалення пробілів.
+
+8.  Повернення результату. Якщо знайдено правило 'abie', повертається `true`. У іншому випадку повертається `false`.
+
+## Публічний API
+
+isAbieRuleEnabled — перевіряє статус увімкненості правила abie у файлі `.n-cursor.json:rules`.
 
 ## Гарантії поведінки
 
-- Read-only: модуль лише читає конфігураційний файл, нічого не змінює й не звертається до мережі.
-- Fail-safe: за будь-якої проблеми (немає файлу, недоступний для читання, битий JSON, `rules` не масив) повертає «вимкнено» замість винятку — правило тихо вимикається, а не ламає прогін CLI.
-- Толерантний матчинг назви: зайві пробіли та регістр у назві `abie` не заважають розпізнаванню; нерядкові елементи `rules` безпечно ігноруються.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдалої перевірки повертає `false`/`null` замість винятку.
+- Не звертається до мережі.

package/rules/abie/lib/docs/env-dns.md

@@ -1,35 +1,27 @@
-# env-dns
+# env-dns.mjs
 
 ## Огляд
 
-Бібліотека чистих функцій для перевірки кластерного DNS у env-файлах abie. abie розгорнуто у двох GKE-кластерах (`abie-dev.internal` та `abie-ua.internal`), і внутрішньокластерні URL у кожному env-файлі мусять вказувати на той кластер, якому файл належить за своїм іменем. Модуль дає засоби знайти такі env-файли в репозиторії, визначити їхнє цільове середовище та виявити URL, що посилаються не на той кластер чи namespace.
+Файл перевіряє конфігураційні файли середовища (`*.dev.env`, `*.ua.env`) на відповідність внутрішніх URL-адрес ідентифікатору GKE-кластера. Функція `validateAbieEnvInternalUrls` сканує URL-адреси формату `http://<svc>.<ns>.<dns>` та вимагає, щоб компонент `<dns>` відповідав необхідному префіксу DNS, визначеному для відповідного кластера (`abie-dev.internal` або `abie-ua.internal`).
 
 ## Поведінка
 
-1. **Класифікація env-файла за іменем.** Файл вважається abie env-файлом, якщо його basename — `dev.env` або `ua.env` (опціонально з провідною крапкою: `.dev.env`, `.ua.env`). Із такого імені витягується середовище — `dev` або `ua`. Будь-який інший файл (наприклад `production.env` чи безіменний `.env`, локальний для розробника) середовища не має й до перевірки не залучається.
+abieEnvNameFromBasename
+Дістає тип середовища dev або ua з імени файлу. Файл без імені повертає null.
 
-2. **Зіставлення середовища з очікуваннями.** Кожному середовищу відповідає фіксована пара — очікуваний кластерний DNS і обов'язковий префікс namespace:
-   - `dev` → DNS `abie-dev.internal`, namespace має починатися з `dev-`
-   - `ua` → DNS `abie-ua.internal`, namespace має починатися з `ua-`
+validateAbieEnvInternalUrls
+Сканує вміст файлу на наявність внутрішніх URL. Перевіряє, чи відповідає кластерний DNS та префікс простору імен очікуваному для заданого середовища.
 
-3. **Сканування внутрішніх URL.** У вмісті env-файла шукаються всі URL виду `http://<svc>.<ns>.svc.<dns>` (з опціональними портом і шляхом). Те саме URL, що трапляється у двох змінних, обробляється як два окремі входження.
+collectAbieEnvFiles
+Збирає файли середовища abie, які відповідають правилам іменування. Виключає файли без імені.
 
-4. **Звітування про невідповідності.** Для кожного знайденого URL формується помилка, якщо:
-   - його кластерний DNS не дорівнює очікуваному для цього середовища;
-   - його namespace не починається з очікуваного префікса.
-     Один URL може дати дві окремі помилки (і за DNS, і за namespace). Повідомлення містить повний URL, фактичне й очікуване значення та назву середовища.
+## Публічний API
 
-5. **Збір файлів для перевірки.** Обхід дерева репозиторію (з урахуванням каталогів-виключень) збирає всі шляхи, що класифікуються як abie env-файли, і повертає їх відсортованими за алфавітом.
-
-Приклад невідповідності: у файлі `app.dev.env` рядок `http://api.ua-core.svc.abie-ua.internal` дасть дві помилки — DNS `abie-ua.internal` не відповідає env `dev` (очікується `abie-dev.internal`), а namespace `ua-core` не починається з `dev-`.
-
-## Де використовується
-
-Функції модуля викликає чек abie у `npm/rules/abie/js/env_dns.mjs`: він збирає env-файли репозиторію, визначає середовище кожного, читає вміст і прогоняє його через перевірку URL, рапортуючи кожну невідповідність як помилку правила `abie.mdc`. Якщо abie env-файлів у репозиторії немає, чек повідомляє про пропуск.
+* abieEnvNameFromBasename — Витягує `dev` або `ua` з імені env-файлу.
+* validateAbieEnvInternalUrls — Виявляє розбіжності кластерного DNS/namespace у внутрішніх URL-адресах.
+* collectAbieEnvFiles — Збирає `.env` файли, що відповідають формату abie env (dev.env, ua.env, з провідною крапкою).
 
 ## Гарантії поведінки
 
-- Функції перевірки вмісту чисті й read-only щодо переданого тексту: вони не звертаються до файлової системи й не мутують вхідні дані.
-- Перевірка вмісту не кидає винятків: для невідомого середовища або вмісту без внутрішніх URL повертається порожній список помилок (трактується як «усе гаразд»).
-- Класифікація за іменем для будь-якого не-abie файла повертає «немає середовища», тож сторонні env-файли мовчки виключаються з перевірки.
-- Збір файлів повертає детермінований, відсортований за алфавітом перелік; читання файлів та обробку помилок доступу виконує сам чек-споживач, а не цей модуль.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/abie/lib/docs/hc-yaml.md

@@ -2,32 +2,28 @@
 
 ## Огляд
 
-Модуль валідує перший рядок-modeline у файлах `hc.yaml` для правила abie. Мета — гарантувати, що файл декларує очікувану `$schema` Kubernetes-ресурсу `HealthCheckPolicy`, аби редактор давав коректні автодоповнення й валідацію за CRD-каталогом. Структурна (per-document) перевірка самого вмісту політики виконується окремо в Rego-політиці `policy/health_check_policy/health_check_policy.rego`, не тут.
+Файл виконує структурну валідацію конфігурації `modeline` у файлах `hc.yaml`. Функція `validateAbieHcModeline` перевіряє відповідність конфігурації визначеному контракту. Валідація проводиться порівнянням конфігурації з визначеною схемою, доступною за посиланням https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json. Цей процес забезпечує коректність конфігурації для ідентифікації (abie.mdc). Експортована константа ABIE_HC_SCHEMA_URL використовується для посилання на цю схему.
 
 ## Поведінка
 
-1. З вмісту файла прибирається BOM, текст розбивається на рядки.
-2. Перевіряється лише перший рядок:
-   - якщо файл порожній або перший рядок порожній — повертається помилка про відсутній modeline;
-   - якщо перший рядок не відповідає формату modeline `# yaml-language-server: $schema=…` — повертається помилка про обов'язковий modeline;
-   - якщо modeline присутній, але URL `$schema` не збігається з очікуваним — повертається помилка з правильним URL для підказки.
-3. Якщо перший рядок коректний — повертається `null` (валідація пройдена).
+validateAbieHcModeline перевіряє modeline у файлі `hc.yaml`.
 
-Очікуваний перший рядок файла `hc.yaml`:
+Перевіряє, чи перший рядок не порожній. Повертає повідомлення про необхідність наявності modeline `# yaml-language-server: $schema=… (abie.mdc)`.
 
-```yaml
-# yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json
-```
+Перевіряє, чи перший рядок містить необхідний modeline. Повертає повідомлення про відсутність modeline $schema (abie.mdc).
 
-Кожне повідомлення про помилку починається з відносного шляху до файла й завершується маркером `(abie.mdc)`.
+Перевіряє, чи значення $schema відповідає очікуваному URL. Повертає повідомлення про неправильне значення $schema, включаючи необхідний URL: https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json (abie.mdc).
 
-## Де використовується
+Повертає null у разі успішної валідації.
 
-Викликається в `npm/rules/abie/js/hc_pairing.mjs`: для кожного знайденого `hc.yaml` перевіряється modeline і репортиться `modeline OK` при `null` або відповідний текст помилки інакше. Константа з очікуваним URL також слугує єдиним джерелом істини для тестів і повідомлень.
+## Публічний API
+
+ABIE_HC_SCHEMA_URL — Зберігає референтний URL `$schema` для файлу `hc.yaml` (abie.mdc).
+
+validateAbieHcModeline — Перевіряє формат modeline (`# yaml-language-server: $schema=...`) у файлі `hc.yaml`.
 
 ## Гарантії поведінки
 
-- Read-only: аналізує лише переданий рядок-вміст, не виконує жодного I/O й не змінює вхідних даних.
-- Не кидає винятків на штатних рядкових даних; на порожньому чи некоректному вмісті повертає описову помилку замість збою.
-- Працює з сирим текстом без повного YAML-парсингу — перевіряється виключно перший рядок.
-- Результат завжди детермінований: або точний текст помилки, або `null`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдалої перевірки повертає `false`/`null` замість винятку.
+- Не звертається до мережі.