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

# 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-команді
`doc-files gen`. **Ти не диспатчиш субагентів і не тримаєш сотні файлів у контексті**
— тому навіть масовий перший прогін усього репо не «заморює». Цей скіл **тонкий**: твоє завдання —
запустити генерацію і прочитати підсумок.

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

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

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

## Workflow

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

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

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

- Для дуже великого прогону можна порціями: `--from N --limit M`.
- Перегенерувати **всі** доки (не лише застарілі): `--overwrite`.
- Перегенерувати лише degraded (свіжі за CRC, score < порогу): `--retry-degraded`.

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

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

### Крок 3 (за потреби): перевірка перед завершенням

```bash
npx @nitra/cursor doc-files check --git
```

Перевіряє змінені у задачі джерела (`git diff --name-only HEAD`) проти CRC їхніх док.
Цю ж перевірку виконує **Stop-hook** як твердий гейт: завершити задачу зі застарілими
доками не можна (виняток — масовий прогін понад поріг `N_CURSOR_DOC_FILES_GATE_MAX`, дефолт 50).
Degraded-доки гейт **не** блокує (CRC свіжий); їх список — `doc-files check --degraded`.

## Правила стилю документа (за 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`, за запитом.
- Для наявних док без CRC одноразово: `npx @nitra/cursor doc-files stamp` (штампує frontmatter без LLM).
