---
name: docgen
description: >-
  Обходить проєкт і для кожного кодового файлу (js/mjs/ts/vue/py) пише лаконічну поведінкову українську md-документацію у теку docs/ поряд із кодом — диспатчить окремого субагента на кожен файл, за правилами adr/ci4
---

# docgen — генерація документації по файлах

## Мета

Для кожного кодового файлу проєкту створити лаконічну поведінкову `.md`-документацію у теці `docs/`
**поряд із самим файлом** (`<dir>/docs/<stem>.md`). Документацію пише **окремий субагент**
на кожен файл — не один прохід, а батч-диспатч. Джерело правди стилю — правила `adr` і
`ci4` (`docs/explanation`/`docs/adr`-каталоги з тих правил **не застосовуємо** — доку
кладемо локально поряд із кодом).

Документація — **трирівнева**, рівні виконуються строго послідовно:

1. **Tier 1 — файли**: `<dir>/docs/<stem>.md`, субагент на файл (нижче).
2. **Tier 2 — module-summary**: `<module_root>/docs/ARCHITECTURE.md`, субагент на модуль.
3. **Tier 3 — доменні доки**: `docs/<домен>.md` у кореневій `docs/`, субагент-синтезатор
   виділяє бізнес-домени й пише файл на кожен домен.

Агрегат ніколи не випереджає джерело: Tier 2 — лише після завершення всього Tier 1,
Tier 3 — лише після завершення всього Tier 2.

## ⚠️ Паралелізм

Диспатч субагентів — **батчами по 5 одночасно**. Не запускати весь список одразу
(перевантаження). Кожен субагент пише свій окремий файл — спільного стану немає, гонок
за файли немає.

Рівні строго послідовні: Tier 2 стартує лише після завершення всього Tier 1, Tier 3 —
лише після всього Tier 2. Усередині Tier 1 і Tier 2 — батчі по 5. Tier 3 — один субагент.

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

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

## Workflow

### Крок 1: Зібрати список файлів

```bash
npx @nitra/cursor docgen scan
```

Команда друкує JSON-масив об'єктів. Усі шляхи в ньому — відносні до кореня проєкту:

```json
[{ "sourcePath": "src/lib/foo.js", "docPath": "src/lib/docs/foo.md", "exists": false }]
```

Розпарси JSON.

### Крок 2: Відфільтрувати вже описані

За замовчуванням **пропусти** елементи з `"exists": true`. Перегенеровуй їх лише якщо
користувач явно попросив `--overwrite` (тоді обробляй усі). `--overwrite` — **не** прапор
`docgen scan`: scanner лише лістить файли, а рішення «пропустити чи перегенерувати» приймаєш
ти тут, фільтруючи за полем `exists`.

Якщо після фільтра список порожній — зупинись:

```
✓ Усі кодові файли вже мають документацію. Нічого робити.
```

Запам'ятай `total = довжина відфільтрованого списку`.

### Крок 3: Диспатч субагентів батчами по 5

Розбий список на батчі по 5 елементів. Для кожного батчу запусти **до 5 субагентів
одночасно (в одному повідомленні)**, дочекайся завершення батчу, переходь до наступного.

Промпт кожного субагента (підстав `sourcePath` і `docPath`):

```
Напиши лаконічну технічну документацію для одного файлу коду — орієнтовану на поведінку, не реалізацію.

ФАЙЛ-ДЖЕРЕЛО: <sourcePath>
ЗАПИСАТИ В: <docPath>

Кроки:
1. Прочитай файл <sourcePath> повністю.
2. Створи теку для <docPath>, якщо її немає.
3. Запиши markdown-документ у <docPath> за правилами нижче.

Правила документа (за adr/ci4):
- Мова — УКРАЇНСЬКА для всього тексту (заголовки, абзаци, таблиці). Code identifiers,
  шляхи, імена API, команди — лишай як у коді (зазвичай ASCII).
- ЧИСТИЙ Markdown. Жодних HTML-обгорток (<div>/<span>/класів) — токен-ефективність.
- ФОКУС НА ПОВЕДІНЦІ, не реалізації. Пиши ЩО і НАВІЩО, а не як саме це зроблено.
- НЕ перелічуй модулі стандартної бібліотеки (node:fs, node:path, node:crypto, python stdlib
  тощо) — вони не несуть бізнес-значення. Зовнішні залежності (npm-пакети, внутрішні модулі)
  згадуй лише якщо їхня роль не очевидна з контексту.
- НЕ перелічуй внутрішні назви допоміжних функцій/змінних — описуй їхню роль і поведінку.
  Імена публічних exports згадуй лише коли export — справжня точка інтеграції, яку кличуть
  ззовні. Для дрібних/листкових модулів з однією відповідальністю опиши роль поведінково,
  БЕЗ сигнатур, таблиць типів і переліку параметрів — це деталі реалізації.
- Контекстна незалежність: кожна секція самодостатня. Уникай «як вище», «ця функція», «той сервіс».
- Секції (включай лише доречні — порожніх не вигадуй):
  ## Огляд — 1-3 речення: що файл робить і навіщо він існує (роль у системі). Згадай
    ключову семантику, якщо вона визначає сенс файлу (opt-in/gate, кеш, ідемпотентність тощо).
  ## Поведінка — покроковий алгоритм у бізнес-термінах (не деталі реалізації).
    Нумерований список: що відбувається, умови, гілки логіки. Якщо файл керується
    конфігом чи форматом даних — наведи короткий приклад (тільки реальний з коду).
  ## Публічний API — ЛИШЕ якщо модуль має нетривіальну зовнішню поверхню, яку називають
    споживачі. Для кожного export: назва + що робить. Без сигнатур і таблиць типів.
    Не дублюй ## Поведінка. Для модуля з однією функцією-предикатом цю секцію пропусти.
  ## Де використовується — де в системі цей файл вживається (якщо відомо з коду).
  ## Гарантії поведінки — інваріанти й крайові випадки: що гарантовано (read-only,
    не кидає винятків, fail-safe-значення за замовчуванням, безпечна обробка поганих даних)
    і що стається при відсутніх ресурсах чи некоректному вводі. Пропусти, якщо таких гарантій немає.
- Для .vue додай ## Інтерфейс компонента — props (типи, defaults), emits, slots, реактивний стан.
- НЕ вигадуй деталей, яких немає в коді.
- Мета — Behavior Test: читач розуміє, що робить файл і як він вписується в систему,
  без потреби читати реалізацію.

Поверни лише підтвердження, що файл <docPath> записано.
```

