@nitra/cursor 5.0.1 → 5.0.3

package/rules/abie/lib/docs/http-route.md

@@ -2,43 +2,23 @@
 
 ## Огляд
 
-Cross-документна аналітика abie `HTTPRoute`-маніфестів: рахує посилання (`backendRefs`) на спільні `-hl`-сервіси у base-шарі пакета (поза overlay `ua`) і водночас фіксує порушення `namespace`. Слугує джерелом істини для `ua_http_route`-концерну, який звіряє кількість namespace-patch-ів в overlay із кількістю base-reference.
+Файл надає інструмент для порівняльного аналізу конфігурації HTTP-маршрутів. Він виконує порівняння кількості `backendRefs` для сервісів `auth-run-hl` та `file-link-hl` у базових маніфестах пакета з кількістю патчів, визначеною в оверлеях. Цей механізм використовується для синхронізації кількості патчів у верхньому рівні з фактичною кількістю посилань у базі. (abie.mdc)
 
 ## Поведінка
 
-1. Обходить переданий перелік YAML-файлів під k8s-каталогом, лишаючи тільки ті, що належать base-шару abie-пакета й не входять до overlay `ua`.
-2. Кожен відібраний файл читається й безпечно парситься як набір YAML-документів; документи з помилками парсингу пропускаються (інші документи в тому ж файлі продовжують аналізуватися).
-3. Враховуються лише документи з `kind: HTTPRoute`. Інші види та структурно некоректні корені дають нульовий внесок.
-4. Для `HTTPRoute` обхід заходить у `spec.rules[].backendRefs[]` і для кожного посилання перевіряє, чи його `name` належить набору спільних cross-namespace сервісів.
-5. Спільними вважаються рівно два сервіси: `auth-run-hl` та `file-link-hl`. Кожне таке посилання збільшує загальний лічильник посилань на 1.
-6. Якщо посилання на спільний сервіс не має `namespace: dev`, додається помилка виду `<rel>: HTTPRoute backendRefs до <name> має містити namespace: dev (abie.mdc)`.
-7. Підсумок по всьому пакету повертається як агрегований лічильник посилань (`refCount`) і список base-помилок (`baseErrors`).
-
-Приклад спільного backend-посилання, яке проходить перевірку:
-
-```yaml
-kind: HTTPRoute
-spec:
-  rules:
-    - backendRefs:
-        - name: auth-run-hl
-          namespace: dev
-```
+ABIE_SHARED_CROSS_NS_BACKEND_NAMES
+Визначає список спільних сервісів, які підлягають аналітиці.
 
-## Публічний API
+analyzeAbieSharedBackendRefsInPackageK8s
+Збирає кількість посилань на спільні бекенди та порушення вимог до namespace у базових документах HTTPRoute пакета.
 
-- `analyzeAbieSharedBackendRefsInPackageK8s` — за коренем репозиторію, шляхом каталогу пакета й переліком YAML-файлів повертає сумарну кількість base-посилань на спільні `-hl`-сервіси та список порушень `namespace` у base-шарі.
-- `ABIE_SHARED_CROSS_NS_BACKEND_NAMES` — заморожений перелік імен спільних cross-namespace сервісів (`auth-run-hl`, `file-link-hl`), за якими ведеться підрахунок.
+## Публічний API
 
-## Де використовується
+ABIE_SHARED_CROSS_NS_BACKEND_NAMES — Формує імена для крос-нішових зв'язків між бекендами. (abie.mdc)
 
-Споживається `ua_http_route`-концерном (`npm/rules/abie/js/ua_http_route.mjs`) для синхронізації числа namespace-patch-ів в overlay `ua` із кількістю base-reference.
+analyzeAbieSharedBackendRefsInPackageK8s — Збирає кількість спільних посилань `backendRefs` та базові помилки з YAML-файлів пакета, ігноруючи неймспейс `dev`. (abie.mdc)
 
 ## Гарантії поведінки
 
-- Read-only: файли лише читаються, аналіз нічого не пише на диск.
-- Парсинг fail-safe: помилки читання/розбору YAML придушуються, а документи з помилками не враховуються — некоректний файл не зриває аналіз пакета.
-- Структурна стійкість: `null`, масиви та поля неочікуваного типу на будь-якому рівні (корінь, `spec`, `rules`, окреме посилання) дають нульовий внесок без винятків.
-- Лічильник рахує тільки посилання на два визначені спільні сервіси; інші backend-сервіси ігноруються.
-- Перелік спільних імен заморожений і не може бути змінений споживачами.
-- Шляхи у повідомленнях нормалізовані до `/`, тож вихід однаковий на POSIX і Windows.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/skills/docgen/js/docgen-batch-omlx.mjs

