@nitra/cursor 3.27.0 → 3.28.0

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

@@ -0,0 +1,95 @@
+/**
+ * Batch docgen для відсутніх файлів проєкту.
+ * sym < 4 → gemma3:4b orchestrated (local)
+ * sym ≥ 4 → Claude Sonnet (cloud, via generateDoc pre-routing)
+ */
+import { readFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { generateDoc } from './docgen-gen.mjs'
+import { extractFacts } from './docgen-extract.mjs'
+import { execSync } from 'node:child_process'
+
+const ROOT = resolve(fileURLToPath(import.meta.url), '../../../../..')
+
+// 1. Отримати список відсутніх файлів
+const scanOut = execSync('node npm/bin/n-cursor.js docgen scan', { cwd: ROOT, encoding: 'utf8' })
+const allFiles = JSON.parse(scanOut)
+const missing = allFiles.filter(x => !x.exists)
+
+console.log(`\n📋 Файлів для генерації: ${missing.length}`)
+
+// 2. Розкласти по тирах
+const local = [],
+  cloud = []
+for (const f of missing) {
+  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) cloud.push({ ...f, sym })
+    else local.push({ ...f, sym })
+  } catch {
+    local.push({ ...f, sym: 0 })
+  }
+}
+
+console.log(`  Local (sym<4): ${local.length}`)
+console.log(`  Cloud (sym≥4): ${cloud.length}`)
+
+const stats = { ok: 0, err: 0, localOk: 0, cloudOk: 0, errors: [] }
+
+// 3. Cloud файли (sym≥4) — generateDoc auto-routes до Claude
+console.log('\n☁️  Cloud tier...')
+for (const f of cloud) {
+  const t0 = Date.now()
+  try {
+    const result = await generateDoc(join(ROOT, f.sourcePath), { symThreshold: 4 })
+    const docAbs = join(ROOT, f.docPath)
+    mkdirSync(dirname(docAbs), { recursive: true })
+    writeFileSync(docAbs, result.md)
+    stats.ok++
+    stats.cloudOk++
+    console.log(`  ✓ ${f.sourcePath} (sym=${f.sym}, ${Math.round((Date.now() - t0) / 1000)}s)`)
+  } catch (e) {
+    stats.err++
+    stats.errors.push(f.sourcePath)
+    console.error(`  ✗ ${f.sourcePath}: ${e.message}`)
+  }
+}
+
+// 4. Local файли (sym<4) — gemma3:4b orchestrated
+console.log('\n💻 Local tier...')
+let done = 0
+for (const f of local) {
+  done++
+  const t0 = Date.now()
+  const pct = Math.round((done / local.length) * 100)
+  process.stdout.write(`  [${done}/${local.length} ${pct}%] ${f.sourcePath} ... `)
+  try {
+    const result = await generateDoc(join(ROOT, f.sourcePath), {
+      mode: 'orchestrated',
+      symThreshold: 999 // force local
+    })
+    const docAbs = join(ROOT, f.docPath)
+    mkdirSync(dirname(docAbs), { recursive: true })
+    writeFileSync(docAbs, result.md)
+    stats.ok++
+    stats.localOk++
+    process.stdout.write(`✓ ${Math.round((Date.now() - t0) / 1000)}s score=${result.score ?? '?'}\n`)
+  } catch (e) {
+    stats.err++
+    stats.errors.push(f.sourcePath)
+    process.stdout.write(`✗ ${e.message}\n`)
+  }
+}
+
+// 5. Підсумок
+console.log(`\n${'─'.repeat(50)}`)
+console.log(`✓ OK: ${stats.ok}  ✗ Err: ${stats.err}`)
+console.log(`  💻 Local (gemma3:4b): ${stats.localOk} файлів`)
+console.log(`  ☁️  Cloud (Claude/pi): ${stats.cloudOk} файлів`)
+if (stats.errors.length > 0) {
+  console.log('Помилки:')
+  stats.errors.forEach(e => console.log(`  - ${e}`))
+}

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

