@nitra/cursor 5.0.3 → 5.2.0

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

@@ -1,95 +0,0 @@
-/**
- * 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 cloud = [],
-  local = []
-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 (error) {
-    stats.err++
-    stats.errors.push(f.sourcePath)
-    console.error(`  ✗ ${f.sourcePath}: ${error.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 (error) {
-    stats.err++
-    stats.errors.push(f.sourcePath)
-    process.stdout.write(`✗ ${error.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('Помилки:')
-  for (const e of stats.errors) console.log(`  - ${e}`)
-}

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

@@ -1,95 +0,0 @@
-/**
- * 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-gen.mjs

@@ -1,339 +0,0 @@
-/** @see ./docs/docgen-gen.md */
-import { readFileSync } from 'node:fs'
-import { basename } from 'node:path'
-import { spawnSync } from 'node:child_process'
-import { env } from 'node:process'
-import { resolveModel } from '../../../lib/models.mjs'
-import { extractFacts } from './docgen-extract.mjs'
-import { extractAnchors } from './docgen-extract-anchors.mjs'
-import { oneShotMessages, sectionMessages, criticMessages, refineMessages, guaranteesFromMarkers } from './docgen-prompts.mjs'
-
-const QUALITY_THRESHOLD = 70
-
-/** Прибирає ```-обгортку й випадковий провідний `##`-заголовок із секції. */
-function stripSection(text) {
-  let t = text.trim()
-  if (t.startsWith('```')) {
-    t = t
-      .replace(/^```[a-z]*\n?/, '')
-      .replace(/\n?```\s*$/, '')
-      .trim()
-  }
-  t = t.replace(/^#{1,6}\s+.*\n+/, '') // зрізати випадковий заголовок
-  return t.trim()
-}
-
-/**
- * Stage 2 (детермінований лінт, 0 токенів): зрізає сигнатури `name(args)` → `name`.
- * Два проходи — щоб зняти вкладені виклики на кшталт `check(cwd = process.cwd())`.
- * Не чіпає дужки без ідентифікатора перед ними (напр. `(abie.mdc)`, «(наприклад)»).
- */
-function stripSignatures(text) {
-  let t = text
-  for (let i = 0; i < 2; i++) t = t.replaceAll(/([`\w$.]+)\([^()]*\)/g, '$1')
-  return t
-}
-
-/** Розбиває md на секції за ## заголовками → { огляд, поведінка, api, гарантіїповедінки, … } */
-function parseSections(md) {
-  const result = {}
-  let cur = null
-  for (const line of md.split('\n')) {
-    const m = line.match(/^##\s+(.+)/)
-    if (m) {
-      cur = m[1].toLowerCase().replaceAll(/[^а-яіїєґa-z0-9]/gi, '')
-      result[cur] = ''
-    } else if (cur) result[cur] += line + '\n'
-  }
-  return result
-}
-
-/**
- * Stage 2.5 — детермінований скоринг (0 токенів): перевіряє вихід проти фактів.
- * @returns {{ score: number, issues: string[] }}
- */
-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 = /кеш/i.test(guarantees) && !/(?:не|без)\s+(?:\S+\s+)?кеш|немає\s+кеш/i.test(guarantees)
-  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}`)
-    }
-  }
-
-  return { score: Math.max(0, score), issues }
-}
-
-/**
- * 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',
-    timeout: timeoutMs
-  })
-  if (r.error) throw new Error(`pi error: ${r.error.message}`)
-  if (r.status !== 0) throw new Error(`pi exit ${r.status}: ${r.stderr?.slice(0, 300) ?? ''}`)
-  return r.stdout?.trim() ?? ''
-}
-
-/**
- * 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 = 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 }
-}
-
-/** Stage 3: фіксовані заголовки у фіксованому порядку. */
-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 окремих pi-викликів, по одному на секцію.
- * Код потрапляє лише в `behavior`; решта секцій — на мінімальному факт-листі.
- */
-function piOrchestrated(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 лише для секцій, де 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 }
-}
-
-
-
-/** Файли з sym ≥ цього значення одразу йдуть у Tier 2 (без Tier 1 проходу). */
-const DEFAULT_SYM_THRESHOLD = 4
-/** Максимальний час Tier 1 генерації на один файл перед ескалацією у Tier 2. */
-const LOCAL_TIMEOUT_MS = 5 * 60 * 1000
-/** Дефолтна Tier 1 модель: N_CURSOR_DOCGEN_MODEL → resolveModel('min'). */
-const DEFAULT_LOCAL_MODEL = env.N_CURSOR_DOCGEN_MODEL ?? resolveModel('min')
-/** Дефолтна Tier 2 модель: N_CURSOR_DOCGEN_CLOUD_MODEL → resolveModel('avg'). */
-const DEFAULT_CLOUD_MODEL = env.N_CURSOR_DOCGEN_CLOUD_MODEL ?? resolveModel('avg')
-
-/**
- * Головний API: файл → { md, genTok, ms, score, issues, tier }.
- *
- * Routing (sym-threshold):
- *   sym < symThreshold  → Tier 1 pi(resolveModel('min'), timeout=5хв) + det-scorer
- *                       → timeout або det-score < threshold → Tier 2
- *   sym >= symThreshold → Pre-routing одразу Tier 2
- */
-export async function generateDoc(
-  file,
-  {
-    model = DEFAULT_LOCAL_MODEL,
-    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
-  const complexity = facts.internalSymbols?.length ?? 0
-  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 }
-  }
-
-  // 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, { anchors })
-  } catch (error) {
-    if (cloudModel) {
-      const r2 = piOneShot(facts, src, cloudModel)
-      return { ...r2, ms: Date.now() - t0, score: null, issues: [`tier1-error: ${error.message}`], tier: 2, model: cloudModel }
-    }
-    throw error
-  }
-
-  // Stage 2.5: детермінований скоринг (0 токенів) — gate перед Tier 2
-  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)
-    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, model }
-}
-
-// CLI: node docgen-gen.mjs <file> [--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 tierOnly = args.includes('--tier-only')
-  const mi = args.indexOf('--model')
-  const model = mi !== -1 ? args[mi + 1] : DEFAULT_LOCAL_MODEL
-  const si = args.indexOf('--sym-threshold')
-  const symThreshold = si !== -1 ? Number(args[si + 1]) : DEFAULT_SYM_THRESHOLD
-  if (!file) {
-    console.error('Usage: node docgen-gen.mjs <file> [--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
-    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, symThreshold })
-  const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
-  process.stderr.write(`[tier${r.tier} pi-orchestrated] ${r.ms}ms / score=${r.score}${issuesTxt}\n`)
-  process.stdout.write(r.md)
-}

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

