@nitra/cursor 9.1.1 → 9.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [9.3.0] - 2026-06-14
+
+### Added
+
+- per-tool omlx-фіксер (point 4): cspell autofix одруків через omlx у fix-режимі lint-text; спільне ядро llm-fix-apply (parse/read/apply, перевикористане llm-worker); generic llm-lint-fix; re-detect лишає валідні терміни для словника. Відновлено канон lint-text.yml --read-only (відкочений паралельним агентом)
+
+## [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.3.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
 }
 
 /**

package/rules/text/lint/cspell-fix.mjs

@@ -0,0 +1,104 @@
+/**
+ * cspell у ланцюжку lint-text із omlx-автофіксом (point 4 спеки).
+ *
+ * cspell не має нативного `--fix`. У fix-режимі: детект (захоплення виводу) → групування
+ * знахідок по файлах → per-file omlx-фікс справжніх одруків (`llmLintFix`) → re-detect.
+ * У read-only: лише детект (нуль мутацій). Валідні терміни omlx лишає — їх ловить повторний
+ * cspell (далі — у словник `@nitra/cspell-dict`).
+ */
+import { spawnSync } from 'node:child_process'
+
+import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { llmLintFix } from '../../../scripts/lib/fix/llm-lint-fix.mjs'
+
+/** Рядок cspell: `<file>:<line>:<col> - Unknown word (xxx)`. */
+const CSPELL_LINE_RE = /^(.+?):\d+:\d+\s+-\s+Unknown word/u
+/** Максимум файлів під omlx-фікс за прогін (без тихого обрізання — логуємо надлишок). */
+const MAX_FIX_FILES = 25
+
+/**
+ * Запускає `cspell .` із захопленням виводу.
+ * @param {string} cwd корінь
+ * @param {string} bin шлях до cspell (npx/локальний)
+ * @returns {{ code:number, out:string }} код + обʼєднаний stdout/stderr
+ */
+function detectCspell(cwd, bin) {
+  const r = spawnSync(bin, ['cspell', '.'], { cwd, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, env: process.env })
+  return { code: typeof r.status === 'number' ? r.status : 1, out: `${r.stdout ?? ''}${r.stderr ?? ''}` }
+}
+
+/**
+ * Групує cspell-знахідки за файлом.
+ * @param {string} out вивід cspell
+ * @returns {Map<string, string[]>} файл → рядки знахідок
+ */
+export function groupFindingsByFile(out) {
+  /** @type {Map<string, string[]>} */
+  const byFile = new Map()
+  for (const line of out.split('\n')) {
+    const m = CSPELL_LINE_RE.exec(line.trim())
+    if (!m) continue
+    const file = m[1]
+    if (!byFile.has(file)) byFile.set(file, [])
+    byFile.get(file).push(line.trim())
+  }
+  return byFile
+}
+
+const CSPELL_INSTRUCTION = [
+  'Correct genuine spelling typos in the file(s).',
+  'Each flagged "Unknown word" is listed below.',
+  'ONLY fix obvious misspellings of real words.',
+  'If a flagged token is a valid identifier, technical term, abbreviation, proper noun, URL,',
+  'or an intentional non-English word, leave it UNCHANGED (it will be added to the dictionary).',
+  'Preserve all code, formatting, and unrelated text exactly.'
+].join(' ')
+
+/**
+ * cspell-крок lint-text з omlx-автофіксом.
+ * @param {string} [cwd] корінь
+ * @param {boolean} [readOnly] true → лише детект (нуль мутацій)
+ * @returns {number} 0 — чисто; 1 — лишились знахідки / помилка середовища
+ */
+export function runCspellText(cwd = process.cwd(), readOnly = false) {
+  const bin = resolveCmd('npx')
+  if (!bin) {
+    process.stderr.write('❌ npx не знайдено в PATH (cspell).\n')
+    return 1
+  }
+
+  const first = detectCspell(cwd, bin)
+  if (first.code === 0) return 0
+  if (readOnly) {
+    process.stdout.write(first.out)
+    return first.code
+  }
+
+  // Fix-режим: omlx по файлах зі справжніми одруками.
+  const byFile = groupFindingsByFile(first.out)
+  const files = [...byFile.keys()]
+  if (files.length === 0) {
+    process.stdout.write(first.out)
+    return first.code
+  }
+  const targets = files.slice(0, MAX_FIX_FILES)
+  if (files.length > MAX_FIX_FILES) {
+    process.stdout.write(`ℹ️  cspell: omlx-фікс перших ${MAX_FIX_FILES}/${files.length} файлів (решта — наступний прогін)\n`)
+  }
+
+  for (const file of targets) {
+    const res = llmLintFix({
+      tool: 'cspell',
+      instruction: CSPELL_INSTRUCTION,
+      findings: byFile.get(file).join('\n'),
+      filePaths: [file],
+      projectRoot: cwd
+    })
+    process.stdout.write(res.ok ? `  ⚡ cspell omlx-фікс: ${file}\n` : `  ⚠️  cspell omlx-фікс пропущено (${file}): ${res.error}\n`)
+  }
+
+  // Re-detect: що лишилось (валідні терміни → у словник).
+  const second = detectCspell(cwd, bin)
+  if (second.code !== 0) process.stdout.write(second.out)
+  return second.code
+}