@@ -1,16 +1,22 @@
-/**
- * Stage 0 docgen-конвеєра: детермінована екстракція «факт-листа» з коду (0 токенів LLM).
- *
- * Ідея: винести з-під локальної моделі все, що вона псує (імена експортів, stdlib-vs-internal,
- * крайові деталі поведінки), і віддати їй лише перефразування вже відомих фактів. Тут — суто
- * парсинг JS/MJS регулярками: жодних мереж, LLM чи запису.
- *
- * Повертає об'єкт-факт-лист, який Stage 1 (docgen-prompts) перетворює на точкові промпти.
- */
+/** @see ./docs/docgen-extract.md */
 
 const BUILTIN_MODULES = new Set([
-  'fs', 'path', 'crypto', 'os', 'util', 'stream', 'events', 'http', 'https',
-  'url', 'child_process', 'process', 'assert', 'buffer', 'zlib', 'readline'
+  'fs',
+  'path',
+  'crypto',
+  'os',
+  'util',
+  'stream',
+  'events',
+  'http',
+  'https',
+  'url',
+  'child_process',
+  'process',
+  'assert',
+  'buffer',
+  'zlib',
+  'readline'
 ])
 
 /** Прибирає `/** *​/`-обрамлення й `*`-префікси, повертає чистий текст рядками. */
@@ -40,7 +46,10 @@ function parseJsDoc(raw) {
       params.push({ name: pm[1], desc: desc === 'опис.' ? '' : desc })
       continue
     }
-    if (rm) { ret = rm[1].trim(); continue }
+    if (rm) {
+      ret = rm[1].trim()
+      continue
+    }
     if (l.startsWith('@')) continue
     descLines.push(l)
   }
