@nitra/cursor 9.1.1 → 9.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [9.2.0] - 2026-06-14
+
+### Changed
+
+- docgen: класифікація omlx-збоїв (transient/systemic/permanent) — ретрай ETIMEDOUT з backoff, circuit-breaker на systemic-каскад (exit 2), permanent→skip; scan поважає .gitignore; прибрано хардкод DEFAULT_OMLX_MODEL (fail-loud, модель через N_LOCAL_MIN_MODEL)
+
 ## [9.1.1] - 2026-06-14
 
 ### Changed

package/lib/llm.mjs

@@ -121,6 +121,26 @@ export function callLlm(messages, model, opts = {}) {
 const MEMORY_GUARD_MARKER = 'memory ceiling'
 /** Тип помилки omlx про відсутній/хибний API-ключ. */
 const AUTH_ERROR_MARKER = 'authentication_error'
+/** Детерміновані помилки: контекст/модель — ретрай чи чекання не допоможе. */
+const PERMANENT_RE = /too long|exceeds[^.]*context|not found/i
+
+/**
+ * Класифікує omlx-помилку **після** того, як `callOmlxRaw` вичерпав внутрішні
+ * ретраї — для реакції оркестратора (skip vs circuit-breaker vs звичайна помилка):
+ *   - `permanent` — детерміновано (контекст завеликий, модель відсутня): skip, не ретраїти;
+ *   - `systemic`  — середовище/сервер (memory-guard, auth, down/таймаут): каскадить → circuit-breaker;
+ *   - `transient` — решта (empty content, bad json): рідкісне, не каскадить.
+ * @param {string} message текст `error.message`
+ * @returns {'transient'|'systemic'|'permanent'} клас помилки
+ */
+export function classifyOmlxError(message) {
+  const m = String(message)
+  if (PERMANENT_RE.test(m)) return 'permanent'
+  if (m.includes(MEMORY_GUARD_MARKER) || m.includes(AUTH_ERROR_MARKER) || m.startsWith('omlx curl')) {
+    return 'systemic'
+  }
+  return 'transient'
+}
 
 /**
  * Preflight-перевірка omlx перед масовим прогоном: мінімальний chat-виклик

package/lib/omlx.mjs

@@ -45,11 +45,20 @@ export function resolveOmlxApiKey(apiKey) {
   }
 }
 
-/** Дефолтна модель, якщо в id лишився голий `omlx/` (override — `N_CURSOR_OMLX_MODEL`). */
-export const DEFAULT_OMLX_MODEL = 'mlx-community--gemma-4-e2b-it-4bit'
-
 const OMLX_PREFIX = 'omlx/'
 
+/** Backoff між transient-ретраями curl (мс): 2 паузи на 3 спроби. */
+const BACKOFF_MS = [2000, 8000]
+
+/**
+ * Блокуюча пауза без зайнятого циклу (sync — для retry-loop у `callOmlxRaw`).
+ * @param {number} ms тривалість паузи
+ * @returns {void}
+ */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
 /**
  * Чи цей model-id адресує локальний omlx-бекенд (префікс `omlx/`).
  * @param {unknown} model перевірюваний model-id
@@ -92,15 +101,38 @@ export function extractReasoning(message, finishReason) {
   return { reasoning: null, reasoningSource: null }
 }
 
+/**
+ * Парсить успішну (curl-exit 0) omlx-відповідь у багатий обʼєкт.
+ * @param {string} stdout сире тіло відповіді curl
+ * @param {number} attempt номер успішної спроби (для поля `attempts`)
+ * @returns {{ content:string, reasoning:string|null, reasoningSource:string|null, finishReason:string|null, usage:object|null, attempts:number }} багатий результат
+ * @throws {Error} на поганому JSON, api-помилці чи порожньому контенті
+ */
+function parseOmlxResponse(stdout, attempt) {
+  let j
+  try {
+    j = JSON.parse(stdout)
+  } catch {
+    throw new Error(`omlx bad json: ${stdout?.slice(0, 200) ?? ''}`)
+  }
+  if (j.error) throw new Error(`omlx api: ${JSON.stringify(j.error).slice(0, 300)}`)
+  const message = j.choices?.[0]?.message ?? {}
+  const finishReason = j.choices?.[0]?.finish_reason ?? null
+  const content = message.content?.trim() ?? ''
+  if (!content) throw new Error(`omlx empty content (finish=${finishReason})`)
+  const { reasoning, reasoningSource } = extractReasoning(message, finishReason)
+  return { content, reasoning, reasoningSource, finishReason, usage: j.usage ?? null, attempts: attempt }
+}
+
 /**
  * Ядро прямого HTTP-виклику до omlx через `curl` (spawnSync). Повертає **багатий**
  * обʼєкт: контент + reasoning + usage + finish_reason + кількість спроб. Ретраїть
- * лише transient curl-помилки (18 = transfer closed, 52 = empty reply, 56 = recv failure).
+ * transient-помилки (curl 18/28/52/56 + spawnSync ETIMEDOUT) із backoff 2s→8s.
  * @param {Array<{role:string, content:string}>} messages OpenAI-messages (system+user збережено)
- * @param {string} model model-id (з/без `omlx/`-префікса); порожній → дефолт
- * @param {{ url?: string, timeoutMs?: number, temperature?: number, maxTokens?: number, fallbackModel?: string, apiKey?: string }} [opts] URL, timeout, температура, ліміт виходу, fallback-модель, API-ключ
+ * @param {string} model model-id (з/без `omlx/`-префікса); порожній і без `fallbackModel` → throw
+ * @param {{ url?: string, timeoutMs?: number, temperature?: number, maxTokens?: number, fallbackModel?: string, apiKey?: string, backoffMs?: number[] }} [opts] URL, timeout, температура, ліміт виходу, fallback-модель, API-ключ, backoff між ретраями (мс)
  * @returns {{ content:string, reasoning:string|null, reasoningSource:string|null, finishReason:string|null, usage:object|null, attempts:number }} багатий результат виклику
- * @throws на curl-помилці, не-200 exit, поганому JSON чи порожньому контенті
+ * @throws {Error} на curl-помилці, не-200 exit, поганому JSON чи порожньому контенті
  */
 export function callOmlxRaw(messages, model, opts = {}) {
   const {
@@ -108,18 +140,23 @@ export function callOmlxRaw(messages, model, opts = {}) {
     timeoutMs = 60_000,
     temperature = 0.2,
     maxTokens = 4096,
-    fallbackModel = env.N_CURSOR_OMLX_MODEL ?? DEFAULT_OMLX_MODEL,
-    apiKey
+    fallbackModel = env.N_CURSOR_OMLX_MODEL ?? '',
+    apiKey,
+    backoffMs = BACKOFF_MS
   } = opts
 
   const m = omlxModelId(model) || fallbackModel
+  if (!m) {
+    throw new Error('omlx: модель не задано — постав N_LOCAL_MIN_MODEL (або N_CURSOR_OMLX_MODEL)')
+  }
   const body = JSON.stringify({ model: m, messages, max_tokens: maxTokens, temperature })
   // Ключ локального сервера в argv допустимий: localhost-секрет власної машини,
   // короткоживучий процес; stdin уже зайнятий body (`--data-binary @-`).
   const key = resolveOmlxApiKey(apiKey)
   const authArgs = key ? ['-H', `Authorization: Bearer ${key}`] : []
 
-  const TRANSIENT_CURL_CODES = new Set([18, 52, 56])
+  // 18=transfer closed, 28=operation timeout, 52=empty reply, 56=recv failure — усі transient.
+  const TRANSIENT_CURL_CODES = new Set([18, 28, 52, 56])
   let lastErr
   for (let attempt = 1; attempt <= 3; attempt++) {
     const r = spawnSync(
@@ -143,28 +180,22 @@ export function callOmlxRaw(messages, model, opts = {}) {
     )
     if (r.error) {
       lastErr = new Error(`omlx curl error: ${r.error.message}`)
+      // spawnSync-таймаут (ETIMEDOUT) — transient: сервер перевантажений, ретраїмо з backoff.
+      if (r.error.code === 'ETIMEDOUT' && attempt < 3) {
+        sleepSync(backoffMs[attempt - 1])
+        continue
+      }
       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})`)
+        sleepSync(backoffMs[attempt - 1])
         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 message = j.choices?.[0]?.message ?? {}
-    const finishReason = j.choices?.[0]?.finish_reason ?? null
-    const content = message.content?.trim() ?? ''
-    if (!content) throw new Error(`omlx empty content (finish=${finishReason})`)
-    const { reasoning, reasoningSource } = extractReasoning(message, finishReason)
-    return { content, reasoning, reasoningSource, finishReason, usage: j.usage ?? null, attempts: attempt }
+    return parseOmlxResponse(r.stdout, attempt)
   }
   throw lastErr ?? new Error('omlx unknown failure')
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "9.1.1",
+  "version": "9.2.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/doc-files/js/docgen-crc.mjs

@@ -20,9 +20,14 @@
  *   docgen:
  *     source: src/lib/foo.js
  *     crc: a3f1c9e0
+ *     model: omlx/gemma-4-e4b-it-OptiQ-4bit
  *     score: 55
  *     issues: short-behavior,internal-name:bar
  *   ---
+ *
+ * `model` — повний id моделі-генератора (як повертає resolveModel, із префіксом
+ * провайдера). Пасивна метадата: маркер «віку» доки за моделлю на додачу до CRC
+ * джерела. На staleness НЕ впливає — звіряється лише `crc`.
  */
 import { existsSync, readFileSync } from 'node:fs'
 import { crc32 as zlibCrc32 } from 'node:zlib'
@@ -46,6 +51,7 @@ export function crc32(input) {
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/u
 const SOURCE_RE = /^[ \t]{0,8}source:[ \t]{0,8}(.+)$/mu
 const CRC_RE = /^[ \t]{0,8}crc:[ \t]{0,8}(.+)$/mu
+const MODEL_RE = /^[ \t]{0,8}model:[ \t]{0,8}(.+)$/mu
 const SCORE_RE = /^[ \t]{0,8}score:[ \t]{0,8}(\d+)$/mu
 const ISSUES_RE = /^[ \t]{0,8}issues:[ \t]{0,8}(.+)$/mu
 const LEADING_NEWLINES_RE = /^\n+/u
@@ -53,10 +59,10 @@ const ISSUE_CODE_TAIL_RE = /[,:]$/u
 
 /**
  * Парсить frontmatter файлової доки. Без блоку — `data:null` і `body` дорівнює входу.
- * Поля `score`/`issues` опційні (back-compat зі старими доками): без них —
- * `score:null`, `issues:[]`.
+ * Поля `model`/`score`/`issues` опційні (back-compat зі старими доками): без них —
+ * `model:null`, `score:null`, `issues:[]`.
  * @param {string} md вміст md-файлу
- * @returns {{ data: { source: string|null, crc: string|null, score: number|null, issues: string[] }|null, body: string }} метадані + тіло без frontmatter
+ * @returns {{ data: { source: string|null, crc: string|null, model: string|null, score: number|null, issues: string[] }|null, body: string }} метадані + тіло без frontmatter
  */
 export function parseDocFrontmatter(md) {
   const match = md.match(FRONTMATTER_RE)
@@ -68,6 +74,7 @@ export function parseDocFrontmatter(md) {
     data: {
       source: block.match(SOURCE_RE)?.[1].trim() ?? null,
       crc: block.match(CRC_RE)?.[1].trim() ?? null,
+      model: block.match(MODEL_RE)?.[1].trim() ?? null,
       score: scoreRaw === undefined ? null : Number(scoreRaw),
       issues: issuesRaw
         ? issuesRaw
@@ -97,14 +104,16 @@ function issueCodes(issues) {
 }
 
 /**
- * Будує frontmatter-блок із шляхом джерела, CRC і (опційно) якістю.
+ * Будує frontmatter-блок із шляхом джерела, CRC, (опційно) моделлю-генератором і якістю.
  * @param {string} source відносний шлях джерела
  * @param {string} crc CRC32 джерела у hex
  * @param {{ score: number, issues?: string[] }|null} [quality] det-оцінка доки; null — без полів якості
- * @returns {string} рядок `---\ndocgen:\n  source: …\n  crc: …[\n  score: …][\n  issues: …]\n---\n`
+ * @param {string|null} [model] повний id моделі-генератора; null — без поля `model`
+ * @returns {string} рядок `---\ndocgen:\n  source: …\n  crc: …[\n  model: …][\n  score: …][\n  issues: …]\n---\n`
  */
-export function buildDocFrontmatter(source, crc, quality = null) {
+export function buildDocFrontmatter(source, crc, quality = null, model = null) {
   const lines = [`source: ${source}`, `crc: ${crc}`]
+  if (model) lines.push(`model: ${model}`)
   if (quality && typeof quality.score === 'number') {
     lines.push(`score: ${quality.score}`)
     const codes = issueCodes(quality.issues ?? [])
@@ -120,11 +129,12 @@ export function buildDocFrontmatter(source, crc, quality = null) {
  * @param {string} source відносний шлях джерела
  * @param {string} crc CRC32 джерела у hex
  * @param {{ score: number, issues?: string[] }|null} [quality] det-оцінка доки
+ * @param {string|null} [model] повний id моделі-генератора; null — без поля `model`
  * @returns {string} md зі свіжим frontmatter
  */
-export function stampDoc(md, source, crc, quality = null) {
+export function stampDoc(md, source, crc, quality = null, model = null) {
   const { body } = parseDocFrontmatter(md)
-  return `${buildDocFrontmatter(source, crc, quality)}\n${body.replace(LEADING_NEWLINES_RE, '')}`
+  return `${buildDocFrontmatter(source, crc, quality, model)}\n${body.replace(LEADING_NEWLINES_RE, '')}`
 }
 
 /**
@@ -148,6 +158,17 @@ export function readDocQuality(docAbsPath) {
   return { score: data?.score ?? null, issues: data?.issues ?? [] }
 }
 
+/**
+ * Модель-генератор, збережена у frontmatter доки; `null` — доки немає або поле відсутнє
+ * (старі доки до введення `model`).
+ * @param {string} docAbsPath абсолютний шлях md-доки
+ * @returns {string|null} повний id моделі або null
+ */
+export function readDocModel(docAbsPath) {
+  if (!existsSync(docAbsPath)) return null
+  return parseDocFrontmatter(readFileSync(docAbsPath, 'utf8')).data?.model ?? null
+}
+
 /**
  * Стан застарілості доки відносно її джерела.
  * `missing` — доки немає; `crc-mismatch` — CRC джерела ≠ CRC у доці; інакше свіжа.

package/rules/doc-files/js/docgen-files-batch.mjs

@@ -10,13 +10,13 @@
  * Перед масовим прогоном — health-check omlx: memory-guard зайнятої 8GB машини
  * означає «відклади прогін», а не сотні хибних «✗» у звіті.
  */
-import { readFileSync, mkdirSync, writeFileSync, existsSync } from 'node:fs'
+import { readFileSync, mkdirSync, writeFileSync, existsSync, statSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
-import { omlxHealthCheck, pickBackend } from '../../../lib/llm.mjs'
+import { omlxHealthCheck, pickBackend, classifyOmlxError } from '../../../lib/llm.mjs'
 import { generateDoc, DEFAULT_LOCAL_MODEL } from './docgen-gen.mjs'
-import { crc32, stampDoc, readDocQuality, QUALITY_THRESHOLD } from './docgen-crc.mjs'
+import { crc32, stampDoc, readDocQuality, readDocModel, QUALITY_THRESHOLD } from './docgen-crc.mjs'
 import { resolveRoot, scanForDocFiles } from './docgen-scan.mjs'
 
 /**
@@ -64,6 +64,9 @@ function selectTargets(root, all, { overwrite, retryDegraded }) {
  * @returns {string|null} текст фатальної проблеми або null якщо можна генерувати
  */
 function preflightProblem() {
+  if (!DEFAULT_LOCAL_MODEL) {
+    return 'модель не задано. Вистав N_LOCAL_MIN_MODEL (напр. omlx/mlx-community--gemma-4-e4b-it-OptiQ-4bit) і повтори.'
+  }
   if (pickBackend(DEFAULT_LOCAL_MODEL) !== 'omlx') return null
   const hc = omlxHealthCheck({ model: DEFAULT_LOCAL_MODEL })
   if (hc.ok) return null
@@ -103,17 +106,39 @@ function fmtTiming(r) {
   return `${s(r.ms)} (llm ${s(llmMs)}/${r.llmCalls ?? 0} calls, orch ${s(r.ms - llmMs)})`
 }
 
+/** Скільки systemic-збоїв підряд → негайний abort батчу (fail-fast, без cooldown). */
+const SYSTEMIC_ABORT_STREAK = 3
+
+/**
+ * Діагностика розміру джерела (для дослідження, що роздуває контекст):
+ * байти + груба оцінка токенів (~bytes/4). Без size-guard-гейта — лише вивід.
+ * @param {number} bytes розмір файлу в байтах
+ * @returns {string} напр. `12.3KB ~3.1k tok`
+ */
+function fmtSize(bytes) {
+  return `${(bytes / 1024).toFixed(1)}KB ~${(bytes / 4 / 1000).toFixed(1)}k tok`
+}
+
 /**
  * Генерує й штампує доку для одного файлу, оновлюючи лічильники й прогрес.
+ * Помилку класифікує (`classifyOmlxError`): `permanent` → skip (не «помилка для
+ * перегону»), `systemic`/`transient` → у `errors`. Повертає клас для циклу
+ * (circuit-breaker рахує systemic-підряд).
  * @param {object} file елемент scanForDocFiles
  * @param {string} root абсолютний корінь
  * @param {{ done: number, total: number }} progress позиція у прогресі
- * @param {{ ok: number, degraded: number, err: number, errors: string[] }} stats акумулятор статистики
- * @returns {Promise<void>}
+ * @param {{ ok: number, degraded: number, err: number, errors: string[], skipped: string[] }} stats акумулятор
+ * @returns {Promise<'ok'|'permanent'|'systemic'|'transient'>} результат для керування циклом
  */
 async function generateOne(file, root, progress, stats) {
   const sourceAbs = join(root, file.sourcePath)
-  process.stdout.write(`  [${progress.done}/${progress.total}] ${file.sourcePath} … `)
+  let size = 0
+  try {
+    size = statSync(sourceAbs).size
+  } catch {
+    // файл зник між скануванням і генерацією — лишаємо розмір 0
+  }
+  process.stdout.write(`  [${progress.done}/${progress.total}] ${file.sourcePath} [${fmtSize(size)}] … `)
   try {
     const docAbs = join(root, file.docPath)
     // Варіант B: передаємо наявну доку, щоб зберегти захищену секцію «Призначення»
@@ -123,7 +148,7 @@ async function generateOne(file, root, progress, stats) {
     mkdirSync(dirname(docAbs), { recursive: true })
     const quality =
       result.score === null ? null : { score: result.score, issues: result.degraded ? result.issues : [] }
-    writeFileSync(docAbs, stampDoc(result.md, file.sourcePath, crc, quality))
+    writeFileSync(docAbs, stampDoc(result.md, file.sourcePath, crc, quality, result.model))
     stats.ok++
     if (result.degraded) {
       stats.degraded++
@@ -131,24 +156,38 @@ async function generateOne(file, root, progress, stats) {
     } else {
       process.stdout.write(`✓ score=${result.score ?? '—'} crc=${crc}  ${fmtTiming(result)}\n`)
     }
+    return 'ok'
   } catch (error) {
-    stats.err++
-    stats.errors.push(file.sourcePath)
-    process.stdout.write(`✗ ${error.message}\n`)
+    const cls = classifyOmlxError(error.message)
+    if (cls === 'permanent') {
+      stats.skipped.push(file.sourcePath)
+      process.stdout.write(`⊘ skip (permanent): ${error.message}\n`)
+    } else {
+      stats.err++
+      stats.errors.push(file.sourcePath)
+      process.stdout.write(`✗ ${cls}: ${error.message}\n`)
+    }
+    return cls
   }
 }
 
 /**
  * Підсумковий звіт прогону у stdout.
- * @param {{ ok: number, degraded: number, err: number, errors: string[] }} stats статистика
+ * @param {{ ok: number, degraded: number, err: number, errors: string[], skipped: string[] }} stats статистика
  * @returns {void}
  */
 function reportStats(stats) {
-  console.log(`\n${'─'.repeat(50)}\n✓ OK: ${stats.ok}  ⚠ degraded: ${stats.degraded}  ✗ Err: ${stats.err}`)
+  console.log(
+    `\n${'─'.repeat(50)}\n✓ OK: ${stats.ok}  ⚠ degraded: ${stats.degraded}  ✗ Err: ${stats.err}  ⊘ Skip: ${stats.skipped.length}`
+  )
   if (stats.errors.length > 0) {
     console.log('Помилки:')
     for (const e of stats.errors) console.log(`  - ${e}`)
   }
+  if (stats.skipped.length > 0) {
+    console.log('Пропущено (permanent — завеликий контекст / модель відсутня):')
+    for (const e of stats.skipped) console.log(`  - ${e}`)
+  }
   if (stats.degraded > 0) {
     console.log(`Degraded-доки перегенеровуються пізніше: npx @nitra/cursor fix-doc-files --retry-degraded`)
   }
@@ -157,7 +196,7 @@ function reportStats(stats) {
 /**
  * `doc-files gen` — згенерувати документацію для застарілих/відсутніх док.
  * @param {string[]} argv аргументи після назви субкоманди
- * @returns {Promise<number>} exit-код: 0 — без помилок, 1 — хоча б одна помилка або фейл preflight
+ * @returns {Promise<number>} exit-код: 0 — без помилок; 1 — помилки/фейл preflight; 2 — systemic-abort
  */
 export async function runDocFilesGenCli(argv) {
   const root = resolveRoot(argv)
@@ -182,22 +221,38 @@ export async function runDocFilesGenCli(argv) {
   }
 
   console.log(`📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite, retryDegraded })}`)
-  const stats = { ok: 0, degraded: 0, err: 0, errors: [] }
+  const stats = { ok: 0, degraded: 0, err: 0, errors: [], skipped: [] }
 
   let done = 0
+  let systemicStreak = 0
+  let aborted = false
   for (const file of targets) {
     done++
-    await generateOne(file, root, { done, total: targets.length }, stats)
+    const status = await generateOne(file, root, { done, total: targets.length }, stats)
+    // Circuit-breaker: K systemic-збоїв підряд → негайний abort (середовище впало,
+    // решта файлів так само згорить). Будь-який не-systemic результат скидає лічильник.
+    if (status === 'systemic') {
+      if (++systemicStreak >= SYSTEMIC_ABORT_STREAK) {
+        aborted = true
+        console.error(
+          `\n✗ doc-files: ${SYSTEMIC_ABORT_STREAK} systemic-збої підряд (omlx memory-guard / сервер) — abort на ${done}/${targets.length}.\n  Звільни RAM або перезапусти omlx і повтори — зроблене лишилось, решта підбереться за CRC.`
+        )
+        break
+      }
+    } else {
+      systemicStreak = 0
+    }
   }
 
   reportStats(stats)
+  if (aborted) return 2
   return stats.err > 0 ? 1 : 0
 }
 
 /**
  * `doc-files stamp` — детерміновано (пере)штампувати frontmatter `source`+`crc`
  * у НАЯВНИХ доках без виклику LLM. Для міграції док, які ще не мають CRC.
- * Поля якості (`score`/`issues`) при цьому зберігаються з наявного frontmatter.
+ * Поля `model` та якості (`score`/`issues`) при цьому зберігаються з наявного frontmatter.
  * @param {string[]} argv аргументи після назви субкоманди
  * @returns {number} exit-код: 0 — успіх
  */
@@ -211,7 +266,8 @@ export function runDocFilesStampCli(argv) {
     const crc = crc32(readFileSync(sourceAbs))
     const md = readFileSync(docAbs, 'utf8')
     const { score, issues } = readDocQuality(docAbs)
-    writeFileSync(docAbs, stampDoc(md, file.sourcePath, crc, score === null ? null : { score, issues }))
+    const model = readDocModel(docAbs)
+    writeFileSync(docAbs, stampDoc(md, file.sourcePath, crc, score === null ? null : { score, issues }, model))
     stamped++
   }
   console.log(`✓ fix-doc-files --stamp: оновлено frontmatter у ${stamped} доці(ах).`)

package/rules/doc-files/js/docgen-gen.mjs

@@ -3,7 +3,6 @@ import { readFileSync, existsSync } from 'node:fs'
 import { basename } from 'node:path'
 import { env } from 'node:process'
 import { resolveModel } from '../../../lib/models.mjs'
-import { DEFAULT_OMLX_MODEL } from '../../../lib/omlx.mjs'
 import { callLlm as callLlmRaw } from '../../../lib/llm.mjs'
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { docPathForSource } from './docgen-scan.mjs'
@@ -365,11 +364,12 @@ function orchestratedDoc(facts, src, model, timeoutMs, { anchors = null, tempera
 /** Максимальний час генерації одного LLM-виклику. */
 const LOCAL_TIMEOUT_MS = 5 * 60 * 1000
 /**
- * Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel('min') → omlx напряму.
- * Останній fallback гарантує local-only шлях без жодних env (через pi CLI той
- * самий локальний виклик виміряно повільніший на ~46%).
+ * Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel('min') (→ N_LOCAL_MIN_MODEL).
+ * Без хардкод-fallback: модель налаштовує кожен локально (`N_LOCAL_MIN_MODEL`); якщо
+ * нічого не задано — порожньо, і preflight оркестратора фейлить гучно (а не шле
+ * запит до неіснуючої моделі).
  */
-export const DEFAULT_LOCAL_MODEL = env.N_CURSOR_DOCGEN_MODEL ?? (resolveModel('min') || `omlx/${DEFAULT_OMLX_MODEL}`)
+export const DEFAULT_LOCAL_MODEL = env.N_CURSOR_DOCGEN_MODEL ?? resolveModel('min')
 
 /**
  * Головний API: файл → md-дока з det-оцінкою.

package/rules/doc-files/js/docgen-scan.mjs

@@ -78,9 +78,35 @@ export function describeFile(root, sourcePath) {
   return { sourcePath, docPath, stale, reason }
 }
 
+/**
+ * Підмножина шляхів, які git вважає ігнорованими (`.gitignore` + global excludes).
+ * Один батч-виклик `git check-ignore --stdin`. Tracked-файли git не репортить як
+ * ігноровані (тож `euscp.js` лишається кандидатом). Поза git-репо / коли жоден не
+ * ігнорується — порожній набір (graceful: фільтр просто не застосовується).
+ * @param {string} root абсолютний корінь (cwd для git)
+ * @param {string[]} relPaths posix-шляхи від кореня
+ * @returns {Set<string>} підмножина ігнорованих relPaths
+ */
+function gitIgnoredPaths(root, relPaths) {
+  if (relPaths.length === 0) return new Set()
+  try {
+    const out = execFileSync('git', ['check-ignore', '--stdin'], {
+      cwd: root,
+      input: relPaths.join('\n'),
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'ignore'] // git пише «not a git repository» у stderr — глушимо
+    })
+    return new Set(out.split('\n').map(s => s.trim()).filter(Boolean))
+  } catch {
+    // exit 1 (жоден не ігнорується) і 128 (не git-репо) → execFileSync кидає; обидва = «не фільтруємо».
+    return new Set()
+  }
+}
+
 /**
  * Рекурсивно обходить дерево від `root`, повертає кодові файли зі станом застарілості.
  * Синхронний `readdirSync` — детермінований порядок без гонок; обсяг дерева це дозволяє.
+ * Поверх `DOCGEN_IGNORE_GLOBS` відсіює ще й те, що в `.gitignore` (через git check-ignore).
  * @param {string} root абсолютний корінь обходу
  * @returns {Array<{sourcePath:string, docPath:string, stale:boolean, reason:'missing'|'crc-mismatch'|null}>} кандидати з відносними шляхами
  */
@@ -111,7 +137,8 @@ export function scanForDocFiles(root) {
   }
 
   walk(root)
-  return results
+  const ignored = gitIgnoredPaths(root, results.map(r => r.sourcePath))
+  return ignored.size ? results.filter(r => !ignored.has(r.sourcePath)) : results
 }
 
 /**