package/rules/text/lint/lint.mjs

@@ -24,6 +24,7 @@ import { runLintStep } from '../../../scripts/lib/run-lint-step.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
 import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
 import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
+import { runCspellText } from './cspell-fix.mjs'
 import { runDotenvLinter } from './run-dotenv-linter.mjs'
 import { runShellcheckText } from './run-shellcheck.mjs'
 import { runV8rWithGlobs } from './run-v8r.mjs'
@@ -106,7 +107,8 @@ function runLintTextSteps(readOnly = false) {
   // patch потрібен лише для авто-фіксу shellcheck; у read-only пропускаємо preflight.
   if (!readOnly && !preflight(PATCH_PREFLIGHT)) return 1
 
-  const cspellCode = runLintStep('cspell', 'npx', ['cspell', '.'])
+  console.log(`\n▶ cspell (${readOnly ? 'перевірка' : 'omlx-автофікс одруків + перевірка'})`)
+  const cspellCode = runCspellText(process.cwd(), readOnly)
   if (cspellCode !== 0) return cspellCode
 
   console.log(`\n▶ shellcheck (${readOnly ? 'перевірка' : 'авто-фікс + фінальна перевірка'} *.sh)`)

package/scripts/lib/fix/llm-fix-apply.mjs

@@ -0,0 +1,78 @@
+/**
+ * Спільне ядро LLM-фіксу: парс відповіді `{changes:[{path,content}]}`, читання файлів
+ * під фікс і застосування змін. Використовують і `llm-worker.mjs` (конформність), і
+ * `llm-lint-fix.mjs` (per-tool лінтер-фіксери) — щоб не дублювати парс/apply (knip/jscpd).
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const JSON_CODE_BLOCK_RE = /```(?:json)?[ \t]{0,8}\n?([\s\S]*?)```/
+
+/**
+ * Парсить JSON-відповідь моделі: прямий JSON → ```json-блок``` → перший `{…}`-блок.
+ * @param {string} text сирий текст відповіді
+ * @returns {{ changes?: Array<{path:string,content:string}>, error?: string } | null} патч або null
+ */
+export function parseChangesResponse(text) {
+  try {
+    return JSON.parse(text)
+  } catch {
+    /* fallthrough */
+  }
+  const block = text.match(JSON_CODE_BLOCK_RE)
+  if (block) {
+    try {
+      return JSON.parse(block[1].trim())
+    } catch {
+      /* fallthrough */
+    }
+  }
+  const start = text.indexOf('{')
+  const end = text.lastIndexOf('}')
+  if (start !== -1 && end > start) {
+    try {
+      return JSON.parse(text.slice(start, end + 1))
+    } catch {
+      /* fallthrough */
+    }
+  }
+  return null
+}
+
+/**
+ * Читає існуючі файли за відносними шляхами у форму `{path, content}` (для prompt).
+ * @param {string[]} filePaths відносні шляхи від кореня
+ * @param {string} projectRoot абсолютний корінь
+ * @returns {Array<{path:string, content:string}>} наявні файли з вмістом
+ */
+export function readFilesForFix(filePaths, projectRoot) {
+  return filePaths
+    .map(p => {
+      const abs = join(projectRoot, p)
+      if (!existsSync(abs)) return null
+      try {
+        return { path: p, content: readFileSync(abs, 'utf8') }
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+}
+
+/**
+ * Застосовує `changes` до ФС (повний вміст файлу, не diff).
+ * @param {Array<{path:string, content:string}>} changes зміни
+ * @param {string} projectRoot абсолютний корінь
+ * @returns {{ ok: boolean, error?: string }} статус
+ */
+export function applyChanges(changes, projectRoot) {
+  for (const change of changes) {
+    if (!change.path || typeof change.content !== 'string') continue
+    try {
+      writeFileSync(join(projectRoot, change.path), change.content, 'utf8')
+    } catch (error) {
+      return { ok: false, error: `write ${change.path}: ${error.message}` }
+    }
+  }
+  return { ok: true }
+}

package/scripts/lib/fix/llm-lint-fix.mjs

@@ -0,0 +1,82 @@
+/**
+ * Per-tool omlx-фікс лінтер-знахідок (point 4 спеки lint-orchestrator-fix-readonly).
+ *
+ * Для detect-only тулів без нативного `--fix` (cspell, knip, actionlint, v8r тощо): читає
+ * уражені файли, просить omlx виправити за tool-специфічною інструкцією, застосовує `{changes}`.
+ * Re-detect (перевірка, що знахідка закрита) — на стороні caller (convergence-патерн).
+ *
+ * Маршрут моделі — через `callLlm` за префіксом: `omlx/<model>` → локальний HTTP (дефолт
+ * `resolveModel('min')`); cloud — фолбек каскаду. Парс/застосування — спільне ядро `llm-fix-apply`.
+ */
+import { env } from 'node:process'
+
+import { resolveModel } from '../../../lib/models.mjs'
+import { callLlm } from '../../../lib/llm.mjs'
+import { applyChanges, parseChangesResponse, readFilesForFix } from './llm-fix-apply.mjs'
+
+/** Дефолтний локальний тир (omlx); env `N_CURSOR_FIX_MODEL` перекриває. */
+const DEFAULT_MODEL = env.N_CURSOR_FIX_MODEL ?? resolveModel('min')
+
+/**
+ * Будує prompt для omlx: tool-інструкція + знахідки + повний вміст файлів.
+ * @param {string} tool назва тула (cspell/knip/…)
+ * @param {string} instruction що саме виправити (tool-специфічно)
+ * @param {string} findings сирий вивід тула (знахідки)
+ * @param {Array<{path:string, content:string}>} files файли під фікс
+ * @returns {string} prompt
+ */
+function buildLintFixPrompt(tool, instruction, findings, files) {
+  const filesBlock = files.map(f => `<file path="${f.path}">\n${f.content}\n</file>`).join('\n\n')
+  return [
+    `You fix ${tool} lint findings. Return ONLY valid JSON — no explanation, no markdown.`,
+    ``,
+    `Task: ${instruction}`,
+    ``,
+    `${tool} findings:`,
+    findings,
+    ``,
+    `Current file contents:`,
+    filesBlock,
+    ``,
+    `Return JSON with this exact shape:`,
+    `{"changes":[{"path":"relative/path","content":"full corrected file content"}]}`,
+    ``,
+    `Rules:`,
+    `- "path" is relative to the project root (use the path from the <file> tag)`,
+    `- "content" is the COMPLETE new file content (not a diff)`,
+    `- Only include files that actually need to change; preserve everything unrelated verbatim`,
+    `- If nothing should be auto-fixed, return {"changes":[],"error":"reason"}`
+  ].join('\n')
+}
+
+/**
+ * Виправляє лінтер-знахідки через omlx і застосовує зміни.
+ * @param {{ tool:string, instruction:string, findings:string, filePaths:string[], projectRoot:string, model?:string }} opts параметри
+ * @returns {{ ok:boolean, error?:string, fixed:string[] }} статус + список змінених шляхів
+ */
+export function llmLintFix({ tool, instruction, findings, filePaths, projectRoot, model }) {
+  const m = model ?? DEFAULT_MODEL
+  const files = readFilesForFix(filePaths, projectRoot)
+  if (files.length === 0) return { ok: false, error: 'no readable files to fix', fixed: [] }
+
+  let text
+  try {
+    text = callLlm([{ role: 'user', content: buildLintFixPrompt(tool, instruction, findings, files) }], m, {
+      timeoutMs: 120_000,
+      caller: `lint:${tool}`
+    })
+  } catch (error) {
+    return { ok: false, error: String(error.message), fixed: [] }
+  }
+
+  const parsed = parseChangesResponse(text)
+  if (!parsed) return { ok: false, error: `cannot parse omlx response: ${String(text).slice(0, 200)}`, fixed: [] }
+  if (parsed.error) return { ok: false, error: parsed.error, fixed: [] }
+
+  const changes = (parsed.changes ?? []).filter(c => c.path && typeof c.content === 'string')
+  if (changes.length === 0) return { ok: false, error: 'omlx returned no changes', fixed: [] }
+
+  const applied = applyChanges(changes, projectRoot)
+  if (!applied.ok) return { ok: false, error: applied.error, fixed: [] }
+  return { ok: true, fixed: changes.map(c => c.path) }
+}

package/scripts/lib/fix/llm-worker.mjs

@@ -1,17 +1,17 @@
 /** @see ./docs/llm-worker.md */
 
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { env } from 'node:process'
 import { resolveModel } from '../../../lib/models.mjs'
 import { callLlm } from '../../../lib/llm.mjs'
+import { applyChanges, parseChangesResponse, readFilesForFix } from './llm-fix-apply.mjs'
 
 // Тир за замовчуванням: min → avg при ескалації (каскад local→cloud).
 // Перевизначення через N_CURSOR_FIX_MODEL / N_CURSOR_FIX_MODEL_HEAVY.
 export const MODEL = env.N_CURSOR_FIX_MODEL ?? resolveModel('min')
 export const MODEL_HEAVY = env.N_CURSOR_FIX_MODEL_HEAVY ?? resolveModel('avg')
 
-const JSON_CODE_BLOCK_RE = /```(?:json)?[ \t]{0,8}\n?([\s\S]*?)```/
 const API_KEY_RE = /api key/i
 
 /**
@@ -113,44 +113,6 @@ function callModel(prompt, model) {
   }
 }
 
-/**
- * Парсить JSON-відповідь від моделі.
- * Модель може обгорнути JSON у ```json ... ```, тому пробуємо витягти.
- * @param {string} text сирий текст відповіді
- * @returns {{ changes: Array<{path:string,content:string}>, error?: string } | null} розпарсений патч або null
- */
-function parseResponse(text) {
-  // Спроба 1: прямий JSON
-  try {
-    return JSON.parse(text)
-  } catch {
-    /* fallthrough */
-  }
-
-  // Спроба 2: витягти з ```json ... ```
-  const m = text.match(JSON_CODE_BLOCK_RE)
-  if (m) {
-    try {
-      return JSON.parse(m[1].trim())
-    } catch {
-      /* fallthrough */
-    }
-  }
-
-  // Спроба 3: перший { ... } блок
-  const start = text.indexOf('{')
-  const end = text.lastIndexOf('}')
-  if (start !== -1 && end > start) {
-    try {
-      return JSON.parse(text.slice(start, end + 1))
-    } catch {
-      /* fallthrough */
-    }
-  }
-
-  return null
-}
-
 /**
  * LLM-worker: виправляє одне rule-порушення через pi (C1 pattern).
  * @param {string} ruleId ID правила
@@ -167,18 +129,7 @@ export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
   const ruleMdc = existsSync(mdcPath) ? readFileSync(mdcPath, 'utf8') : '(rule file not found)'
 
   // 2. Витягуємо файли з violation output і читаємо їх
-  const filePaths = extractFilePaths(violationOutput)
-  const files = filePaths
-    .map(p => {
-      const abs = join(projectRoot, p)
-      if (!existsSync(abs)) return null
-      try {
-        return { path: p, content: readFileSync(abs, 'utf8') }
-      } catch {
-        return null
-      }
-    })
-    .filter(Boolean)
+  const files = readFilesForFix(extractFilePaths(violationOutput), projectRoot)
 
   // 3. Будуємо prompt і викликаємо модель
   const prompt = buildPrompt(ruleId, ruleMdc, violationOutput, files)
@@ -188,7 +139,7 @@ export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
   if (!text) return { ok: false, error: 'model returned empty response' }
 
   // 4. Парсимо відповідь
-  const parsed = parseResponse(text)
+  const parsed = parseChangesResponse(text)
   if (!parsed) return { ok: false, error: `cannot parse pi response: ${text.slice(0, 200)}` }
   if (parsed.error) return { ok: false, error: parsed.error }
 
@@ -196,15 +147,5 @@ export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
   if (changes.length === 0) return { ok: false, error: 'pi returned no changes' }
 
   // 5. Застосовуємо зміни
-  for (const change of changes) {
-    if (!change.path || typeof change.content !== 'string') continue
-    const abs = join(projectRoot, change.path)
-    try {
-      writeFileSync(abs, change.content, 'utf8')
-    } catch (error) {
-      return { ok: false, error: `write ${change.path}: ${error.message}` }
-    }
-  }
-
-  return { ok: true }
+  return applyChanges(changes, projectRoot)
 }