@@ -1,28 +0,0 @@
-# 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

@@ -1,41 +0,0 @@
-# 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

@@ -1,24 +0,0 @@
-# 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`.
-- Результат прогону кешується для подальшого використання.

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

@@ -1,24 +0,0 @@
-# docgen-prompts.mjs
-
-## Огляд
-
-Цей файл містить опис коду для конвеєра docgen. Він визначає точкові промпти для кожної секції коду, що генерується. Це дозволяє ефективно генерувати документацію на основі коду.
-
-## Поведінка
-
-Напиши вміст секції «Поведінка»: для кожної публічної функції — один короткий пункт «що вона робить». Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex. Без заголовка.
-
-## Публічний API
-
-- STYLE — Підготовка документації на першому етапі генерації: створення факт-листа та коду, а потім генерація точкових промптів для кожної секції.
-- v2 — Мінімальний контекст секції: код розміщується лише в `Поведінку`. `Огляд` містить лише заголовок, `API` – список експортів, `Гарантії` – маркери. Це дозволяє один раз обробити інсульт коду, а не секцію за секцією.
-- sectionMessages — Набори повідомлень для кожної секції з мінімальним контекстом. Код розміщується лише в `Поведінку`, решта – на факт-листи.
-- oneShotMessages — База повідомлень для порівняння.
-- oneShotPromptText — Текст user-промпту для one-shot (для резервного копіювання в хмарі через Anthropic SDK).
-
-## Гарантії поведінки
-
-- `docgen-конвеєр` кешує результати генерації промптів для кожної секції.
-- `Огляд` містить лише заголовок секції.
-- `API` містить лише список експортів секції.
-- `Гарантії` містять лише маркери.