---
name: doc-files
description: >-
  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (js/mjs/ts/vue/py) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
version: '1.0'
---

# doc-files — файлова документація (обовʼязковий крок)

## Мета

Для кожного кодового файлу проєкту тримати **актуальну** лаконічну поведінкову `.md`-документацію
у теці `docs/` **поряд із самим файлом** (`<dir>/docs/<stem>.md`). Це **обовʼязковий крок кожної
задачі** — як `lint`: після зміни коду його дока має бути перегенерована.

Застарілість визначається **детерміновано за CRC**: кожна дока несе у frontmatter контрольну
суму байтів джерела на момент генерації. Дока **застаріла**, якщо її немає або
`crc(поточне джерело) ≠ crc у frontmatter`.

```markdown
---
docgen:
  source: src/lib/foo.js
  crc: a3f1c9e0
---

## Огляд

…
```

## Оркестрацію веде JS, не модель; конвеєр — local-only

Уся важка робота — черга, батчинг, виклики LLM і штамп CRC — живе у JS-оркестрації
`lint doc-files`. **Ти не диспатчиш субагентів і не тримаєш сотні файлів у контексті**
— тому навіть масовий перший прогін усього репо не «заморює». Цей скіл **тонкий**: твоє завдання —
запустити генерацію і прочитати підсумок.

Конвеєр **суто локальний** (ADR `260610-2228`): будь-який файл генерується локальною
моделлю (`omlx/…` напряму), хмарних ескалацій немає. Якщо det-оцінка нижча за поріг —
дока все одно пишеться з **degraded-маркером** (`score`/`issues` у frontmatter, CRC свіжий),
а перегенерація таких док — окремою командою пізніше.

## Передумова

- Поточна директорія — корінь проєкту (`requireRoot`), не worktree.
- Доступний `npx @nitra/cursor`.

## Workflow

### Крок 1: Генерація застарілих/відсутніх док

```bash
npx @nitra/cursor lint doc-files
```

Команда запускає doc-files лінтер у fix-режимі (весь репо): перевіряє omlx
(preflight: «сервер лежить» / «модель не влазить у пам'ять зайнятої машини» /
«потрібен API-ключ» → одна зрозуміла зупинка замість лавини «✗») → фільтрує застарілі
(`stale`) → генерує локальною моделлю → пише доку зі **свіжим CRC** (і degraded-маркером,
якщо не дотягнула) → друкує прогрес і підсумок.

### Крок 2: Підтвердження

Дочекайся підсумку `✓ OK: <N>  ⚠ degraded: <D>  ✗ Err: <E>`. Якщо є помилки — перелічи
проблемні файли. Exit-код `1` означає, що хоча б один файл не згенерувався (або не пройшов
preflight). Degraded — не помилка: дока існує, CRC свіжий.

## Правила стилю документа (за adr/ci4)

- Мова — **УКРАЇНСЬКА** для всього тексту. Code identifiers, шляхи, імена API, команди — як у коді.
- **Чистий Markdown.** Жодних HTML-обгорток. Єдиний виняток — машинний `docgen:`-frontmatter із CRC.
- **Фокус на ПОВЕДІНЦІ, не реалізації.** ЩО і НАВІЩО, а не як саме зроблено.
- Не перелічуй модулі стандартної бібліотеки і внутрішні назви допоміжних функцій.
- Кожна секція самодостатня (без «як вище», «ця функція»).
- Секції (лише доречні): `## Огляд`, `## Поведінка`, `## Публічний API`, `## Де використовується`,
  `## Гарантії поведінки`; для `.vue` — `## Інтерфейс компонента`.
- Не вигадуй деталей, яких немає в коді.

## Нотатки

- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
- Scanner ігнорує `node_modules`, `dist`, `.git`, `__pycache__`, `coverage`, `.cursor`, `.claude`,
  усі теки `docs/`, а також `*.test.*` / `*.spec.*` / `*.d.ts`. Кореневий repo `docs/` —
  system-wide only: file-level docs туди не пишуться. Список glob-ів — `docgen-ignore.mjs`.
- Агрегуюча документація (module-summary, доменні доки) — окремий скіл `doc-aggregate`, за запитом.
