@nitra/cursor 5.1.0 → 5.2.1

package/skills/{docgen → doc-files}/js/docgen-prompts.mjs

@@ -8,7 +8,11 @@ export const STYLE = [
   'Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.'
 ].join(' ')
 
-/** Окремий блок інструкцій з анкорами — підставляється коли вони є. */
+/**
+ * Окремий блок інструкцій з анкорами — підставляється коли вони є.
+ * @param {object|null} anchors анкори файлу (або null)
+ * @returns {string} текстовий блок для system-промпта або порожній рядок
+ */
 function anchorsBlock(anchors) {
   if (!anchors) return ''
   const txt = anchorsToPrompt(anchors)
@@ -35,6 +39,12 @@ function factsSummary(facts) {
   return lines.join('\n')
 }
 
+/**
+ * Пара system+user messages для одного виклику.
+ * @param {string} system system-промпт
+ * @param {string} user user-промпт
+ * @returns {Array<{role:string, content:string}>} messages-масив
+ */
 const msgs = (system, user) => [
   { role: 'system', content: system },
   { role: 'user', content: user }
@@ -42,67 +52,83 @@ const msgs = (system, user) => [
 
 /**
  * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
- * Код потрапляє лише в `behavior`; решта секцій — на факт-листі.
+ * Код потрапляє лише в `behavior`; «Огляд» генерується окремо ОСТАННІМ
+ * (`overviewMessages`) з уже написаної Поведінки — тут його немає.
  * @param {object} facts факт-лист про файл
  * @param {string} src вміст файлу
- * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів
+ * @param {object|null} [anchors] анкори файлу для обовʼязкового включення
+ * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів (behavior[, api])
  */
 export function sectionMessages(facts, src, anchors = null) {
   const factsTxt = factsSummary(facts)
   const anch = anchorsBlock(anchors)
   const multi = (facts.exports?.length || 0) > 1
-  const out = []
-
-  // Огляд — лише факти (без коду)
-  out.push({
-    key: 'overview',
-    numPredict: 220,
-    messages: msgs(
-      `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
-      'Напиши вміст секції «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Без заголовка, без переліку функцій. Заборонені generic-фрази типу «забезпечує перевірку», «виконує валідацію» — пиши КОНКРЕТНО що саме і за яким контрактом.'
-    )
-  })
 
-  // Поведінка — ЄДИНА секція, якій потрібен код
-  out.push({
+  // R6: Поведінка описує РІВНО експортовані імена, не службові помічники
+  const exportNames = (facts.exports ?? []).map(e => e.name)
+  const behaviorTask = multi
+    ? 'для кожної публічної функції — один короткий пункт «що вона робить»'
+    : 'нумерований алгоритм у бізнес-термінах'
+  const onlyExports = exportNames.length
+    ? ` Описуй РІВНО ці публічні імена і жодних інших: ${exportNames.join(', ')}.`
+    : ''
+  const noInternal = facts.internalSymbols?.length
+    ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.`
+    : ''
+  const behavior = {
     key: 'behavior',
     numPredict: 500,
     messages: msgs(
       `${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
-      `Напиши вміст секції «Поведінка»: ${multi ? 'для кожної публічної функції — один короткий пункт «що вона робить»' : 'нумерований алгоритм у бізнес-термінах'}. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${facts.internalSymbols?.length ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.` : ''} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
+      `Напиши вміст секції «Поведінка»: ${behaviorTask}.${onlyExports} Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${noInternal} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
     )
-  })
+  }
 
   // API — лише список експортів (без коду)
-  if (multi || facts.exports?.some(e => e.desc)) {
-    const list = facts.exports.map(e => `- ${e.name}: ${e.desc || '(сформулюй стисло з наміру файлу)'}`).join('\n')
-    out.push({
-      key: 'api',
-      numPredict: 320,
-      messages: msgs(
-        `${STYLE}${anch}`,
-        `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка. Без generic-фраз «застосовує логіку», «перевіряє коректність» — пиши конкретно ЩО саме застосовує/перевіряє.`
-      )
-    })
+  if (!multi && !facts.exports?.some(e => e.desc)) return [behavior]
+  const list = facts.exports.map(e => `- ${e.name}: ${e.desc || '(сформулюй стисло з наміру файлу)'}`).join('\n')
+  const api = {
+    key: 'api',
+    numPredict: 320,
+    messages: msgs(
+      `${STYLE}${anch}`,
+      `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка. Без generic-фраз «застосовує логіку», «перевіряє коректність» — пиши конкретно ЩО саме застосовує/перевіряє.`
+    )
   }
+  return [behavior, api]
+}
 
-  return out
+/**
+ * R3 — «Огляд» ОСТАННІМ: узагальнення вже написаної Поведінки, а не здогад із
+ * голого факт-листа. Лікує generic/хибний Огляд на складних файлах.
+ * @param {object} facts факт-лист про файл
+ * @param {string} behaviorText готовий текст секції «Поведінка»
+ * @param {object|null} [anchors] анкори файлу
+ * @returns {Array<{role:string,content:string}>} messages-масив для Огляду
+ */
+export function overviewMessages(facts, behaviorText, anchors = null) {
+  const factsTxt = factsSummary(facts)
+  const anch = anchorsBlock(anchors)
+  return msgs(
+    `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
+    `На основі вже написаної секції «Поведінка» (нижче) напиши «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Узагальнюй САМЕ описану поведінку, не додавай нових фактів. Без заголовка, без переліку функцій. Заборонені абстрактні формули без конкретики («перевірка/валідація/обробка даних», «відповідність контракту», «застосовує логіку») — пиши, ЩО саме і за яким контрактом.\n\nПОВЕДІНКА:\n${behaviorText}`
+  )
 }
 
 /**
  * E2-step 1 — критик. Перевіряє чорнетку секції на конкретні дефекти.
  * Повертає messages для LLM-запиту: вихід має бути СПИСКОМ issues або словом NONE.
- * @param {'overview'|'behavior'|'api'} sectionKey
+ * @param {'overview'|'behavior'|'api'} sectionKey ключ секції
  * @param {string} draft вже згенерована чорнетка секції
  * @param {object} facts факт-лист
- * @param {ReturnType<import('./docgen-extract-anchors.mjs').extractAnchors>} anchors
- * @returns {Array<{role:string,content:string}>}
+ * @param {ReturnType<import('./docgen-extract-anchors.mjs').extractAnchors>} anchors анкори файлу
+ * @returns {Array<{role:string,content:string}>} messages-масив для критика
  */
 export function criticMessages(sectionKey, draft, facts, anchors) {
   const anch = anchorsBlock(anchors)
   const criteria = [
     'generic-фрази без конкретики («забезпечує перевірку», «виконує валідацію», «застосовує логіку»)',
-    'пропущені обов\'язкові АНКОРИ з контексту (URLs, magic-string constants, error-маркери, конфіги, code-приклади)',
+    "пропущені обов'язкові АНКОРИ з контексту (URLs, magic-string constants, error-маркери, конфіги, code-приклади)",
     'граматичні помилки українською («перед їх застосування», «моделіне», англіцизми як «applys», «moduleline»)',
     'h1/h2/h3 підзаголовки всередині секції — їх не повинно бути',
     'дослівна копія JSDoc-сигнатури або параметрів у дужках',
@@ -122,12 +148,12 @@ export function criticMessages(sectionKey, draft, facts, anchors) {
 
 /**
  * E2-step 2 — refine. Переписує чорнетку, виправляючи перелічені issues.
- * @param {'overview'|'behavior'|'api'} sectionKey
- * @param {string} draft
+ * @param {'overview'|'behavior'|'api'} sectionKey ключ секції
+ * @param {string} draft чорнетка секції
  * @param {string} issues список issues від critic
- * @param {object} facts
- * @param {ReturnType<import('./docgen-extract-anchors.mjs').extractAnchors>} anchors
- * @returns {Array<{role:string,content:string}>}
+ * @param {object} facts факт-лист
+ * @param {ReturnType<import('./docgen-extract-anchors.mjs').extractAnchors>} anchors анкори файлу
+ * @returns {Array<{role:string,content:string}>} messages-масив для переписування
  */
 export function refineMessages(sectionKey, draft, issues, facts, anchors) {
   const anch = anchorsBlock(anchors)
@@ -146,7 +172,7 @@ export function refineMessages(sectionKey, draft, issues, facts, anchors) {
 /**
  * E3 — детермінований шаблон секції «Гарантії поведінки» з facts.markers.
  * НЕ використовує LLM: 0 запитів, 0 галюцинацій, 0 generic-фраз.
- * @param {object} facts
+ * @param {object} facts факт-лист
  * @returns {string} текст секції (без `## Гарантії` — це додає assemble())
  */
 export function guaranteesFromMarkers(facts) {
@@ -177,14 +203,3 @@ export function oneShotMessages(facts, src) {
     `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``
   )
 }
-
-/**
- * Лише текст user-промпту для one-shot (для хмарного fallback через Anthropic SDK).
- * @param {object} facts факт-лист про файл
- * @param {string} src вміст файлу
- * @returns {string} plain-text user-prompt
- */
-export function oneShotPromptText(facts, src) {
-  const multi = (facts.exports?.length || 0) > 1
-  return `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``
-}

package/skills/doc-files/js/docgen-scan.mjs

@@ -0,0 +1,298 @@
+/** @see ./docs/docgen-scan.md */
+// eslint-disable-next-line unicorn/import-style
+import path from 'node:path'
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { once } from 'node:events'
+import { env } from 'node:process'
+
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { isDocgenIgnored } from './docgen-ignore.mjs'
+import { QUALITY_THRESHOLD, readDocQuality, staleness } from './docgen-crc.mjs'
+
+/** Кодові розширення, для яких генеруємо документацію. */
+const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py'])
+
+/** `*.test.*`, `*.spec.*` — тести, документувати не треба. */
+const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u
+
+/** Поріг великого прогону для Stop-гейта: більше stale-файлів — не блокуємо. */
+const DEFAULT_GATE_MAX = Number(env.N_CURSOR_DOC_FILES_GATE_MAX ?? 50) || 50
+
+/**
+ * Чи корінь має system-wide docs layout.
+ * Такий корінь зарезервований під репозиторні docs/adr, docs/explanation тощо,
+ * тому file-level docs у нього не пишемо.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {boolean} true — корінь system-wide docs
+ */
+function isSystemWideDocsRoot(root) {
+  return existsSync(path.join(root, 'docs', 'adr')) || existsSync(path.join(root, 'docs', 'explanation'))
+}
+
+/**
+ * Чи є файл кодовим джерелом для документування.
+ * @param {string} fileName базове ім'я файлу
+ * @returns {boolean} true — документуємо; false — пропускаємо
+ */
+export function isSourceFile(fileName) {
+  if (fileName.endsWith('.d.ts')) return false
+  if (TEST_FILE_RE.test(fileName)) return false
+  return SOURCE_EXTENSIONS.has(path.extname(fileName))
+}
+
+/**
+ * Обчислює шлях md-документа для кодового файлу: тека `docs/` поряд із джерелом.
+ * Якщо `sourcePath` відносний, `docPath` теж відносний; якщо абсолютний — абсолютний.
+ * @param {string} sourcePath шлях до джерела (відносний або абсолютний)
+ * @returns {string} шлях до `<dir>/docs/<stem>.md` у тому ж просторі шляхів
+ */
+export function docPathForSource(sourcePath) {
+  const dir = path.dirname(sourcePath)
+  const stem = path.basename(sourcePath, path.extname(sourcePath))
+  return path.join(dir, 'docs', `${stem}.md`)
+}
+
+/**
+ * Чи кодовий файл `relPath` (posix, від кореня) підлягає документуванню:
+ * правильне розширення, не тест, не в ignore-дереві, не кореневий system-wide docs.
+ * @param {string} root абсолютний корінь
+ * @param {string} relPath posix-шлях файлу від кореня
+ * @returns {boolean} true — кандидат на доку
+ */
+export function isDocCandidate(root, relPath) {
+  const fileName = path.posix.basename(relPath)
+  if (!isSourceFile(fileName)) return false
+  if (isSystemWideDocsRoot(root) && path.posix.dirname(relPath) === '.') return false
+  return !isDocgenIgnored(relPath)
+}
+
+/**
+ * Описує один кодовий файл: шлях джерела, шлях доки, стан застарілості за CRC.
+ * @param {string} root абсолютний корінь
+ * @param {string} sourcePath posix-шлях джерела від кореня
+ * @returns {{sourcePath:string, docPath:string, stale:boolean, reason:'missing'|'crc-mismatch'|null}} опис файлу
+ */
+export function describeFile(root, sourcePath) {
+  const docPath = docPathForSource(sourcePath)
+  const { stale, reason } = staleness(path.join(root, sourcePath), path.join(root, docPath))
+  return { sourcePath, docPath, stale, reason }
+}
+
+/**
+ * Рекурсивно обходить дерево від `root`, повертає кодові файли зі станом застарілості.
+ * Синхронний `readdirSync` — детермінований порядок без гонок; обсяг дерева це дозволяє.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {Array<{sourcePath:string, docPath:string, stale:boolean, reason:'missing'|'crc-mismatch'|null}>} кандидати з відносними шляхами
+ */
+export function scanForDocFiles(root) {
+  const results = []
+
+  /** @param {string} dir поточний каталог обходу */
+  function walk(dir) {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+      const relPath = path.relative(root, fullPath)
+      if (entry.isDirectory()) {
+        if (isDocgenIgnored(relPath, 'dir')) continue
+        walk(fullPath)
+      } else if (entry.isFile() && isSourceFile(entry.name)) {
+        if (isSystemWideDocsRoot(root) && path.dirname(relPath) === '.') continue
+        const sourcePath = relPath.split(path.sep).join('/')
+        if (isDocgenIgnored(sourcePath)) continue
+        results.push(describeFile(root, sourcePath))
+      }
+    }
+  }
+
+  walk(root)
+  return results
+}
+
+/**
+ * Парсить `--root <dir>` з argv; default — cwd.
+ * @param {string[]} argv аргументи після підкоманди
+ * @returns {string} абсолютний корінь
+ */
+export function resolveRoot(argv) {
+  const i = argv.indexOf('--root')
+  return i !== -1 && argv[i + 1] ? path.resolve(argv[i + 1]) : process.cwd()
+}
+
+/**
+ * Сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
+ * Рішення «генерувати лише stale чи всі» приймає скіл, фільтруючи поле `stale`.
+ * @param {string[]} argv аргументи після назви субкоманди
+ * @returns {number} exit-код: 0 — успіх, 1 — корінь не існує
+ */
+export function runDocFilesScanCli(argv) {
+  const root = resolveRoot(argv)
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    console.error(`doc-files scan: корінь не існує або не є директорією: ${root}`)
+    return 1
+  }
+  console.log(JSON.stringify(scanForDocFiles(root), null, 2))
+  return 0
+}
+
+/**
+ * Зчитує stdin до EOF як utf8 рядок. На TTY — повертає `''` одразу.
+ * @returns {Promise<string>} вміст stdin
+ */
+async function readStdin() {
+  if (process.stdin.isTTY) return ''
+  process.stdin.setEncoding('utf8')
+  const chunks = []
+  process.stdin.on('data', chunk => chunks.push(chunk))
+  try {
+    await once(process.stdin, 'end')
+  } catch {
+    // 'error' на stdin — повертаємо те, що встигли зібрати
+  }
+  return chunks.join('')
+}
+
+/**
+ * Дістає `tool_input.file_path` зі stdin JSON Claude Code PostToolUse hook.
+ * @param {string} stdinJson сирий вміст stdin
+ * @returns {string|null} відносний шлях або null
+ */
+function extractHookFilePath(stdinJson) {
+  if (!stdinJson) return null
+  try {
+    const fp = JSON.parse(stdinJson)?.tool_input?.file_path
+    return typeof fp === 'string' && fp !== '' ? fp : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Список змінених у задачі джерел — найшвидший спосіб: `git diff --name-only HEAD`
+ * (working-tree проти HEAD). Допускаємо неповне покриття (закомічене в межах задачі
+ * випадає) — це свідомий компроміс; CRC лишається джерелом правди про застарілість.
+ * @param {string} root абсолютний корінь
+ * @returns {string[]} posix-шляхи кодових файлів-кандидатів, що існують
+ */
+function gitChangedSources(root) {
+  let out
+  try {
+    out = execFileSync('git', ['diff', '--name-only', 'HEAD'], { cwd: root, encoding: 'utf8' })
+  } catch {
+    return []
+  }
+  return out
+    .split('\n')
+    .map(s => s.trim())
+    .filter(rel => rel && isDocCandidate(root, rel) && existsSync(path.join(root, rel)))
+}
+
+/**
+ * Нормалізує абсолютний/відносний шлях до posix-шляху від кореня (або null поза деревом).
+ * @param {string} root абсолютний корінь
+ * @param {string} candidate шлях-кандидат
+ * @returns {string|null} posix-шлях від кореня
+ */
+function toRelSource(root, candidate) {
+  const rel = path.relative(root, path.resolve(root, candidate))
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return null
+  return rel.split(path.sep).join('/')
+}
+
+/**
+ * `doc-files check --degraded` — інформаційний список свіжих за CRC док зі
+ * `score < QUALITY_THRESHOLD` (локальний конвеєр не дотягнув; ADR 260610-2228).
+ * Не блокує (exit 0): degraded — борг для `gen --retry-degraded`, а не гейт.
+ * @param {string} root абсолютний корінь
+ * @returns {number} exit-код: завжди 0
+ */
+function runDegradedReport(root) {
+  const degraded = []
+  for (const f of scanForDocFiles(root)) {
+    if (f.stale) continue
+    const { score, issues } = readDocQuality(path.join(root, f.docPath))
+    if (score !== null && score < QUALITY_THRESHOLD) degraded.push({ ...f, score, issues })
+  }
+  if (degraded.length === 0) {
+    console.log(`✓ doc-files: degraded-док немає (поріг ${QUALITY_THRESHOLD}).`)
+    return 0
+  }
+  const list = degraded
+    .map(f => {
+      const issuesTxt = f.issues.length ? ': ' + f.issues.join(',') : ''
+      return `  - ${f.sourcePath} (score=${f.score}${issuesTxt})`
+    })
+    .join('\n')
+  console.log(
+    `⚠ doc-files: degraded-док ${degraded.length} (score < ${QUALITY_THRESHOLD}):\n${list}\n→ перегенеруй: npx @nitra/cursor doc-files gen --retry-degraded`
+  )
+  return 0
+}
+
+/**
+ * `doc-files check` — детермінований детектор застарілості для hook'ів і CLI.
+ *
+ * Режими:
+ * - `--hook`     — PostToolUse: бере `file_path` зі stdin JSON, перевіряє один файл.
+ * - `--git`      — Stop-гейт: перевіряє `git diff --name-only HEAD`. Поріг `--max N`
+ *                  (default 50): якщо stale більше — не блокуємо (exit 0 + попередження).
+ * - `--degraded` — інформаційний звіт по доках зі score нижче порогу (exit 0).
+ * - `<paths…>`   — явні шляхи-джерела.
+ *
+ * Exit 2 (стале знайдено) — для hook'а це блок/нагадування Claude; exit 0 — все свіже
+ * або великий прогін понад поріг.
+ * @param {string[]} argv аргументи після назви субкоманди
+ * @returns {Promise<number>} exit-код (0 / 2)
+ */
+export async function runDocFilesCheckCli(argv) {
+  const root = resolveRoot(argv)
+  if (argv.includes('--degraded')) return runDegradedReport(root)
+  const hookMode = argv.includes('--hook')
+  const gitMode = argv.includes('--git')
+  const maxIdx = argv.indexOf('--max')
+  const gateMax = maxIdx !== -1 && argv[maxIdx + 1] ? Number(argv[maxIdx + 1]) || DEFAULT_GATE_MAX : DEFAULT_GATE_MAX
+
+  let sources
+  if (hookMode) {
+    const fp = extractHookFilePath(await readStdin())
+    const rel = fp ? toRelSource(root, fp) : null
+    sources = rel && isDocCandidate(root, rel) && existsSync(path.join(root, rel)) ? [rel] : []
+  } else if (gitMode) {
+    sources = gitChangedSources(root)
+  } else {
+    sources = argv
+      .filter(a => !a.startsWith('--') && a !== argv[maxIdx + 1])
+      .map(a => toRelSource(root, a))
+      .filter(rel => rel && isDocCandidate(root, rel) && existsSync(path.join(root, rel)))
+  }
+
+  const stale = sources.map(src => describeFile(root, src)).filter(f => f.stale)
+  if (stale.length === 0) return 0
+
+  // Великий прогін: Stop-гейт не блокує, лише попереджає (захист від нескінченного блоку).
+  if (gitMode && stale.length > gateMax) {
+    console.error(
+      `⚠ doc-files: застарілих док ${stale.length} (> ${gateMax}) — гейт не блокує. Запусти масовий прогін:\n  npx @nitra/cursor doc-files gen`
+    )
+    return 0
+  }
+
+  const list = stale.map(f => `  - ${f.sourcePath} (${f.reason})`).join('\n')
+  console.error(
+    `✗ doc-files: документація застаріла/відсутня для ${stale.length} файл(ів):\n${list}\n→ перегенеруй: /doc-files`
+  )
+  return 2
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Прямий запуск: `node skills/doc-files/js/docgen-scan.mjs [scan|check] [args]`
+  const [sub, ...rest] = process.argv.slice(2)
+  const argv = sub === 'scan' || sub === 'check' ? rest : process.argv.slice(2)
+  process.exitCode = sub === 'check' ? await runDocFilesCheckCli(argv) : runDocFilesScanCli(argv)
+}

package/skills/doc-files/js/docs/docgen-crc.md

@@ -0,0 +1,32 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-crc.mjs
+  crc: 54e8e12b
+---
+
+# docgen-crc
+
+## Огляд
+
+Детермінований маркер актуальності файлових док: контрольна сума джерела у frontmatter плюс опційний degraded-маркер якості. Єдине джерело правди про «дока свіжа/застаріла/неякісна» для генерації, перевірок і хуків.
+
+## Поведінка
+
+1. Контрольна сума обчислюється з байтів джерела і записується у машинний frontmatter доки разом зі шляхом джерела; розбіжність суми з поточним джерелом (або відсутність доки) означає застарілість.
+2. Якщо генерація не дотягнула до порогу якості, frontmatter додатково несе оцінку (`score`) і коди проблем (`issues`); коди нормалізуються до YAML-безпечних (без пробілів, обмежена кількість), а старі доки без цих полів лишаються валідними.
+3. Поріг degraded — `70`, override через `N_CURSOR_DOC_FILES_THRESHOLD`.
+4. Перештампування знімає наявний frontmatter і ставить свіжий, не торкаючись тіла документа; якість при цьому передається явно — без неї поля якості зникають.
+
+## Публічний API
+
+- `crc32` — контрольна сума вмісту в hex.
+- `staleness` — стан доки відносно джерела: `missing` / `crc-mismatch` / свіжа.
+- `parseDocFrontmatter` / `buildDocFrontmatter` / `stampDoc` — читання і (пере)штампування машинного блока.
+- `readDocCrc` / `readDocQuality` — точкове читання суми та якості з доки.
+- `QUALITY_THRESHOLD` — чинний поріг degraded.
+
+## Гарантії поведінки
+
+- Сума не залежить від git-стану: rebase, гілки й незакомічені зміни на неї не впливають.
+- Frontmatter — єдиний машинний виняток із правила «чистий Markdown»; тіло доки модуль не редагує.
+- Відсутні поля якості читаються як «не оцінено» (`score: null`), а не як нуль.

package/skills/doc-files/js/docs/docgen-extract-anchors.md

@@ -0,0 +1,27 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-extract-anchors.mjs
+  crc: e80e0827
+---
+
+# docgen-extract-anchors
+
+## Огляд
+
+Детермінований витяг «анкорів» — конкретних фрагментів коду, які модель зобов'язана згадати в документації, щоб не зісковзнути на generic-фрази. Анкори підставляються у промпти окремим блоком обов'язкового включення, а їх покриття перевіряється скорером.
+
+## Поведінка
+
+1. З тексту джерела збираються п'ять категорій анкорів: усі URL; експортовані константи-рядки з непорожнім значенням; маркери повідомлень про помилки виду `(rule.mdc)`; посилання на json-конфіги проєкту; code-block-приклади з провідного коментаря файлу (де автор зазвичай показує контракт).
+2. Кожна категорія дедуплікується зі збереженням порядку появи.
+3. Для промпта анкори форматуються в компактний текстовий блок з інструкціями, де саме їх згадати; якщо анкорів немає взагалі — блок не додається, щоб не вводити модель в оману «обов'язковими» полями.
+
+## Публічний API
+
+- `extractAnchors` — текст джерела → категоризовані анкори.
+- `anchorsToPrompt` — анкори → текстовий блок для system-промпта або порожній рядок.
+
+## Гарантії поведінки
+
+- Повністю детермінований і read-only; жодних LLM-викликів і мережі.
+- Працює по сирому тексту без AST: дешево і свідомо толерує надлишок (зайвий анкор — менша проблема, ніж пропущений).

package/skills/doc-files/js/docs/docgen-extract.md

@@ -0,0 +1,29 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-extract.mjs
+  crc: 26bb2901
+---
+
+# docgen-extract
+
+## Огляд
+
+Детермінований екстрактор фактів про кодовий файл (нуль токенів): з тексту джерела збирається факт-лист, на якому конвеєр будує промпти, маркери поведінки й список заборонених до згадки внутрішніх імен.
+
+## Поведінка
+
+1. Провідний блок-коментар файлу (до першого коду) стає «наміром файлу»; з документувальних коментарів перед кожним експортом витягуються опис, параметри та опис повернення, відкидаючи беззмістовні заглушки.
+2. Збираються всі експортовані оголошення з безпосередньо передуючими їм коментарями.
+3. Імпорти класифікуються на stdlib / npm / внутрішні; імена символів, імпортованих із внутрішніх модулів, складають список internalSymbols — модель не має згадувати їх у доці, а скорер штрафує за витік.
+4. Маркери поведінки визначаються евристиками по тексту: read-only (немає запису у файлову систему), перехоплення помилок, повернення false/null при невдачі, звертання до мережі, кешування, свідомі пропуски шляхів.
+5. Для розширень поза js/mjs/ts повертається позначка unsupported — конвеєр переходить на one-shot-шлях.
+
+## Публічний API
+
+- `extractFacts` — головна точка: текст джерела + шлях → факт-лист `{header, exports, imports, internalSymbols, markers}` або `{unsupported: true}`.
+
+## Гарантії поведінки
+
+- Повністю детермінований: однаковий вхід → однаковий факт-лист; жодних LLM-викликів і мережі.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Евристики свідомо толерують надлишок (зайвий маркер — менша проблема, ніж пропущений).

package/skills/doc-files/js/docs/docgen-files-batch.md

@@ -0,0 +1,25 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-files-batch.mjs
+  crc: 20a14675
+---
+
+# docgen-files-batch
+
+## Огляд
+
+CLI-оркестратор масової генерації файлових док (`doc-files gen` / `doc-files stamp`): черга, вибір цілей, preflight локального сервера, запис док зі свіжою контрольною сумою і degraded-маркером. Уся важка робота живе тут, а не в контексті агента.
+
+## Поведінка
+
+1. Дерево проєкту сканується, цілі обираються за режимом: за замовчуванням — застарілі доки; `--overwrite` — усі; `--retry-degraded` — свіжі за сумою, але з оцінкою нижче порогу. Зріз великого прогону — `--from N --limit M`.
+2. Перед генерацією — preflight локального сервера: «сервер лежить», «модель не влазить у пам'ять зайнятої машини» чи «потрібен API-ключ» зупиняють прогін одним зрозумілим повідомленням замість лавини помилок по файлах.
+3. Кожна ціль генерується локальним конвеєром; дока пишеться поряд із джерелом у `docs/` зі свіжою сумою. Якщо оцінка нижча за поріг — у frontmatter додаються оцінка й коди проблем, файл рахується як degraded.
+4. Підсумок: кількість успішних, degraded і помилкових файлів; за наявності degraded — підказка про `--retry-degraded`. Помилка хоча б одного файлу → exit-код `1`.
+5. `stamp` детерміновано перештамповує frontmatter у наявних доках без LLM (міграція док без суми), зберігаючи наявні поля якості.
+
+## Гарантії поведінки
+
+- Жодних хмарних викликів: збій локальної генерації стає помилкою чи degraded-маркером, а не ескалацією.
+- Доки пишуться атомарно по файлу: успішні цілі не відкочуються через подальші збої.
+- Прогін ніколи не комітить — рішення про фіксацію приймає користувач.

package/skills/doc-files/js/docs/docgen-gen.md

@@ -0,0 +1,30 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-gen.mjs
+  crc: 2d6e5f79
+---
+
+# docgen-gen
+
+## Огляд
+
+Генератор однієї файлової доки local-only конвеєра: файл → українська поведінкова md-документація локальною моделлю, з детермінованим скорингом і позначкою degraded замість будь-яких хмарних ескалацій.
+
+## Поведінка
+
+1. З джерела детерміновано витягуються факти (намір файлу, експорти, маркери поведінки) та анкори (URL, константи, маркери помилок, конфіги, приклади з header-коментаря) — без жодного токена.
+2. Для підтримуваних структур документ збирається посекційно окремими викликами моделі: «Огляд» — лише з фактів, «Поведінка» — єдина секція з кодом у вікні, «Публічний API» — зі списку експортів; «Гарантії поведінки» — детермінований шаблон із маркерів без LLM. Для непідтримуваних структур (`vue`/`py` до появи юніт-шару) — один виклик на весь документ без скорингу.
+3. Чорнетки секцій проходять детермінований пост-лінт (зрізання сигнатур, обгорток, випадкових заголовків); найвразливіші секції — один цикл критика-редактора.
+4. Зібраний документ оцінюється детермінованим скорером (наявність огляду, змістовність поведінки, галюцинація кешу, витік внутрішніх імен). Якщо оцінка нижча за поріг — один повторний прогін з вищою температурою, перемагає кращий за оцінкою (вимикається `N_CURSOR_DOCGEN_BEST_OF=0`).
+5. Результат повертається з оцінкою, списком проблем і прапором degraded; рішення про повторну генерацію приймає batch-обгортка або користувач — конвеєр ніколи не звертається до хмари.
+
+## Публічний API
+
+- `generateDoc` — головна точка: шлях файлу → `{ md, ms, score, issues, degraded, model }`.
+- `DEFAULT_LOCAL_MODEL` — модель конвеєра: `N_CURSOR_DOCGEN_MODEL` → каскад локальних тирів → локальний omlx-дефолт напряму.
+
+## Гарантії поведінки
+
+- Local-only: жодних хмарних викликів і pre-route за складністю — будь-який файл генерується локальною моделлю.
+- Скоринг і пост-лінт детерміновані: однаковий вхід → однакова оцінка.
+- Помилка транспорту прокидається назовні — не маскується під degraded.