@@ -81,7 +90,9 @@ function extractExports(src) {
 
 /** Імпорти, класифіковані на stdlib / npm / internal. */
 function extractImports(src) {
-  const stdlib = new Set(), npm = new Set(), internal = new Set()
+  const stdlib = new Set(),
+    npm = new Set(),
+    internal = new Set()
   const re = /^import\s+[\s\S]*?from\s+['"]([^'"]+)['"]/gm
   let m
   while ((m = re.exec(src))) {
@@ -100,10 +111,11 @@ function extractInternalSymbols(src) {
   let m
   while ((m = re.exec(src))) {
     if (m[1]) out.add(m[1].trim())
-    if (m[2]) for (const n of m[2].split(',')) {
-      const name = n.replace(/\s+as\s+.*/, '').trim()
-      if (name) out.add(name)
-    }
+    if (m[2])
+      for (const n of m[2].split(',')) {
+        const name = n.replace(/\s+as\s+.*/, '').trim()
+        if (name) out.add(name)
+      }
   }
   return [...out]
 }
@@ -152,7 +164,10 @@ import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { readFileSync } from 'node:fs'
 if (isRunAsCli(import.meta.url)) {
   const file = process.argv[2]
-  if (!file) { console.error('Usage: node docgen-extract.mjs <file>'); process.exit(1) }
+  if (!file) {
+    console.error('Usage: node docgen-extract.mjs <file>')
+    process.exit(1)
+  }
   const facts = extractFacts(readFileSync(file, 'utf8'), file)
   console.log(JSON.stringify(facts, null, 2))
 }

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

@@ -1,19 +1,4 @@
-/**
- * docgen-конвеєр (входна точка): код файлу → .md-документація.
- *
- * Інверсія керування: веде цей JS, а локальна модель — лише сервіс перефразування.
- *   Stage 0  extractFacts        — факти з коду (0 токенів)
- *   Stage 1  sectionInstructions — точкові промпти на кожну секцію (спільний KV-cached префікс)
- *   Stage 2  stripSignatures     — детермінований зріз сигнатур (0 токенів)
- *   Stage 2.5 scoreDoc           — детермінований скоринг проти фактів (0 токенів)
- *   Stage 3  assemble            — фіксовані заголовки/порядок + зрізання fence
- *   Tier 2   claudeOneShot       — хмарний fallback якщо score < QUALITY_THRESHOLD
- *
- * Hybrid routing (sym-threshold):
- *   sym < BORDERLINE_SYM_LOW          → Tier 1 local (без хмарного рефері)
- *   sym ∈ [BORDERLINE_SYM_LOW, sym<4) → Tier 1 + cloudScoreDoc (Haiku) → при низькому балі → Tier 2
- *   sym >= DEFAULT_SYM_THRESHOLD      → одразу Tier 2 (pre-routing, без local)
- */
+/** @see ./docs/docgen-gen.md */
 import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 import { request } from 'node:http'
@@ -27,16 +12,26 @@ const QUALITY_THRESHOLD = 70
 /** Один виклик чату до ollama зі streaming (токени стримуються → socket активний, жодного timeout). */
 async function ollamaChat(messages, { model, numPredict = 600 }) {
   const body = JSON.stringify({
-    model, messages, stream: true, think: false,
+    model,
+    messages,
+    stream: true,
+    think: false,
     options: { num_ctx: 8192, temperature: 0.2, num_predict: numPredict },
     keep_alive: '15m'
   })
   return new Promise((resolve, reject) => {
     const req = request(
-      { hostname: 'localhost', port: 11434, path: '/api/chat', method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } },
-      (res) => {
-        let text = '', genTok = 0, buf = ''
+      {
+        hostname: 'localhost',
+        port: 11434,
+        path: '/api/chat',
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) }
+      },
+      res => {
+        let text = '',
+          genTok = 0,
+          buf = ''
         res.on('data', chunk => {
           buf += chunk.toString()
           const lines = buf.split('\n')
@@ -47,7 +42,9 @@ async function ollamaChat(messages, { model, numPredict = 600 }) {
               const j = JSON.parse(line)
               text += j.message?.content ?? ''
               if (j.done) genTok = j.eval_count ?? 0
-            } catch { /* partial line */ }
+            } catch {
+              /* partial line */
+            }
           }
         })
         res.on('end', () => resolve({ text, genTok }))
@@ -64,7 +61,10 @@ async function ollamaChat(messages, { model, numPredict = 600 }) {
 function stripSection(text) {
   let t = text.trim()
   if (t.startsWith('```')) {
-    t = t.replace(/^```[a-z]*\n?/, '').replace(/\n?```\s*$/, '').trim()
+    t = t
+      .replace(/^```[a-z]*\n?/, '')
+      .replace(/\n?```\s*$/, '')
+      .trim()
   }
   t = t.replace(/^#{1,6}\s+.*\n+/, '') // зрізати випадковий заголовок
   return t.trim()
@@ -87,8 +87,10 @@ function parseSections(md) {
   let cur = null
   for (const line of md.split('\n')) {
     const m = line.match(/^##\s+(.+)/)
-    if (m) { cur = m[1].toLowerCase().replace(/[^а-яіїєґa-z0-9]/gi, ''); result[cur] = '' }
-    else if (cur) result[cur] += line + '\n'
+    if (m) {
+      cur = m[1].toLowerCase().replace(/[^а-яіїєґa-z0-9]/gi, '')
+      result[cur] = ''
+    } else if (cur) result[cur] += line + '\n'
   }
   return result
 }
@@ -102,25 +104,34 @@ function scoreDoc(md, facts) {
   let score = 100
   const issues = []
 
-  if (!s['огляд'])
-    { score -= 25; issues.push('no-overview') }
+  if (!s['огляд']) {
+    score -= 25
+    issues.push('no-overview')
+  }
 
   const behavior = s['поведінка'] ?? ''
-  if (behavior.length < 60)
-    { score -= 20; issues.push('short-behavior') }
+  if (behavior.length < 60) {
+    score -= 20
+    issues.push('short-behavior')
+  }
 
   const guarantees = s['гарантіїповедінки'] ?? ''
   // Будь-яка згадка "кеш" у Гарантіях коли файл не кешує — галюцинація
   // Негація: "не кешує", "не має кешування", "без кешування", "немає кешу"
   const cacheHit = /кеш/i.test(guarantees) && !/(?:не|без)\s+(?:\S+\s+)?кеш|немає\s+кеш/i.test(guarantees)
-  if (!facts.markers?.caches && cacheHit)
-    { score -= 20; issues.push('cache-hallucination') }
+  if (!facts.markers?.caches && cacheHit) {
+    score -= 20
+    issues.push('cache-hallucination')
+  }
 
   // Перевіряємо лише бектік-обгорнуті імена (`sym`) — уникаємо substring false positives
   const hasName = (text, sym) => text.includes('`' + sym + '`')
   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}`) }
+    if (inDoc) {
+      score -= 10
+      issues.push(`internal-name:${sym}`)
+    }
   }
 
   return { score: Math.max(0, score), issues }
@@ -149,25 +160,29 @@ async function cloudScoreDoc(md, facts, src, model = 'claude-haiku-4-5-20251001'
     facts.markers?.caches ? 'Кешування: є' : 'Кешування: немає',
     facts.markers?.network ? 'Мережа: є' : 'Мережа: немає',
     facts.markers?.readOnly ? 'Read-only (не змінює файли/стан)' : ''
-  ].filter(Boolean).join('\n')
+  ]
+    .filter(Boolean)
+    .join('\n')
 
   const msg = await client.messages.create({
     model,
     max_tokens: 256,
     system: SCORE_RUBRIC,
-    messages: [{
-      role: 'user',
-      content: [
-        { type: 'text', text: `ФАКТИ:\n${factsTxt}`, cache_control: { type: 'ephemeral' } },
-        { type: 'text', text: `КОД:\n\`\`\`\n${src.slice(0, 4000)}\n\`\`\``, cache_control: { type: 'ephemeral' } },
-        { type: 'text', text: `ДОКУМЕНТАЦІЯ:\n${md}` }
-      ]
-    }]
+    messages: [
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: `ФАКТИ:\n${factsTxt}`, cache_control: { type: 'ephemeral' } },
+          { type: 'text', text: `КОД:\n\`\`\`\n${src.slice(0, 4000)}\n\`\`\``, cache_control: { type: 'ephemeral' } },
+          { type: 'text', text: `ДОКУМЕНТАЦІЯ:\n${md}` }
+        ]
+      }
+    ]
   })
   const tok = (msg.usage?.input_tokens ?? 0) + (msg.usage?.output_tokens ?? 0)
   try {
     const j = JSON.parse(msg.content[0]?.text ?? '{}')
-    const total = ((j.огляд ?? 0) + (j.поведінка ?? 0) + (j.гарантії ?? 0) + (j.стиль ?? 0)) / 12 * 100
+    const total = (((j.огляд ?? 0) + (j.поведінка ?? 0) + (j.гарантії ?? 0) + (j.стиль ?? 0)) / 12) * 100
     return { score: Math.round(total), scores: j, issues: j.issues ?? [], tok }
   } catch {
     return { score: 50, scores: {}, issues: ['parse-error'], tok }
@@ -229,31 +244,37 @@ async function generateOneShot(facts, src, model) {
 
 /** Файли з sym ≥ цього значення одразу йдуть у Tier 2 (без локального проходу). */
 const DEFAULT_SYM_THRESHOLD = 4
-/** Файли з sym ≥ цього значення отримують хмарного рефері (Haiku) після локального проходу. */
-const BORDERLINE_SYM_LOW = 2
+/** Максимальний час локальної генерації на один файл перед ескалацією у Tier 2. */
+const LOCAL_TIMEOUT_MS = 5 * 60 * 1000
+
+/** Повертає promise, що відхиляється через `ms` мс з повідомленням про timeout. */
+function withTimeout(promise, ms) {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => setTimeout(() => reject(new Error(`local timeout after ${ms / 1000}s`)), ms))
+  ])
+}
 
 /**
  * Головний API: файл → { md, genTok, ms, score, issues, tier }.
  *
  * Routing (sym-threshold):
- *   sym < BORDERLINE_SYM_LOW                   → Tier 1 (без хмарного рефері)
- *   sym ∈ [BORDERLINE_SYM_LOW, symThreshold)   → Tier 1 + cloudScoreDoc (Haiku) як рефері
- *   sym >= symThreshold                         → Pre-routing одразу Tier 2
- *   scoreCloud=true                             → примусово запускає cloudScoreDoc для всіх Tier 1
+ *   sym < symThreshold  → Tier 1 local (timeout: LOCAL_TIMEOUT_MS) + det-scorer
+ *                       → timeout або det-score < threshold → Tier 2
+ *   sym >= symThreshold → Pre-routing одразу Tier 2
  *
- * @param {string}  scoreModel    — модель для хмарного рефері (Haiku за замовч.)
  * @param {string}  cloudModel    — модель для Tier 2 генерації (Sonnet за замовч.)
- * @param {boolean} scoreCloud    — якщо true, cloudScoreDoc запускається для всіх Tier 1 файлів
  */