@@ -0,0 +1,82 @@
+/**
+ * Тимчасовий A/B-batch: docgen Tier 1 через omlx (gemma-4-e2b 4bit на MLX)
+ * замість pi/ollama. Перезаписує всі docs/<stem>.md для файлів з sym<4,
+ * НЕ ескалює в cloud. Призначення — порівняння якості omlx vs попередньої версії.
+ *
+ * Запуск: node npm/skills/docgen/js/docgen-batch-omlx.mjs [--limit N] [--from N]
+ *   --limit N — обробити перші N файлів зі списку sym<4
+ *   --from N  — почати з індексу N (для дозапуску)
+ */
+import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execSync } from 'node:child_process'
+import { env } from 'node:process'
+import { generateDoc } from './docgen-gen.mjs'
+import { extractFacts } from './docgen-extract.mjs'
+
+const ROOT = resolve(fileURLToPath(import.meta.url), '../../../../..')
+
+const args = process.argv.slice(2)
+const limitIdx = args.indexOf('--limit')
+const limit = limitIdx !== -1 ? Number(args[limitIdx + 1]) : Infinity
+const fromIdx = args.indexOf('--from')
+const from = fromIdx !== -1 ? Number(args[fromIdx + 1]) : 0
+
+env.N_CURSOR_DOCGEN_BACKEND = 'omlx'
+
+const scanOut = execSync('node npm/bin/n-cursor.js docgen scan', { cwd: ROOT, encoding: 'utf8' })
+const all = JSON.parse(scanOut)
+
+const local = []
+for (const f of all) {
+  try {
+    const src = readFileSync(join(ROOT, f.sourcePath), 'utf8')
+    const facts = extractFacts(src, join(ROOT, f.sourcePath))
+    const sym = (facts.internalSymbols ?? []).length
+    if (sym < 4) local.push({ ...f, sym })
+  } catch {
+    /* пропускаємо нечитані */
+  }
+}
+
+const slice = local.slice(from, from + limit)
+console.log(`📋 Файлів sym<4 у проєкті: ${local.length}; обробляємо: ${slice.length} (from=${from}, limit=${limit === Infinity ? 'усе' : limit})`)
+console.log(`🤖 Бекенд: omlx → ${env.N_CURSOR_DOCGEN_OMLX_URL ?? 'http://127.0.0.1:8000/v1/chat/completions'}`)
+
+const stats = { ok: 0, err: 0, totalMs: 0, scores: [], errors: [] }
+
+for (let i = 0; i < slice.length; i++) {
+  const f = slice[i]
+  const t0 = Date.now()
+  const pct = Math.round(((i + 1) / slice.length) * 100)
+  process.stdout.write(`  [${i + 1}/${slice.length} ${pct}%] sym=${f.sym} ${f.sourcePath} ... `)
+  try {
+    const result = await generateDoc(join(ROOT, f.sourcePath), {
+      symThreshold: 999, // не уходити в cloud за sym
+      cloudModel: null // повністю вимкнути cloud-fallback навіть при low det-score
+    })
+    const docAbs = join(ROOT, f.docPath)
+    mkdirSync(dirname(docAbs), { recursive: true })
+    writeFileSync(docAbs, result.md)
+    const ms = Date.now() - t0
+    stats.ok++
+    stats.totalMs += ms
+    stats.scores.push(result.score ?? 0)
+    process.stdout.write(`✓ ${Math.round(ms / 1000)}s score=${result.score ?? '?'} tier=${result.tier}\n`)
+  } catch (error) {
+    stats.err++
+    stats.errors.push({ path: f.sourcePath, msg: error.message })
+    process.stdout.write(`✗ ${error.message}\n`)
+  }
+}
+
+const avgScore = stats.scores.length ? Math.round(stats.scores.reduce((a, b) => a + b, 0) / stats.scores.length) : 0
+console.log(`\n${'─'.repeat(60)}`)
+console.log(`✓ OK: ${stats.ok}  ✗ Err: ${stats.err}`)
+console.log(`  Сумарний час: ${Math.round(stats.totalMs / 1000)}s; середній на файл: ${stats.ok ? Math.round(stats.totalMs / stats.ok / 1000) : 0}s`)
+console.log(`  Середній det-score: ${avgScore}`)
+if (stats.errors.length) {
+  console.log('Помилки:')
+  for (const e of stats.errors) console.log(`  - ${e.path}: ${e.msg}`)
+}

