@nitra/cursor 5.0.3 → 5.2.0

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

@@ -19,9 +19,13 @@ const EXPORT_CONST_RE = /export\s+const\s+([A-Z][A-Z0-9_]+)\s*=\s*(['"`])([^'"`]
 const ERROR_MARKER_RE = /\(([a-z][\w-]*\.mdc)\)/g
 const CONFIG_REF_RE = /\b(\.[a-z][\w.-]*\.json)\b/gi
 const FILE_HEADER_RE = /^\s*\/\*\*([\s\S]*?)\*\//
-const CODE_BLOCK_RE = /```[a-z]*\n([\s\S]*?)\n\s*\*?\s*```/g
+const CODE_BLOCK_RE = /```[a-z]{0,12}\n([\s\S]*?)\n[ \t]{0,8}\*?[ \t]{0,8}```/g
 
-/** Dedup масив, зберігаючи порядок появи. */
+/**
+ * Dedup масив, зберігаючи порядок появи.
+ * @param {Array<string>} arr вхідний масив
+ * @returns {Array<string>} масив без дублікатів у вихідному порядку
+ */
 function uniq(arr) {
   const seen = new Set()
   const out = []
@@ -36,17 +40,17 @@ function uniq(arr) {
 
 /**
  * Витягує анкори з вихідного коду файла.
- * @param {string} src
+ * @param {string} src вміст файлу
  * @returns {{
  *   urls: string[],
  *   magicStrings: Array<{name:string, value:string}>,
  *   errorMarkers: string[],
  *   configRefs: string[],
  *   examples: string[]
- * }}
+ * }} категоризовані анкори файлу
  */
 export function extractAnchors(src) {
-  const urls = uniq([...src.matchAll(URL_RE)].map(m => m[0]))
+  const urls = uniq(Array.from(src.matchAll(URL_RE), m => m[0]))
 
   const magicStrings = []
   const seenNames = new Set()
@@ -59,12 +63,12 @@ export function extractAnchors(src) {
     }
   }
 
-  const errorMarkers = uniq([...src.matchAll(ERROR_MARKER_RE)].map(m => m[1]))
-  const configRefs = uniq([...src.matchAll(CONFIG_REF_RE)].map(m => m[1]))
+  const errorMarkers = uniq(Array.from(src.matchAll(ERROR_MARKER_RE), m => m[1]))
+  const configRefs = uniq(Array.from(src.matchAll(CONFIG_REF_RE), m => m[1]))
 
   // Витягуємо code-block приклади тільки з file-header — там автор зазвичай показує контракт.
   const headerMatch = src.match(FILE_HEADER_RE)
-  const examples = headerMatch ? uniq([...headerMatch[1].matchAll(CODE_BLOCK_RE)].map(m => m[1].trim())) : []
+  const examples = headerMatch ? uniq(Array.from(headerMatch[1].matchAll(CODE_BLOCK_RE), m => m[1].trim())) : []
 
   return { urls, magicStrings, errorMarkers, configRefs, examples }
 }
@@ -73,20 +77,25 @@ export function extractAnchors(src) {
  * Форматує анкори у компактний текст для system-промпта.
  * Якщо анкорів немає взагалі — повертає порожній рядок (системний блок про
  * анкори не додається, щоб не вводити LLM в оману «обовʼязковими» полями).
- * @param {ReturnType<typeof extractAnchors>} a
- * @returns {string}
+ * @param {ReturnType<typeof extractAnchors>} a анкори файлу
+ * @returns {string} компактний текстовий блок або порожній рядок
  */
 export function anchorsToPrompt(a) {
   const blocks = []
   if (a.urls.length) blocks.push(`URLs (згадай у тексті): ${a.urls.join(', ')}`)
   if (a.magicStrings.length) {
-    blocks.push(
-      `Експортовані константи-рядки (наведи назву і призначення): ${a.magicStrings.map(s => `${s.name}=${JSON.stringify(s.value)}`).join('; ')}`
-    )
+    const consts = a.magicStrings.map(s => s.name + '=' + JSON.stringify(s.value)).join('; ')
+    blocks.push(`Експортовані константи-рядки (наведи назву і призначення): ${consts}`)
+  }
+  if (a.errorMarkers.length) {
+    const markers = a.errorMarkers.map(m => '(' + m + ')').join(', ')
+    blocks.push(`Маркери повідомлень (згадай у Поведінці): ${markers}`)
   }
-  if (a.errorMarkers.length) blocks.push(`Маркери повідомлень (згадай у Поведінці): ${a.errorMarkers.map(m => `(${m})`).join(', ')}`)
   if (a.configRefs.length) blocks.push(`Конфіги, на які спирається код: ${a.configRefs.join(', ')}`)
-  if (a.examples.length) blocks.push(`Приклади з документації автора (наведи дослівно у Поведінці):\n${a.examples.map(e => '```\n' + e + '\n```').join('\n')}`)
+  if (a.examples.length) {
+    const fenced = a.examples.map(e => '```\n' + e + '\n```').join('\n')
+    blocks.push(`Приклади з документації автора (наведи дослівно у Поведінці):\n${fenced}`)
+  }
   if (!blocks.length) return ''
   return `АНКОРИ ДО ОБОВ'ЯЗКОВОГО ВКЛЮЧЕННЯ:\n${blocks.join('\n')}`
 }

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

@@ -25,15 +25,17 @@ const BUILTIN_MODULES = new Set([
 const JSDOC_OPEN_RE = /^\s*\/\*\*?/
 const JSDOC_CLOSE_RE = /\*\/\s*$/
 const STAR_PREFIX_RE = /^\s*\*?\s?/
-const PARAM_LINE_RE = /^@param\s+(?:\{[^}]*\}\s+)?\[?([A-Za-z0-9_.]+)\]?\s*(.*)$/
-const RETURNS_LINE_RE = /^@returns?\s+(?:\{[^}]*\}\s+)?(.*)$/
+const PARAM_LINE_RE = /^@param[ \t]{1,8}(?:\{[^}]{0,200}\}[ \t]{1,8})?\[?([\w.]{1,80})\]?[ \t]{0,8}(.{0,400})$/
+const RETURNS_LINE_RE = /^@returns?[ \t]{1,8}(?:\{[^}]{0,200}\}[ \t]{1,8})?(.{0,400})$/
 const FILE_HEADER_RE = /^\s*\/\*\*([\s\S]*?)\*\//
 const PRECEDING_JSDOC_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
-const EXPORT_DECL_RE = /export\s+(?:async\s+)?(function|const|class)\s+([A-Za-z0-9_]+)/g
-const IMPORT_FROM_RE = /^import\s+[\s\S]*?from\s+['"]([^'"]+)['"]/gm
+const EXPORT_DECL_RE = /export\s+(?:async\s+)?(function|const|class)\s+(\w+)/g
+const IMPORT_FROM_RE = /^import[ \t]{1,8}[\s\S]{0,300}?from\s{1,8}['"]([^'"]+)['"]/gm
 const NODE_PREFIX_RE = /^node:/
-const INTERNAL_IMPORT_RE = /import\s+(?:([A-Za-z0-9_$]+)\s*,?\s*)?(?:\{([^}]+)\})?\s+from\s+['"](\.[^'"]+)['"]/g
-const IMPORT_AS_RE = /\s+as\s+.*/
+const INTERNAL_IMPORT_RE = /import[ \t]{1,8}([^'"]{0,300}?)from[ \t]{1,8}['"]\.[^'"]{1,300}['"]/g
+const NAMED_BRACES_RE = /\{([^}]{1,400})\}/
+const IDENT_RE = /^[\w$]{1,80}$/
+const IMPORT_AS_RE = /[ \t]{1,8}as[ \t]{1,8}.{0,200}/
 const WRITE_FS_RE = /\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/
 const CATCH_RE = /catch\s*\(/
 const TRY_RE = /\btry\s*\{/
@@ -152,12 +154,16 @@ function extractImports(src) {
 function extractInternalSymbols(src) {
   const out = new Set()
   for (const m of src.matchAll(INTERNAL_IMPORT_RE)) {
-    if (m[1]) out.add(m[1].trim())
-    if (m[2])
-      for (const n of m[2].split(',')) {
+    const clause = m[1]
+    const named = clause.match(NAMED_BRACES_RE)
+    if (named) {
+      for (const n of named[1].split(',')) {
         const name = n.replace(IMPORT_AS_RE, '').trim()
         if (name) out.add(name)
       }
+    }
+    const defName = clause.replace(NAMED_BRACES_RE, '').replaceAll(',', ' ').trim().split(' ')[0]
+    if (defName && IDENT_RE.test(defName)) out.add(defName)
   }
   return [...out]
 }

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

@@ -0,0 +1,181 @@
+/**
+ * JS-оркестрація генерації файлових док (local-only, ADR 260610-2228).
+ *
+ * Уся черга/батчинг/CRC-штамп живуть тут, а не в контексті моделі — тому
+ * масовий перший прогін на сотні файлів не «заморює» агента. Конвеєр суто
+ * локальний: жодних cloud-ескалацій; якщо det-score нижче порогу — дока все
+ * одно пишеться з degraded-маркером (`score`/`issues` у frontmatter), а
+ * `gen --retry-degraded` адресно переганяє лише такі доки пізніше.
+ *
+ * Перед масовим прогоном — health-check omlx: memory-guard зайнятої 8GB машини
+ * означає «відклади прогін», а не сотні хибних «✗» у звіті.
+ */
+import { readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { omlxHealthCheck, pickBackend } from '../../../lib/llm.mjs'
+import { generateDoc, DEFAULT_LOCAL_MODEL } from './docgen-gen.mjs'
+import { crc32, stampDoc, readDocQuality, QUALITY_THRESHOLD } from './docgen-crc.mjs'
+import { resolveRoot, scanForDocFiles } from './docgen-scan.mjs'
+
+/**
+ * Парсить `--limit N` / `--from N` / прапори режимів для дозапуску великого прогону.
+ * @param {string[]} argv аргументи
+ * @returns {{ from: number, limit: number, overwrite: boolean, retryDegraded: boolean }} зріз і режими
+ */
+function parseGenArgs(argv) {
+  const num = (flag, dflt) => {
+    const i = argv.indexOf(flag)
+    return i !== -1 && argv[i + 1] ? Number(argv[i + 1]) || dflt : dflt
+  }
+  return {
+    from: num('--from', 0),
+    limit: num('--limit', Infinity),
+    overwrite: argv.includes('--overwrite'),
+    retryDegraded: argv.includes('--retry-degraded')
+  }
+}
+
+/**
+ * Цілі генерації за режимом:
+ *   - default          → застарілі (stale);
+ *   - `--overwrite`     → усі;
+ *   - `--retry-degraded` → свіжі за CRC, але зі `score < QUALITY_THRESHOLD`.
+ * @param {string} root абсолютний корінь
+ * @param {Array<object>} all результат scanForDocFiles
+ * @param {{ overwrite: boolean, retryDegraded: boolean }} mode режими
+ * @returns {Array<object>} відфільтровані цілі
+ */
+function selectTargets(root, all, { overwrite, retryDegraded }) {
+  if (retryDegraded) {
+    return all.filter(f => {
+      if (f.stale) return false
+      const { score } = readDocQuality(join(root, f.docPath))
+      return score !== null && score < QUALITY_THRESHOLD
+    })
+  }
+  if (overwrite) return all
+  return all.filter(f => f.stale)
+}
+
+/**
+ * Preflight локального бекенда: для omlx-моделі — мінімальний chat-виклик.
+ * @returns {string|null} текст фатальної проблеми або null якщо можна генерувати
+ */
+function preflightProblem() {
+  if (pickBackend(DEFAULT_LOCAL_MODEL) !== 'omlx') return null
+  const hc = omlxHealthCheck({ model: DEFAULT_LOCAL_MODEL })
+  if (hc.ok) return null
+  if (hc.reason === 'memory-guard') {
+    return `omlx memory-guard: модель не влазить у динамічну стелю пам'яті (машина зайнята).\n  Звільни пам'ять або повтори прогін пізніше.\n  ${hc.detail}`
+  }
+  if (hc.reason === 'down') {
+    return `omlx-сервер не відповідає. Запусти \`omlx serve\` і повтори.\n  ${hc.detail}`
+  }
+  if (hc.reason === 'auth') {
+    return `omlx вимагає API-ключ. Вистав N_CURSOR_OMLX_KEY (auth.api_key з ~/.omlx/settings.json).\n  ${hc.detail}`
+  }
+  return `omlx помилка: ${hc.detail}`
+}
+
+/**
+ * `doc-files gen` — згенерувати документацію для застарілих/відсутніх док.
+ * @param {string[]} argv аргументи після назви субкоманди
+ * @returns {Promise<number>} exit-код: 0 — без помилок, 1 — хоча б одна помилка або фейл preflight
+ */
+export async function runDocFilesGenCli(argv) {
+  const root = resolveRoot(argv)
+  const { from, limit, overwrite, retryDegraded } = parseGenArgs(argv)
+
+  const all = scanForDocFiles(root)
+  const targets = selectTargets(root, all, { overwrite, retryDegraded }).slice(from, from + limit)
+
+  if (targets.length === 0) {
+    console.log(
+      retryDegraded
+        ? '✓ doc-files: degraded-док немає. Нічого переганяти.'
+        : '✓ doc-files: усі файлові доки свіжі. Нічого генерувати.'
+    )
+    return 0
+  }
+
+  const problem = preflightProblem()
+  if (problem) {
+    console.error(`✗ doc-files gen: ${problem}`)
+    return 1
+  }
+
+  let modeTxt = ''
+  if (overwrite) modeTxt = ' (--overwrite)'
+  else if (retryDegraded) modeTxt = ' (--retry-degraded)'
+  console.log(`📋 doc-files: до генерації ${targets.length} файл(ів)${modeTxt}`)
+  const stats = { ok: 0, degraded: 0, err: 0, errors: [] }
+
+  let done = 0
+  for (const file of targets) {
+    done++
+    const sourceAbs = join(root, file.sourcePath)
+    process.stdout.write(`  [${done}/${targets.length}] ${file.sourcePath} … `)
+    try {
+      const result = await generateDoc(sourceAbs)
+      const crc = crc32(readFileSync(sourceAbs))
+      const docAbs = join(root, file.docPath)
+      mkdirSync(dirname(docAbs), { recursive: true })
+      const quality =
+        result.score === null ? null : { score: result.score, issues: result.degraded ? result.issues : [] }
+      writeFileSync(docAbs, stampDoc(result.md, file.sourcePath, crc, quality))
+      stats.ok++
+      if (result.degraded) {
+        stats.degraded++
+        process.stdout.write(`⚠ degraded score=${result.score} crc=${crc}\n`)
+      } else {
+        process.stdout.write(`✓ score=${result.score ?? '—'} crc=${crc}\n`)
+      }
+    } catch (error) {
+      stats.err++
+      stats.errors.push(file.sourcePath)
+      process.stdout.write(`✗ ${error.message}\n`)
+    }
+  }
+
+  console.log(`\n${'─'.repeat(50)}\n✓ OK: ${stats.ok}  ⚠ degraded: ${stats.degraded}  ✗ Err: ${stats.err}`)
+  if (stats.errors.length > 0) {
+    console.log('Помилки:')
+    for (const e of stats.errors) console.log(`  - ${e}`)
+  }
+  if (stats.degraded > 0) {
+    console.log(`Degraded-доки перегенеровуються пізніше: npx @nitra/cursor doc-files gen --retry-degraded`)
+  }
+  return stats.err > 0 ? 1 : 0
+}
+
+/**
+ * `doc-files stamp` — детерміновано (пере)штампувати frontmatter `source`+`crc`
+ * у НАЯВНИХ доках без виклику LLM. Для міграції док, які ще не мають CRC.
+ * Поля якості (`score`/`issues`) при цьому зберігаються з наявного frontmatter.
+ * @param {string[]} argv аргументи після назви субкоманди
+ * @returns {number} exit-код: 0 — успіх
+ */
+export function runDocFilesStampCli(argv) {
+  const root = resolveRoot(argv)
+  let stamped = 0
+  for (const file of scanForDocFiles(root)) {
+    const docAbs = join(root, file.docPath)
+    if (!existsSync(docAbs)) continue
+    const sourceAbs = join(root, file.sourcePath)
+    const crc = crc32(readFileSync(sourceAbs))
+    const md = readFileSync(docAbs, 'utf8')
+    const { score, issues } = readDocQuality(docAbs)
+    writeFileSync(docAbs, stampDoc(md, file.sourcePath, crc, score === null ? null : { score, issues }))
+    stamped++
+  }
+  console.log(`✓ doc-files stamp: оновлено frontmatter у ${stamped} доці(ах).`)
+  return 0
+}
+
+if (isRunAsCli(import.meta.url)) {
+  const [sub, ...rest] = process.argv.slice(2)
+  const argv = sub === 'gen' || sub === 'stamp' ? rest : process.argv.slice(2)
+  process.exitCode = sub === 'stamp' ? runDocFilesStampCli(argv) : await runDocFilesGenCli(argv)
+}

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

@@ -0,0 +1,291 @@
+/** @see ./docs/docgen-gen.md */
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+import { env } from 'node:process'
+import { resolveModel } from '../../../lib/models.mjs'
+import { DEFAULT_OMLX_MODEL } from '../../../lib/omlx.mjs'
+import { callLlm } from '../../../lib/llm.mjs'
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { extractFacts } from './docgen-extract.mjs'
+import { extractAnchors } from './docgen-extract-anchors.mjs'
+import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
+import {
+  oneShotMessages,
+  sectionMessages,
+  criticMessages,
+  refineMessages,
+  guaranteesFromMarkers
+} from './docgen-prompts.mjs'
+
+const FENCE_OPEN_RE = /^```[a-z]*\n?/
+const FENCE_CLOSE_RE = /\n?```\s*$/
+const LEADING_HEADING_RE = /^#{1,6}[ \t]{1,8}[^\n]{0,400}\n{1,8}/
+const SECTION_HEADING_RE = /^##\s+(.+)/
+const SECTION_KEY_CLEAN_RE = /[^а-яіїєґa-z0-9]/gi
+const CACHE_MENTION_RE = /кеш/i
+const CACHE_NEGATION_RE = /(?:не|без)\s+(?:\S+\s+)?кеш|немає\s+кеш/i
+const CRITIC_NONE_RE = /^\s*NONE\s*$/i
+
+/**
+ * Прибирає код-фенс-обгортку (потрійні бектіки) й випадковий провідний
+ * `##`-заголовок із секції.
+ * @param {string} text сирий вихід моделі
+ * @returns {string} очищений текст секції
+ */
+function stripSection(text) {
+  let t = text.trim()
+  if (t.startsWith('```')) {
+    t = t.replace(FENCE_OPEN_RE, '').replace(FENCE_CLOSE_RE, '').trim()
+  }
+  t = t.replace(LEADING_HEADING_RE, '') // зрізати випадковий заголовок
+  return t.trim()
+}
+
+/**
+ * Stage 2 (детермінований лінт, 0 токенів): зрізає сигнатури `name(args)` → `name`.
+ * Два проходи — щоб зняти вкладені виклики на кшталт `check(cwd = process.cwd())`.
+ * Не чіпає дужки без ідентифікатора перед ними (напр. `(abie.mdc)`, «(наприклад)»).
+ * @param {string} text текст секції
+ * @returns {string} текст без сигнатур у дужках
+ */
+function stripSignatures(text) {
+  let t = text
+  for (let i = 0; i < 2; i++) t = t.replaceAll(/([`\w$.]{1,80})\([^()]{0,300}\)/g, '$1')
+  return t
+}
+
+/**
+ * Розбиває md на секції за ## заголовками.
+ * @param {string} md зібраний документ
+ * @returns {Record<string, string>} нормалізований ключ секції → її тіло
+ */
+function parseSections(md) {
+  const result = {}
+  let cur = null
+  for (const line of md.split('\n')) {
+    const m = line.match(SECTION_HEADING_RE)
+    if (m) {
+      cur = m[1].toLowerCase().replaceAll(SECTION_KEY_CLEAN_RE, '')
+      result[cur] = ''
+    } else if (cur) result[cur] += line + '\n'
+  }
+  return result
+}
+
+/**
+ * Чи містить текст бектік-обгорнуте імʼя символу (`sym`) — уникає substring false positives.
+ * @param {string} text текст секції
+ * @param {string} sym імʼя символу без бектіків
+ * @returns {boolean} true — імʼя згадано
+ */
+function hasName(text, sym) {
+  return text.includes('`' + sym + '`')
+}
+
+/**
+ * Stage 2.5 — детермінований скоринг (0 токенів): перевіряє вихід проти фактів.
+ * @param {string} md зібраний документ
+ * @param {object} facts факт-лист про файл
+ * @returns {{ score: number, issues: string[] }} оцінка 0–100 і коди проблем
+ */
+function scoreDoc(md, facts) {
+  const s = parseSections(md)
+  let score = 100
+  const issues = []
+
+  if (!s['огляд']) {
+    score -= 25
+    issues.push('no-overview')
+  }
+
+  const behavior = s['поведінка'] ?? ''
+  if (behavior.length < 60) {
+    score -= 20
+    issues.push('short-behavior')
+  }
+
+  const guarantees = s['гарантіїповедінки'] ?? ''
+  // Будь-яка згадка "кеш" у Гарантіях коли файл не кешує — галюцинація
+  // Негація: "не кешує", "не має кешування", "без кешування", "немає кешу"
+  const cacheHit = CACHE_MENTION_RE.test(guarantees) && !CACHE_NEGATION_RE.test(guarantees)
+  if (!facts.markers?.caches && cacheHit) {
+    score -= 20
+    issues.push('cache-hallucination')
+  }
+
+  for (const sym of facts.internalSymbols ?? []) {
+    const inDoc = hasName(guarantees, sym) || hasName(s['огляд'] ?? '', sym) || hasName(s['поведінка'] ?? '', sym)
+    if (inDoc) {
+      score -= 10
+      issues.push(`internal-name:${sym}`)
+    }
+  }
+
+  return { score: Math.max(0, score), issues }
+}
+
+/**
+ * E2 — один цикл critique→refine на секцію.
+ * Повертає або уточнену чорнетку, або оригінал якщо критик повідомив NONE.
+ * @param {'overview'|'behavior'|'api'} sectionKey ключ секції
+ * @param {string} draft чорнетка секції
+ * @param {object} facts факт-лист
+ * @param {object|null} anchors анкори файлу
+ * @param {string} model model-id
+ * @param {number} timeoutMs ліміт на один виклик
+ * @returns {string} фінальний текст секції
+ */
+function critiqueRefineSection(sectionKey, draft, facts, anchors, model, timeoutMs) {
+  const critique = callLlm(criticMessages(sectionKey, draft, facts, anchors), model, { timeoutMs }).trim()
+  if (!critique || CRITIC_NONE_RE.test(critique) || critique.length < 12) return draft
+  const refined = callLlm(refineMessages(sectionKey, draft, critique, facts, anchors), model, { timeoutMs }).trim()
+  return stripSignatures(stripSection(refined)) || draft
+}
+
+/**
+ * Чи треба refine для секції API: тільки якщо є >1 експорту і всі desc-и порожні
+ * (саме там модель схильна писати «застосовує логіку до файлу»).
+ * @param {object} facts факт-лист
+ * @returns {boolean} true — секцію API варто прогнати через критика
+ */
+function apiNeedsRefine(facts) {
+  const exps = facts.exports ?? []
+  if (exps.length <= 1) return false
+  return exps.every(e => !e.desc)
+}
+
+/**
+ * One-shot: один виклик LLM на весь документ (для unsupported-структур).
+ * @param {object} facts факт-лист
+ * @param {string} src вміст файлу
+ * @param {string} model model-id
+ * @param {number} [timeoutMs] ліміт на виклик
+ * @returns {{ md: string }} зібраний документ
+ */
+function oneShotDoc(facts, src, model, timeoutMs = LOCAL_TIMEOUT_MS) {
+  const text = callLlm(oneShotMessages(facts, src), model, { timeoutMs })
+  let md = stripSignatures(stripSection(text))
+  if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
+  return { md: md + '\n' }
+}
+
+/**
+ * Stage 3: фіксовані заголовки у фіксованому порядку.
+ * @param {string} stem назва файлу для H1
+ * @param {Record<string, string>} sections тексти секцій за ключами
+ * @returns {string} зібраний md-документ
+ */
+function assemble(stem, sections) {
+  const order = [
+    ['overview', '## Огляд'],
+    ['behavior', '## Поведінка'],
+    ['api', '## Публічний API'],
+    ['guarantees', '## Гарантії поведінки']
+  ]
+  const parts = [`# ${stem}`]
+  for (const [key, title] of order) {
+    const body = sections[key]
+    if (body && body.trim()) parts.push(`${title}\n\n${body.trim()}`)
+  }
+  return parts.join('\n\n') + '\n'
+}
+
+/**
+ * Orchestrated: N окремих LLM-викликів, по одному на секцію.
+ * Код потрапляє лише в `behavior`; решта секцій — на мінімальному факт-листі.
+ * @param {object} facts факт-лист
+ * @param {string} src вміст файлу
+ * @param {string} model model-id
+ * @param {number} timeoutMs ліміт на один виклик
+ * @param {{ anchors?: object|null, temperature?: number }} [opts] анкори й температура семплінгу
+ * @returns {{ md: string }} зібраний документ
+ */
+function orchestratedDoc(facts, src, model, timeoutMs, { anchors = null, temperature = 0.2 } = {}) {
+  const sections = {}
+  const anc = anchors ?? extractAnchors(src)
+  // E3: «Гарантії» — детермінований шаблон з markers (0 LLM-запитів, 0 generic-фраз)
+  sections.guarantees = guaranteesFromMarkers(facts)
+  for (const s of sectionMessages(facts, src, anc)) {
+    if (s.key === 'guarantees') continue // вже згенеровано детерміновано
+    let draft = stripSignatures(stripSection(callLlm(s.messages, model, { timeoutMs, temperature })))
+    // E2 + E3: critique→refine лише для секцій, де мала модель зриває на generic
+    if (s.key === 'overview' || (s.key === 'api' && apiNeedsRefine(facts))) {
+      draft = critiqueRefineSection(s.key, draft, facts, anc, model, timeoutMs)
+    }
+    sections[s.key] = draft
+  }
+  return { md: assemble(basename(facts.relPath), sections) }
+}
+
+/** Максимальний час генерації одного LLM-виклику. */
+const LOCAL_TIMEOUT_MS = 5 * 60 * 1000
+/**
+ * Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel('min') → omlx напряму.
+ * Останній fallback гарантує local-only шлях без жодних env (через pi CLI той
+ * самий локальний виклик виміряно повільніший на ~46%).
+ */
+export const DEFAULT_LOCAL_MODEL = env.N_CURSOR_DOCGEN_MODEL ?? (resolveModel('min') || `omlx/${DEFAULT_OMLX_MODEL}`)
+
+/**
+ * Головний API: файл → md-дока з det-оцінкою.
+ *
+ * Local-only (ADR 260610-2228): жодних cloud-ескалацій і pre-route — будь-який
+ * файл генерується локальною моделлю. Якщо det-score нижче порогу, один retry
+ * з вищою температурою (best-of-2); якщо й він не допоміг — результат
+ * позначається `degraded`, рішення про перегенерацію приймає batch/користувач.
+ * @param {string} file абсолютний шлях джерела
+ * @param {{ model?: string, threshold?: number }} [opts] model-id і поріг degraded
+ * @returns {{ md: string, ms: number, score: number|null, issues: string[], degraded: boolean, model: string }} документ і метадані генерації
+ */
+export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUALITY_THRESHOLD } = {}) {
+  const src = readFileSync(file, 'utf8')
+  const facts = extractFacts(src, file)
+  const t0 = Date.now()
+
+  const anchors = facts.unsupported ? null : extractAnchors(src)
+  let r = facts.unsupported
+    ? oneShotDoc(facts, src, model)
+    : orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors })
+
+  // unsupported (vue/py до юніт-шару): скорер не застосовний — score=null, не degraded
+  if (facts.unsupported) {
+    return { ...r, ms: Date.now() - t0, score: null, issues: [], degraded: false, model }
+  }
+
+  // Stage 2.5: детермінований скоринг (0 токенів)
+  let { score, issues } = scoreDoc(r.md, facts)
+
+  // E4: best-of-2 — один retry з вищою температурою, det-вибір кращого
+  if (score < threshold && env.N_CURSOR_DOCGEN_BEST_OF !== '0') {
+    try {
+      const r2 = orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, temperature: 0.5 })
+      const s2 = scoreDoc(r2.md, facts)
+      if (s2.score > score) {
+        r = r2
+        score = s2.score
+        issues = [...s2.issues, 'best-of-2:retry-won']
+      } else {
+        issues = [...issues, 'best-of-2:retry-lost']
+      }
+    } catch (error) {
+      issues = [...issues, `best-of-2:retry-error: ${error.message}`]
+    }
+  }
+
+  return { ...r, ms: Date.now() - t0, score, issues, degraded: score < threshold, model }
+}
+
+// CLI: node docgen-gen.mjs <file> [--model <m>]
+if (isRunAsCli(import.meta.url)) {
+  const args = process.argv.slice(2)
+  const file = args.find(a => !a.startsWith('--'))
+  const mi = args.indexOf('--model')
+  const model = mi === -1 ? DEFAULT_LOCAL_MODEL : args[mi + 1]
+  if (!file) {
+    throw new Error('Usage: node docgen-gen.mjs <file> [--model <m>]')
+  }
+  const r = generateDoc(file, { model })
+  const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
+  process.stderr.write(`[local ${r.model}] ${r.ms}ms / score=${r.score}${r.degraded ? ' DEGRADED' : ''}${issuesTxt}\n`)
+  process.stdout.write(r.md)
+}