### Крок 4: Tier 2 — module-summary

Після завершення **всіх** батчів Tier 1 зібрати список модулів:

```bash
npx @nitra/cursor docgen modules
```

Команда друкує JSON-масив:

```json
[
  {
    "moduleRoot": "/abs/npm/rules/adr",
    "relRoot": "npm/rules/adr",
    "slug": "npm-rules-adr",
    "docPath": "/abs/npm/rules/adr/docs/ARCHITECTURE.md",
    "members": ["npm/rules/adr/index.mjs"],
    "exists": false
  }
]
```

module-summary **завжди регенерується** (це агрегат — поле `exists` ігноруй). Розбий модулі на батчі по 5 і диспатч субагентів. Промпт кожного (підстав `relRoot`, `docPath`, `members`):

```
Напиши module-summary для одного логічного модуля.

МОДУЛЬ: <relRoot>
ЗАПИСАТИ В: <docPath>
ФАЙЛИ МОДУЛЯ (members): <members>

Кроки:
1. Прочитай файлові доки членів модуля. <member> — sourcePath відносно кореня проєкту
   (= поточний CWD); його файлова дока — <CWD>/<dir>/docs/<stem>.md. За потреби зазирни
   в самі файли.
2. Створи теку для <docPath>, якщо її немає.
3. Запиши markdown у <docPath> за тими ж правилами стилю, що й файлова дока
   (українська, чистий Markdown, контекстна незалежність, без HTML).

Секції module-summary:
## Огляд модуля — призначення модуля <relRoot>, його роль у проєкті.
## Ключові файли — список із кліковими посиланнями (відносними до розташування цього
   ARCHITECTURE.md) на члени модуля та їхні файлові доки.
## Публічний API — що модуль експортує назовні.
## Внутрішній потік — як компоненти модуля взаємодіють.
## Підмодулі — вкладені модулі, якщо є.

Поверни лише підтвердження, що файл <docPath> записано.
```

### Крок 5: Tier 3 — доменні доки

Після завершення **всіх** module-summary диспатч **одного** субагента-синтезатора.
У промпт підстав конкретний перелік шляхів module-summary (<module_root>/docs/ARCHITECTURE.md
кожного модуля з виводу `docgen modules`), а не інструкцію їх шукати. Промпт:

```
Синтезуй доменну документацію бізнес-процесів проєкту.

ДЖЕРЕЛА (module-summary, читай усі): <перелік шляхів ARCHITECTURE.md, підставлений вище>

Кроки:
1. Прочитай усі module-summary.
2. Виділи бізнес-домени та процеси (можуть перетинати межі модулів). Доменів може бути багато.
3. Для КОЖНОГО домену запиши окремий файл docs/<домен>.md у кореневій docs/:
   - назва файлу — короткий kebab-slug домену;
   - не перезаписуй файлові доки кореневих файлів у docs/ (напр. app.md, eslint.config.md):
     якщо слаґ домену збігається з іменем такого файлу — додай суфікс -domain
     (напр. app-domain.md). Інакше пиши docs/<домен>.md як є;
   - опиши бізнес-процес домену з кліковими відносними посиланнями на module-summary, конкретні файли й директорії.

Правила стилю — ті ж (українська, чистий Markdown, контекстна незалежність, без HTML).

Поверни перелік створених файлів docs/<домен>.md.
```

### Крок 6: Підсумок

Після всіх батчів виведи:

```
✓ docgen завершено.
Tier 1 (файли): описано <N>, пропущено <S>, помилок <E>.
Tier 2 (модулі): <M> module-summary.
Tier 3 (домени): <D> доменних доків у docs/.
```

Перелічи файли з помилками (субагент впав або не записав `docPath`), якщо такі є.
Помилка одного файлу не зупиняє решту — обробляй усі батчі до кінця.

## Нотатки

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