-export async function generateDoc(file, {
-  model = 'gemma3:4b',
-  mode = 'orchestrated',
-  scoreModel = 'claude-haiku-4-5-20251001',
-  cloudModel = 'claude-sonnet-4-6',
-  threshold = QUALITY_THRESHOLD,
-  scoreCloud = false,
-  symThreshold = DEFAULT_SYM_THRESHOLD
-} = {}) {
+export async function generateDoc(
+  file,
+  {
+    model = 'gemma3:4b',
+    mode = 'orchestrated',
+    cloudModel = 'claude-sonnet-4-6',
+    threshold = QUALITY_THRESHOLD,
+    symThreshold = DEFAULT_SYM_THRESHOLD
+  } = {}
+) {
   const src = readFileSync(file, 'utf8')
   const facts = extractFacts(src, file)
   const t0 = Date.now()
@@ -262,73 +283,79 @@ export async function generateDoc(file, {
   const complexity = facts.internalSymbols?.length ?? 0
   if (complexity >= symThreshold && env.ANTHROPIC_API_KEY) {
     const r2 = await claudeOneShot(facts, src, cloudModel)
-    return { ...r2, ms: Date.now() - t0, score: null, issues: [`pre-routed:sym=${complexity}`], tier: 2 }
+    return {
+      ...r2,
+      ms: Date.now() - t0,
+      score: null,
+      issues: [`pre-routed:sym=${complexity}`],
+      tier: 2,
+      model: cloudModel
+    }
   }
 
-  let r = facts.unsupported
-    ? await generateOneShot(facts, src, model)
-    : mode === 'oneshot'
-      ? await generateOneShot(facts, src, model)
-      : await generateOrchestrated(facts, src, model)
-
-  // Stage 2.5a: детермінований скоринг (0 токенів)
-  const { score: detScore, issues: detIssues } = scoreDoc(r.md, facts)
-
-  // Stage 2.5b: cloudScoreDoc (Haiku) як рефері для borderline-файлів або при scoreCloud=true
-  const isBorderline = complexity >= BORDERLINE_SYM_LOW && complexity < symThreshold
-  if ((isBorderline || scoreCloud) && env.ANTHROPIC_API_KEY) {
-    const cs = await cloudScoreDoc(r.md, facts, src, scoreModel)
-    if (cs.score < threshold) {
+  // Tier 1: локальна генерація з timeout 5 хв — при перевищенні одразу Tier 2
+  let r
+  try {
+    const localPromise =
+      facts.unsupported || mode === 'oneshot'
+        ? generateOneShot(facts, src, model)
+        : generateOrchestrated(facts, src, model)
+    r = await withTimeout(localPromise, LOCAL_TIMEOUT_MS)
+  } catch (e) {
+    if (env.ANTHROPIC_API_KEY) {
       const r2 = await claudeOneShot(facts, src, cloudModel)
-      return { ...r2, ms: Date.now() - t0, score: cs.score, cloudScores: cs.scores,
-               issues: cs.issues, detScore, detIssues, tier: 2 }
+      return {
+        ...r2,
+        ms: Date.now() - t0,
+        score: null,
+        issues: [`local-timeout: ${e.message}`],
+        tier: 2,
+        model: cloudModel
+      }
     }
-    return { ...r, ms: Date.now() - t0, score: cs.score, cloudScores: cs.scores,
-             issues: cs.issues, detScore, detIssues, tier: 1 }
+    throw e
   }
 
-  // Детермінований fallback (без хмарного рефері)
+  // Stage 2.5: детермінований скоринг (0 токенів) — gate перед Tier 2
+  const { score: detScore, issues: detIssues } = scoreDoc(r.md, facts)
+
   if (detScore < threshold && env.ANTHROPIC_API_KEY) {
     const r2 = await claudeOneShot(facts, src, cloudModel)
-    return { ...r2, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 2 }
+    return { ...r2, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 2, model: cloudModel }
   }
 
-  return { ...r, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 1 }
+  return { ...r, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 1, model }
 }
 
-// CLI: node docgen-gen.mjs <file> [--oneshot] [--score-cloud] [--model <m>] [--score-model <m>] [--sym-threshold N] [--tier-only]
+// CLI: node docgen-gen.mjs <file> [--oneshot] [--model <m>] [--sym-threshold N] [--tier-only]
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 if (isRunAsCli(import.meta.url)) {
   const args = process.argv.slice(2)
   const file = args.find(a => !a.startsWith('--'))
   const mode = args.includes('--oneshot') ? 'oneshot' : 'orchestrated'
-  const scoreCloud = args.includes('--score-cloud')
   const tierOnly = args.includes('--tier-only')
-  const mi = args.indexOf('--model'); const model = mi >= 0 ? args[mi + 1] : 'gemma3:4b'
-  const smi = args.indexOf('--score-model'); const scoreModel = smi >= 0 ? args[smi + 1] : 'claude-haiku-4-5-20251001'
-  const si = args.indexOf('--sym-threshold'); const symThreshold = si >= 0 ? Number(args[si + 1]) : DEFAULT_SYM_THRESHOLD
+  const mi = args.indexOf('--model')
+  const model = mi >= 0 ? args[mi + 1] : 'gemma3:4b'
+  const si = args.indexOf('--sym-threshold')
+  const symThreshold = si >= 0 ? Number(args[si + 1]) : DEFAULT_SYM_THRESHOLD
   if (!file) {
-    console.error('Usage: node docgen-gen.mjs <file> [--oneshot] [--score-cloud] [--model <m>] [--score-model <m>] [--sym-threshold N] [--tier-only]')
+    console.error('Usage: node docgen-gen.mjs <file> [--oneshot] [--model <m>] [--sym-threshold N] [--tier-only]')
     process.exit(1)
   }
   if (tierOnly) {
     const src = readFileSync(file, 'utf8')
     const facts = extractFacts(src, file)
     const sym = facts.internalSymbols?.length ?? 0
-    let label, icon
-    if (sym >= symThreshold) {
-      icon = '☁️ '; label = `Tier 2 cloud   (sym=${sym} ≥ ${symThreshold}, pre-routed)`
-    } else if (sym >= BORDERLINE_SYM_LOW) {
-      icon = '🔀'; label = `Tier 1+judge   (sym=${sym} ∈ [${BORDERLINE_SYM_LOW},${symThreshold}), Haiku рефері)`
-    } else {
-      icon = '💻'; label = `Tier 1 local   (sym=${sym} < ${BORDERLINE_SYM_LOW})`
-    }
+    const icon = sym >= symThreshold ? '☁️ ' : '💻'
+    const label =
+      sym >= symThreshold
+        ? `Tier 2 cloud   (sym=${sym} ≥ ${symThreshold}, pre-routed)`
+        : `Tier 1 local   (sym=${sym} < ${symThreshold})`
     process.stdout.write(`${icon} ${label}  |  ${file}\n`)
     process.exit(0)
   }
-  const r = await generateDoc(file, { model, mode, scoreCloud, scoreModel, symThreshold })
+  const r = await generateDoc(file, { model, mode, symThreshold })
   const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
-  const cloudTxt = r.cloudScores ? ` cloud-scores=${JSON.stringify(r.cloudScores)}` : ''
-  process.stderr.write(`[tier${r.tier} ${mode}] ${r.ms}ms / ${r.genTok} tok / score=${r.score}${issuesTxt}${cloudTxt}\n`)
+  process.stderr.write(`[tier${r.tier} ${mode}] ${r.ms}ms / ${r.genTok} tok / score=${r.score}${issuesTxt}\n`)
   process.stdout.write(r.md)
 }

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

@@ -1,9 +1,4 @@
-/**
- * Глоби, які `docgen` завжди ігнорує.
- *
- * Це окремий snippet-модуль: список правиться тут, scanner лише читає його
- * через predicate. Патерни пишуться в posix-формі відносно кореня проєкту.
- */
+/** @see ./docs/docgen-ignore.md */
 import picomatch from 'picomatch'
 
 /** Базовий список glob-ів для `docgen` ignore. */

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

@@ -1,10 +1,4 @@
-/**
- * Stage 1 docgen-конвеєра: факт-лист + код → точкові промпти на кожну секцію.
- *
- * v2 — СЕКЦІЙНО-МІНІМАЛЬНИЙ контекст: код іде ЛИШЕ у `Поведінку`. `Огляд` бере тільки
- * header, `API` — лише список експортів, `Гарантії` — лише markers. Так інгест коду
- * оплачується один раз (а не на кожну секцію), і оркестрація перестає програвати в часі.
- */
+/** @see ./docs/docgen-prompts.md */
 
 export const STYLE = [
   'Ти технічний письменник. Пишеш лаконічну ПОВЕДІНКОВУ документацію до коду українською, чистим Markdown.',
@@ -28,7 +22,10 @@ function factsSummary(facts) {
   return lines.join('\n')
 }
 
-const msgs = (system, user) => [{ role: 'system', content: system }, { role: 'user', content: user }]
+const msgs = (system, user) => [
+  { role: 'system', content: system },
+  { role: 'user', content: user }
+]
 
 /**
  * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
@@ -42,33 +39,45 @@ export function sectionMessages(facts, src) {
 
   // Огляд — лише факти (без коду)
   out.push({
-    key: 'overview', numPredict: 220,
-    messages: msgs(`${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
-      'Напиши вміст секції «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Без заголовка, без переліку функцій.')
+    key: 'overview',
+    numPredict: 220,
+    messages: msgs(
+      `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
+      'Напиши вміст секції «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Без заголовка, без переліку функцій.'
+    )
   })
 
   // Поведінка — ЄДИНА секція, якій потрібен код
   out.push({
-    key: 'behavior', numPredict: 500,
-    messages: msgs(`${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
-      `Напиши вміст секції «Поведінка»: ${multi ? 'для кожної публічної функції — один короткий пункт «що вона робить»' : 'нумерований алгоритм у бізнес-термінах'}. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${facts.internalSymbols?.length ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.` : ''} Без заголовка.`)
+    key: 'behavior',
+    numPredict: 500,
+    messages: msgs(
+      `${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
+      `Напиши вміст секції «Поведінка»: ${multi ? 'для кожної публічної функції — один короткий пункт «що вона робить»' : 'нумерований алгоритм у бізнес-термінах'}. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${facts.internalSymbols?.length ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.` : ''} Без заголовка.`
+    )
   })
 
   // 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,
-        `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка.`)
+      key: 'api',
+      numPredict: 320,
+      messages: msgs(
+        STYLE,
+        `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка.`
+      )
     })
   }
 
   // Гарантії — лише markers (без коду)
   out.push({
-    key: 'guarantees', numPredict: 300,
-    messages: msgs(`${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
-      'Напиши вміст секції «Гарантії поведінки» як маркери-інваріанти СУВОРО на основі ВІДОМИХ ФАКТІВ (read-only, fail-safe, пропуски). Згадуй кеш ЛИШЕ якщо у фактах прямо є «Кешує». Без сигнатур у дужках і без імен внутрішніх структур/Map-ів/кешів. Не вигадуй гарантій, яких немає у фактах. Без заголовка.')
+    key: 'guarantees',
+    numPredict: 300,
+    messages: msgs(
+      `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}`,
+      'Напиши вміст секції «Гарантії поведінки» як маркери-інваріанти СУВОРО на основі ВІДОМИХ ФАКТІВ (read-only, fail-safe, пропуски). Згадуй кеш ЛИШЕ якщо у фактах прямо є «Кешує». Без сигнатур у дужках і без імен внутрішніх структур/Map-ів/кешів. Не вигадуй гарантій, яких немає у фактах. Без заголовка.'
+    )
   })
 
   return out
@@ -77,8 +86,10 @@ export function sectionMessages(facts, src) {
 /** One-shot messages (база для порівняння). */
 export function oneShotMessages(facts, src) {
   const multi = (facts.exports?.length || 0) > 1
-  return msgs(STYLE,
-    `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``)
+  return msgs(
+    STYLE,
+    `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``
+  )
 }
 
 /** Лише текст user-промпту для one-shot (для хмарного fallback через Anthropic SDK). */

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

@@ -1,11 +1,4 @@
-/**
- * docgen scanner — детермінований обхід проєкту для скілу `docgen`.
- *
- * Друкує JSON-список кодових файлів із відносними `sourcePath`/`docPath`
- * (тека `docs/` поряд із джерелом). Рішення про overwrite/skip приймає скіл —
- * scanner лише лістить і ставить прапор `exists`. LLM/мережі тут немає: уся
- * генерація доки — у субагентах скілу.
- */
+/** @see ./docs/docgen-scan.md */
 // eslint-disable-next-line unicorn/import-style
 import path from 'node:path'
 import { existsSync, readdirSync, statSync } from 'node:fs'