package/skills/docgen/js/docgen-compare-pi-vs-direct.mjs

@@ -0,0 +1,95 @@
+/**
+ * A/B: docgen Tier 1 через pi cli (з omlx-провайдером у ~/.pi/agent/models.json)
+ * vs прямий callOmlxMessages (`N_CURSOR_DOCGEN_BACKEND=omlx`).
+ *
+ * Однаковий 8-сет файлів, однаковий оркестратор (E1+E2+E3+E4), різний backend.
+ * Пише в /tmp/docgen-compare/{pi,direct}/<idx>-<stem>.md і збирає метрики.
+ *
+ * Запуск: node npm/skills/docgen/js/docgen-compare-pi-vs-direct.mjs [--from N] [--limit N]
+ */
+import { readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs'
+import { join, resolve, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execSync } from 'node:child_process'
+import { env } from 'node:process'
+import { generateDoc } from './docgen-gen.mjs'
+import { extractFacts } from './docgen-extract.mjs'
+
+const ROOT = resolve(fileURLToPath(import.meta.url), '../../../../..')
+const TMP = '/tmp/docgen-compare'
+
+const args = process.argv.slice(2)
+const limitIdx = args.indexOf('--limit')
+const limit = limitIdx !== -1 ? Number(args[limitIdx + 1]) : 8
+const fromIdx = args.indexOf('--from')
+const from = fromIdx !== -1 ? Number(args[fromIdx + 1]) : 1
+
+const scanOut = execSync('node npm/bin/n-cursor.js docgen scan', { cwd: ROOT, encoding: 'utf8' })
+const all = JSON.parse(scanOut)
+
+const local = []
+for (const f of all) {
+  try {
+    const src = readFileSync(join(ROOT, f.sourcePath), 'utf8')
+    const facts = extractFacts(src, join(ROOT, f.sourcePath))
+    const sym = (facts.internalSymbols ?? []).length
+    if (sym < 4) local.push({ ...f, sym })
+  } catch {}
+}
+const slice = local.slice(from, from + limit)
+
+mkdirSync(join(TMP, 'pi'), { recursive: true })
+mkdirSync(join(TMP, 'direct'), { recursive: true })
+
+async function runBackendAsync(kind) {
+  if (kind === 'direct') env.N_CURSOR_DOCGEN_BACKEND = 'omlx'
+  else delete env.N_CURSOR_DOCGEN_BACKEND
+  const out = { ok: 0, err: 0, totalMs: 0, scores: [], lengths: [], errors: [], times: [] }
+  console.log(`\n══════ Backend: ${kind} ══════`)
+  for (let i = 0; i < slice.length; i++) {
+    const f = slice[i]
+    const t0 = Date.now()
+    const stem = basename(f.sourcePath).replace(/\.[^.]+$/, '')
+    const destFile = join(TMP, kind, `${String(i + 1).padStart(2, '0')}-${stem}.md`)
+    process.stdout.write(`  [${i + 1}/${slice.length}] sym=${f.sym} ${f.sourcePath} ... `)
+    try {
+      const r = await generateDoc(join(ROOT, f.sourcePath), { symThreshold: 999, cloudModel: null })
+      writeFileSync(destFile, r.md)
+      const ms = Date.now() - t0
+      out.ok++
+      out.totalMs += ms
+      out.times.push(ms)
+      out.scores.push(r.score ?? 0)
+      out.lengths.push(r.md.length)
+      process.stdout.write(`✓ ${Math.round(ms / 1000)}s score=${r.score ?? '?'} chars=${r.md.length}\n`)
+    } catch (error) {
+      out.err++
+      out.errors.push({ path: f.sourcePath, msg: error.message })
+      process.stdout.write(`✗ ${error.message}\n`)
+    }
+  }
+  return out
+}
+
+const direct = await runBackendAsync('direct')
+const pi = await runBackendAsync('pi')
+
+function avg(a) { return a.length ? Math.round(a.reduce((x, y) => x + y, 0) / a.length) : 0 }
+function median(a) {
+  if (!a.length) return 0
+  const s = [...a].sort((x, y) => x - y)
+  return s[Math.floor(s.length / 2)]
+}
+
+const report = {
+  files: slice.map(f => f.sourcePath),
+  direct: { ok: direct.ok, err: direct.err, avgMs: avg(direct.times), medianMs: median(direct.times), avgScore: avg(direct.scores), avgChars: avg(direct.lengths), totalSec: Math.round(direct.totalMs / 1000) },
+  pi: { ok: pi.ok, err: pi.err, avgMs: avg(pi.times), medianMs: median(pi.times), avgScore: avg(pi.scores), avgChars: avg(pi.lengths), totalSec: Math.round(pi.totalMs / 1000) }
+}
+writeFileSync(join(TMP, 'report.json'), JSON.stringify(report, null, 2))
+
+console.log(`\n${'─'.repeat(60)}\nA/B SUMMARY (${slice.length} файлів, той самий оркестратор)\n${'─'.repeat(60)}`)
+console.log(`Backend        | ok | err | avg s | median s | avg score | avg chars | total s`)
+console.log(`direct (curl)  | ${direct.ok}  | ${direct.err}   | ${Math.round(report.direct.avgMs / 1000)}    | ${Math.round(report.direct.medianMs / 1000)}        | ${report.direct.avgScore}        | ${report.direct.avgChars}      | ${report.direct.totalSec}`)
+console.log(`pi cli         | ${pi.ok}  | ${pi.err}   | ${Math.round(report.pi.avgMs / 1000)}    | ${Math.round(report.pi.medianMs / 1000)}        | ${report.pi.avgScore}        | ${report.pi.avgChars}      | ${report.pi.totalSec}`)
+console.log(`\nФайли: ${TMP}/{direct,pi}/<idx>-<stem>.md\nReport: ${TMP}/report.json`)

package/skills/docgen/js/docgen-extract-anchors.mjs

@@ -0,0 +1,92 @@
+/**
+ * E1 (Fact-anchoring): детермінований витяг «анкорів» — конкретних фрагментів
+ * з коду, які LLM зобовʼязана згадати в документації, щоб не зісковзнути на
+ * generic-фрази.
+ *
+ * Категорії анкорів:
+ *   - urls         : усі https?://… у вихідному коді
+ *   - magicStrings : export const X = '…' з непорожнім value (≤120 символів)
+ *   - errorMarkers : суфікси повідомлень про помилки виду `(rule.mdc)`
+ *   - configRefs   : посилання на .json-конфіги проєкту (.n-cursor.json, …)
+ *   - examples     : ```…```-блоки у file-header JSDoc (першому коментарі файла)
+ *
+ * Всі регулярки — на сирому src без AST: дешево, безпечно, без false-positive
+ * критичної ваги (надмір — менша проблема, ніж пропуск).
+ */
+
+const URL_RE = /https?:\/\/[^\s'"`)<>]+/g
+const EXPORT_CONST_RE = /export\s+const\s+([A-Z][A-Z0-9_]+)\s*=\s*(['"`])([^'"`]+)\2/g
+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
+
+/** Dedup масив, зберігаючи порядок появи. */
+function uniq(arr) {
+  const seen = new Set()
+  const out = []
+  for (const x of arr) {
+    if (!seen.has(x)) {
+      seen.add(x)
+      out.push(x)
+    }
+  }
+  return out
+}
+
+/**
+ * Витягує анкори з вихідного коду файла.
+ * @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 magicStrings = []
+  const seenNames = new Set()
+  for (const m of src.matchAll(EXPORT_CONST_RE)) {
+    const name = m[1]
+    const value = m[3]
+    if (!seenNames.has(name) && value.length <= 120) {
+      seenNames.add(name)
+      magicStrings.push({ name, value })
+    }
+  }
+
+  const errorMarkers = uniq([...src.matchAll(ERROR_MARKER_RE)].map(m => m[1]))
+  const configRefs = uniq([...src.matchAll(CONFIG_REF_RE)].map(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())) : []
+
+  return { urls, magicStrings, errorMarkers, configRefs, examples }
+}
+
+/**
+ * Форматує анкори у компактний текст для system-промпта.
+ * Якщо анкорів немає взагалі — повертає порожній рядок (системний блок про
+ * анкори не додається, щоб не вводити LLM в оману «обовʼязковими» полями).
+ * @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('; ')}`
+    )
+  }
+  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 (!blocks.length) return ''
+  return `АНКОРИ ДО ОБОВ'ЯЗКОВОГО ВКЛЮЧЕННЯ:\n${blocks.join('\n')}`
+}

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

@@ -5,7 +5,8 @@ import { spawnSync } from 'node:child_process'
 import { env } from 'node:process'
 import { resolveModel } from '../../../lib/models.mjs'
 import { extractFacts } from './docgen-extract.mjs'
-import { STYLE, oneShotPromptText, sectionMessages } from './docgen-prompts.mjs'
+import { extractAnchors } from './docgen-extract-anchors.mjs'
+import { oneShotMessages, sectionMessages, criticMessages, refineMessages, guaranteesFromMarkers } from './docgen-prompts.mjs'
 
 const QUALITY_THRESHOLD = 70
 
@@ -89,8 +90,62 @@ function scoreDoc(md, facts) {
   return { score: Math.max(0, score), issues }
 }
 
-/** Викликає pi і повертає stdout. Кидає якщо pi повертає ненульовий код. */
-function callPi(prompt, model, timeoutMs) {
+/**
+ * omlx-бекенд: справжні OpenAI-сумісні messages (system+user збереженi).
+ * Вмикається `N_CURSOR_DOCGEN_BACKEND=omlx`.
+ * URL: `N_CURSOR_DOCGEN_OMLX_URL` або http://127.0.0.1:8000/v1/chat/completions.
+ * Модель: переданий `model`, потім `N_CURSOR_DOCGEN_OMLX_MODEL`, потім дефолт.
+ */
+function callOmlxMessages(messages, model, timeoutMs, temperature = 0.2) {
+  const url = env.N_CURSOR_DOCGEN_OMLX_URL ?? 'http://127.0.0.1:8000/v1/chat/completions'
+  const m = model || env.N_CURSOR_DOCGEN_OMLX_MODEL || 'mlx-community--gemma-4-e2b-it-4bit'
+  const body = JSON.stringify({
+    model: m,
+    messages,
+    max_tokens: 4096,
+    temperature
+  })
+  // Ретраїмо лише transient curl-помилки (18 = transfer closed, 56 = recv failure, 52 = empty reply).
+  const TRANSIENT_CURL_CODES = new Set([18, 52, 56])
+  let lastErr
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    const r = spawnSync(
+      'curl',
+      ['-sS', '-X', 'POST', url, '-H', 'Content-Type: application/json', '-H', 'Connection: close', '--max-time', String(Math.ceil(timeoutMs / 1000)), '--data-binary', '@-'],
+      { input: body, encoding: 'utf8', timeout: timeoutMs + 5000 }
+    )
+    if (r.error) {
+      lastErr = new Error(`omlx curl error: ${r.error.message}`)
+      break
+    }
+    if (r.status !== 0) {
+      if (TRANSIENT_CURL_CODES.has(r.status) && attempt < 3) {
+        lastErr = new Error(`omlx curl exit ${r.status} (transient, retry ${attempt})`)
+        continue
+      }
+      throw new Error(`omlx curl exit ${r.status}: ${r.stderr?.slice(0, 300) ?? ''}`)
+    }
+    let j
+    try { j = JSON.parse(r.stdout) } catch { throw new Error(`omlx bad json: ${r.stdout?.slice(0, 200) ?? ''}`) }
+    if (j.error) throw new Error(`omlx api: ${JSON.stringify(j.error).slice(0, 300)}`)
+    const content = j.choices?.[0]?.message?.content?.trim() ?? ''
+    if (!content) {
+      const finish = j.choices?.[0]?.finish_reason
+      throw new Error(`omlx empty content (finish=${finish})`)
+    }
+    return content
+  }
+  throw lastErr ?? new Error('omlx unknown failure')
+}
+
+/**
+ * Універсальний виклик LLM за повним messages-масивом.
+ * - omlx: шле messages напряму (system збережено)
+ * - pi: конкатенує message.content (pi приймає лише plain prompt)
+ */
+function callLlm(messages, model, timeoutMs, temperature = 0.2) {
+  if (env.N_CURSOR_DOCGEN_BACKEND === 'omlx') return callOmlxMessages(messages, model, timeoutMs, temperature)
+  const prompt = messages.map(m => m.content).join('\n\n')
   const modelArgs = model ? ['--model', model] : []
   const r = spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session', '--mode', 'text', '--no-tools'], {
     encoding: 'utf8',
@@ -101,9 +156,30 @@ function callPi(prompt, model, timeoutMs) {
   return r.stdout?.trim() ?? ''
 }
 
-/** One-shot: один pi-виклик на весь документ. */
+/**
+ * E2 — один цикл critique→refine на секцію.
+ * Повертає або уточнену чорнетку, або оригінал якщо критик повідомив NONE.
+ */
+function critiqueRefineSection(sectionKey, draft, facts, anchors, model, timeoutMs) {
+  const critique = callLlm(criticMessages(sectionKey, draft, facts, anchors), model, timeoutMs).trim()
+  if (!critique || /^\s*NONE\s*$/i.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-и порожні
+ * (саме там модель схильна писати «застосовує логіку до файлу»).
+ */
+function apiNeedsRefine(facts) {
+  const exps = facts.exports ?? []
+  if (exps.length <= 1) return false
+  return exps.every(e => !e.desc)
+}
+
+/** One-shot: один виклик LLM на весь документ. */
 function piOneShot(facts, src, model, timeoutMs = 120_000) {
-  const text = callPi(`${STYLE}\n\n${oneShotPromptText(facts, src)}`, model, timeoutMs)
+  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', genTok: 0 }
@@ -129,12 +205,19 @@ function assemble(stem, sections) {
  * Orchestrated: N окремих pi-викликів, по одному на секцію.
  * Код потрапляє лише в `behavior`; решта секцій — на мінімальному факт-листі.
  */
-function piOrchestrated(facts, src, model, timeoutMs) {
+function piOrchestrated(facts, src, model, timeoutMs, { anchors = null, temperature = 0.2 } = {}) {
   const sections = {}
-  for (const s of sectionMessages(facts, src)) {
-    // messages = [{role:'system',content}, {role:'user',content}] → plain text prompt для pi
-    const prompt = s.messages.map(m => m.content).join('\n\n')
-    sections[s.key] = stripSignatures(stripSection(callPi(prompt, model, timeoutMs)))
+  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 лише для секцій, де gemma-4 зриває на 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), genTok: 0 }
 }
@@ -181,10 +264,11 @@ export async function generateDoc(
   // Tier 1: pi orchestrated (секція за секцією), timeout на секцію = LOCAL_TIMEOUT_MS
   // facts.unsupported → one-shot (структура файлу нестандартна)
   let r
+  const anchors = facts.unsupported ? null : extractAnchors(src)
   try {
     r = facts.unsupported
       ? piOneShot(facts, src, model, LOCAL_TIMEOUT_MS)
-      : piOrchestrated(facts, src, model, LOCAL_TIMEOUT_MS)
+      : piOrchestrated(facts, src, model, LOCAL_TIMEOUT_MS, { anchors })
   } catch (error) {
     if (cloudModel) {
       const r2 = piOneShot(facts, src, cloudModel)
@@ -194,7 +278,25 @@ export async function generateDoc(
   }
 
   // Stage 2.5: детермінований скоринг (0 токенів) — gate перед Tier 2
-  const { score: detScore, issues: detIssues } = scoreDoc(r.md, facts)
+  let { score: detScore, issues: detIssues } = scoreDoc(r.md, facts)
+
+  // E4: best-of-N. Якщо score нижчий за threshold і немає cloud-fallback — спроба
+  // ще раз з вищою температурою, керуємо через env (повторні прогони коштовні).
+  if (detScore < threshold && !cloudModel && !facts.unsupported && env.N_CURSOR_DOCGEN_BEST_OF !== '0') {
+    try {
+      const r2 = piOrchestrated(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, temperature: 0.5 })
+      const s2 = scoreDoc(r2.md, facts)
+      if (s2.score > detScore) {
+        r = r2
+        detScore = s2.score
+        detIssues = [...s2.issues, 'best-of-2:retry-won']
+      } else {
+        detIssues = [...detIssues, 'best-of-2:retry-lost']
+      }
+    } catch (error) {
+      detIssues = [...detIssues, `best-of-2:retry-error: ${error.message}`]
+    }
+  }
 
   if (detScore < threshold && cloudModel) {
     const r2 = piOneShot(facts, src, cloudModel)