@nitra/cursor 5.1.0 → 5.2.0

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)
+}

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 }
@@ -45,64 +55,68 @@ const msgs = (system, user) => [
  * Код потрапляє лише в `behavior`; решта секцій — на факт-листі.
  * @param {object} facts факт-лист про файл
  * @param {string} src вміст файлу
+ * @param {object|null} [anchors] анкори файлу для обовʼязкового включення
  * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів
  */
 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({
+  const overview = {
     key: 'overview',
     numPredict: 220,
     messages: msgs(
       `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
       'Напиши вміст секції «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Без заголовка, без переліку функцій. Заборонені generic-фрази типу «забезпечує перевірку», «виконує валідацію» — пиши КОНКРЕТНО що саме і за яким контрактом.'
     )
-  })
+  }
 
   // Поведінка — ЄДИНА секція, якій потрібен код
-  out.push({
+  const behaviorTask = multi
+    ? 'для кожної публічної функції — один короткий пункт «що вона робить»'
+    : 'нумерований алгоритм у бізнес-термінах'
+  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}. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без 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 [overview, 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 out
+  return [overview, behavior, api]
 }
 
 /**
  * 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 +136,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 +160,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 +191,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\`\`\``
-}