@nitra/cursor 3.27.0 → 3.29.0

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

@@ -1,42 +1,45 @@
-/**
- * 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'
+import { spawnSync } from 'node:child_process'
 import { env } from 'node:process'
-import Anthropic from '@anthropic-ai/sdk'
+import { LOCAL_MIN, resolveModel } from '../../../lib/models.mjs'
 import { extractFacts } from './docgen-extract.mjs'
 import { sectionMessages, oneShotMessages, STYLE, oneShotPromptText } from './docgen-prompts.mjs'
 
+/** Strips provider prefix from tier string for direct ollama HTTP (ollama/gemma3:4b → gemma3:4b). */
+function localModelId(tier) {
+  if (!tier) return 'gemma3:4b'
+  const i = tier.indexOf('/')
+  return i === -1 ? tier : tier.slice(i + 1)
+}
+
 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 +50,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 +69,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 +95,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,93 +112,53 @@ 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 }
 }
 
-const SCORE_RUBRIC = `Оціни якість документації для JavaScript-модуля за 4 критеріями (1-3 кожен):
-
-- огляд: 3=описує роль модуля в системі (ЩО і НАВІЩО); 2=частково розмитий; 1=відсутній або перераховує функції
-- поведінка: 3=бізнес-терміни, без деталей реалізації; 2=деякі impl-деталі; 1=переважно реалізація або відсутня
-- гарантії: 3=лише реальні інваріанти підтверджені кодом, без галюцинацій; 2=частково правильні; 1=вигадані або відсутні
-- стиль: 3=без сигнатур/internal-імен, правильна markdown-структура; 2=дрібні порушення; 1=сигнатури/internal-імена/відсутні заголовки
-
-Відповідай ТІЛЬКИ JSON без пояснень:
-{"огляд":N,"поведінка":N,"гарантії":N,"стиль":N,"issues":["коротко про кожен мінус 1-5 слів"]}`
-
-/**
- * Stage 2.5 cloud: Claude Haiku оцінює якість доку проти коду + фактів.
- * Використовує найдешевшу хмарну модель — haiku — для мінімальної вартості судді.
- * @returns {{ score: number, scores: object, issues: string[], tok: number }}
- */
-async function cloudScoreDoc(md, facts, src, model = 'claude-haiku-4-5-20251001') {
-  const client = new Anthropic()
-  const factsTxt = [
-    facts.exports?.length ? `Публічні функції: ${facts.exports.map(e => e.name).join(', ')}` : '',
-    facts.internalSymbols?.length ? `Внутрішні (не публічні): ${facts.internalSymbols.join(', ')}` : '',
-    facts.markers?.caches ? 'Кешування: є' : 'Кешування: немає',
-    facts.markers?.network ? 'Мережа: є' : 'Мережа: немає',
-    facts.markers?.readOnly ? 'Read-only (не змінює файли/стан)' : ''
-  ].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}` }
-      ]
-    }]
-  })
-  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
-    return { score: Math.round(total), scores: j, issues: j.issues ?? [], tok }
-  } catch {
-    return { score: 50, scores: {}, issues: ['parse-error'], tok }
-  }
-}
-
-/** Tier 2: хмарний fallback через Claude коли local-score < QUALITY_THRESHOLD. */
-async function claudeOneShot(facts, src, model = 'claude-sonnet-4-6') {
-  const client = new Anthropic()
-  const prompt = oneShotPromptText(facts, src)
-  const msg = await client.messages.create({
-    model,
-    max_tokens: 1500,
-    system: STYLE,
-    messages: [{ role: 'user', content: prompt }]
+/** Tier 2: виклик через pi (провайдер-нейтрально). model — рядок `provider/model-id`. */
+function piOneShot(facts, src, model) {
+  const fullPrompt = `${STYLE}\n\n${oneShotPromptText(facts, src)}`
+  const modelArgs = model ? ['--model', model] : []
+  const r = spawnSync('pi', ['-p', fullPrompt, ...modelArgs, '--no-session', '--mode', 'text', '--no-tools'], {
+    encoding: 'utf8',
+    timeout: 120_000
   })
-  const text = msg.content[0]?.text ?? ''
-  const genTok = msg.usage?.output_tokens ?? 0
+  if (r.error) throw new Error(`pi Tier 2 error: ${r.error.message}`)
+  if (r.status !== 0) throw new Error(`pi Tier 2 exit ${r.status}: ${r.stderr?.slice(0, 300) ?? ''}`)
+  const text = r.stdout?.trim() ?? ''
   let md = stripSignatures(stripSection(text))
   if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
-  return { md: md + '\n', genTok }
+  return { md: md + '\n', genTok: 0 }
 }
 
 /** Stage 3: фіксовані заголовки у фіксованому порядку. */
@@ -229,106 +199,122 @@ 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
+/** Дефолтна Tier 1 модель: N_CURSOR_DOCGEN_MODEL → LOCAL_MIN → ollama gemma3:4b. */
+const DEFAULT_LOCAL_MODEL = localModelId(env.N_CURSOR_DOCGEN_MODEL ?? LOCAL_MIN)
+/** Дефолтна Tier 2 модель (provider/model-id для pi): N_CURSOR_DOCGEN_CLOUD_MODEL → resolveModel('avg'). */
+const DEFAULT_CLOUD_MODEL = env.N_CURSOR_DOCGEN_CLOUD_MODEL ?? resolveModel('avg')
+
+/** Повертає 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 = DEFAULT_LOCAL_MODEL,
+    mode = 'orchestrated',
+    cloudModel = DEFAULT_CLOUD_MODEL,
+    threshold = QUALITY_THRESHOLD,
+    symThreshold = DEFAULT_SYM_THRESHOLD
+  } = {}
+) {
   const src = readFileSync(file, 'utf8')
   const facts = extractFacts(src, file)
   const t0 = Date.now()
 
   // Pre-routing: складні файли (sym ≥ symThreshold) → одразу Tier 2, не витрачаємо local-час
   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 }
+  if (complexity >= symThreshold && cloudModel) {
+    const r2 = piOneShot(facts, src, cloudModel)
+    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) {
-      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 }
+  // 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 (cloudModel) {
+      const r2 = piOneShot(facts, src, cloudModel)
+      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 (без хмарного рефері)
-  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 }
+  // Stage 2.5: детермінований скоринг (0 токенів) — gate перед Tier 2
+  const { score: detScore, issues: detIssues } = scoreDoc(r.md, facts)
+
+  if (detScore < threshold && cloudModel) {
+    const r2 = piOneShot(facts, src, cloudModel)
+    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] : DEFAULT_LOCAL_MODEL
+  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'

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

@@ -0,0 +1,28 @@
+# docgen-extract.mjs
+
+## Огляд
+
+Файл `extractFacts` витягує інформацію про поведінку коду, формуючи об'єкт "факт-лист". Цей факт-лист використовується Stage 1 docgen-конвеєра для створення точкових промптів. Функція є ключовою частиною детермінованого процесу генерації документації, виключаючи використання великих мовних моделей.
+
+## Поведінка
+
+1.  **Обробка даних:** Система аналізує код, витягуючи інформацію про експортовані функції, імпорти та їхні описи.
+2.  **Ідентифікація відхилень:** Система визначає, чи використовується код для виконання операцій, які можуть призвести до помилок, наприклад, запис у файли, створення директорій, видалення файлів, обробка мережевих запитів або використання try/catch блоків.
+3.  **Виявлення пропущених шляхів:** Система виявляє, чи використовується код для обробки певних шляхів файлів, таких як `.github`, `.git`, `node_modules` або `base/`, `ua/`, `.firebase`.
+4.  **Визначення кешування:** Система визначає, чи використовується код для кешування даних, наприклад, за допомогою Map або Cache.
+5.  **Визначення відсутності обробки помилок:** Система визначає, чи використовується код для обробки помилок, наприклад, за допомогою try/catch блоків.
+6.  **Визначення мережевих операцій:** Система визначає, чи використовується код для виконання мережевих операцій, наприклад, за допомогою fetch або axios.
+7.  **Вихідні дані:** Система надає вихідні дані у вигляді об'єкта, що містить витягнуту інформацію про код, а також виявлені відхилення та пропущені шляхи.
+
+## Публічний API
+
+extractFacts — Витягує факти з коду файлу, представляючи їх у вигляді списку.
+
+## Гарантії поведінки
+
+- Екстрагує з коду список фактів.
+- Повертає об'єкт з витягнутими фактами.
+- Не викликає винятків при невдачі.
+- Кешує результати для одного прогону.
+- Не використовує мережу.
+- Не обробляє файли/каталоги .github, .git, node_modules, base/, ua/, .firebase.

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

@@ -0,0 +1,41 @@
+# docgen-gen.mjs
+
+## Огляд
+
+Цей файл генерує документацію на основі коду, використовуючи конвеєр обробки. Він автоматично створює Markdown-файли, що містять опис коду, використовуючи декілька етапів, включаючи вилучення фактів та створення текстових описів. Ця функція є ключовою частиною системи документування, забезпечуючи автоматизований та послідовний процес створення документації.
+
+## Поведінка
+
+1.  Модуль визначає основну функцію `generateDoc`, яка приймає код джерела та налаштовує параметри для генерації документації.
+2.  Вхідний код обробляється для вилучення ключових фактів про функціональність модуля, включаючи назви функцій та їх призначення.
+3.  Вилучені факти використовуються для оцінки якості документації, зокрема, перевіряється, чи опис відповідає реальній поведінці модуля.
+4.  Оцінка якості здійснюється за допомогою декількох критеріїв: опис має бути чітким та описовим, а поведінка – узгодженою з кодом.
+5.  Якщо оцінка якості низька, використовується хмарний сервіс Claude для перевірки документації та надання рекомендацій щодо покращення.
+6.  У випадку, коли оцінка якості висока, генерується документ, який містить огляд модуля, його поведінку, API та гарантії поведінки.
+7.  Документація форматується у Markdown, з використанням фіксованого набору заголовків та розділів.
+8.  Під час генерації документації враховуються можливі пропуски в інформації про шляхи, що може вплинути на оцінку якості.
+9.  Використовується хмарний сервіс Claude для оцінки якості документації та надання рекомендацій щодо покращення.
+10. Генерується документ, який містить огляд модуля, його поведінку, API та гарантії поведінки.
+
+## Публічний API
+
+- generateDoc — Генерує документацію з файлу, включаючи метадані, токени, оцінки, проблеми та рівень.
+- Routing (sym-threshold) — Розподіляє обробку на основі значення символу, визначаючи рівень (Tier) та тип рефері (Haiku або без хмарного рефері).
+  - sym < BORDERLINE_SYM_LOW — Tier 1 без хмарного рефері.
+  - sym ∈ [BORDERLINE_SYM_LOW, symThreshold) — Tier 1 з хмарним рефері (Haiku).
+  - sym >= symThreshold — Відразу Tier 2.
+  - scoreCloud=true — Автоматично запускає хмарний рефері для всіх Tier 1.
+
+## Гарантії поведінки
+
+- Конвеєр завжди генерує .md-документацію на основі вхідного коду.
+- Конвеєр використовує інверсію керування, де JS-код визначає весь процес.
+- Stage 0 (extractFacts) не впливає на вихідну документацію.
+- Stage 1 (sectionInstructions) генерує точкові промпти для кожної секції коду.
+- Stage 2 (stripSignatures) завжди видаляє інформацію про сигнатури.
+- Stage 2.5 (scoreDoc) оцінює документацію за фактами.
+- Stage 3 (assemble) збирає документацію з фіксованими заголовками та порядком.
+- При низькому балі скорингу (claudeOneShot) використовується хмарний сервіс для перефразування.
+- При сим-значенні нижче BORDERLINE_SYM_LOW, документація генерується локально без використання хмарного рефері.
+- При сим-значенні між BORDERLINE_SYM_LOW та DEFAULT_SYM_THRESHOLD, документація генерується локально та оцінюється за допомогою cloudScoreDoc (Haiku).
+- При сим-значенні, що перевищує DEFAULT_SYM_THRESHOLD, документація генерується безпосередньо, без локальної оцінки

package/skills/docgen/js/docs/docgen-ignore.md

@@ -0,0 +1,24 @@
+# docgen-ignore.mjs
+
+## Огляд
+
+Цей файл містить список глобальних файлів, які `docgen` ігнорує під час генерації документації. Він використовується для визначення, які файли не потрібно аналізувати, забезпечуючи ефективність процесу генерації та запобігаючи включенню нерелевантної інформації. Цей список є основою для predicate, який scanner використовує для визначення, чи потрібно читати певний файл.
+
+## Поведінка
+
+DOCGEN_IGNORE_GLOBS: визначає список глобів, які `docgen` ігнорує.
+isDocgenIgnored: перевіряє, чи шлях має бути пропущений `docgen`, використовуючи глоби.
+
+## Публічний API
+
+- DOCGEN_IGNORE_GLOBS — Список glob-ів, які ігнорує `docgen`.
+- isDocgenIgnored — Перевіряє, чи потрібно пропустити шлях під час генерації документації.
+
+## Гарантії поведінки
+
+- `DOCGEN_IGNORE_GLOBS` завжди ігнорує певний набір шляхів.
+- `isDocgenIgnored` повертає `true` якщо шлях ігнорується.
+- Шляхи `.git` та `node_modules` завжди ігноруються.
+- Файл є read-only.
+- У разі невдачі повертає `false` або `null`.
+- Результат прогону кешується для подальшого використання.