claude-brain 0.27.2 → 0.28.0

package/src/cli/commands/models.ts

@@ -0,0 +1,681 @@
+/**
+ * Models Command — SLM Upgrade Phase 5
+ * Manage SLM models: list, download, enable, disable, benchmark, stats.
+ *
+ * Usage:
+ *   claude-brain models list
+ *   claude-brain models download [--task <task>|all]
+ *   claude-brain models enable <task>
+ *   claude-brain models disable <task>
+ *   claude-brain models benchmark <task>
+ *   claude-brain models stats
+ */
+
+import { readFileSync, existsSync, mkdirSync, writeFileSync, statSync, copyFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { parseArgs } from 'citty'
+import { renderLogo, theme, heading, dimText, successText, warningText, errorText, box, summaryPanel } from '@/cli/ui/index.js'
+import { getHomePaths, getClaudeBrainHome } from '@/config/home'
+import { getTrainingStats, type TrainingTask } from '@/training/data-store'
+import type { ModelManifest, ModelManifestEntry, ModelTask } from '@/intelligence/model-manager'
+import { shouldRetrain, retrainTask, retrainAll, type RetrainConfig } from '@/training/retrain-pipeline'
+
+const ALL_TASKS: ModelTask[] = ['intent', 'entity', 'query', 'knowledge', 'compress', 'pattern']
+
+export async function runModels() {
+  const args = parseArgs(process.argv.slice(3), {
+    subcommand: { type: 'positional', required: false, description: 'Subcommand: list, download, enable, disable, benchmark, stats, retrain' },
+    taskArg: { type: 'positional', required: false, description: 'Task name (for enable/disable/benchmark/retrain)' },
+    task: { type: 'string', description: 'Target task (for download --task)' },
+    source: { type: 'string', description: 'Source: local (default) or release' },
+    force: { type: 'boolean', description: 'Force retrain even if checks say not needed' },
+  })
+
+  const subcommand = args.subcommand || ''
+  const taskArg = (args.task || args.taskArg || '') as string
+
+  switch (subcommand) {
+    case 'list':
+      return listModels()
+    case 'download':
+      return downloadModels(taskArg || 'all', (args.source as string) || 'local')
+    case 'enable':
+      return enableTask(taskArg)
+    case 'disable':
+      return disableTask(taskArg)
+    case 'benchmark':
+      return benchmarkTask(taskArg)
+    case 'stats':
+      return showStats()
+    case 'retrain':
+      return retrainModels(taskArg || 'all', !!args.force)
+    default:
+      return printModelsHelp()
+  }
+}
+
+// ─── list ─────────────────────────────────────────────────────────
+
+function listModels() {
+  console.log()
+  console.log(renderLogo())
+  console.log()
+  console.log(heading('SLM Models'))
+  console.log()
+
+  const paths = getHomePaths()
+  const manifestPath = join(paths.models, 'manifest.json')
+
+  const items: Array<{ label: string; value: string; status?: 'success' | 'warning' | 'error' | 'info' }> = []
+
+  if (!existsSync(manifestPath)) {
+    items.push({ label: 'Manifest', value: 'Not found — run "models download" first', status: 'warning' })
+    console.log(summaryPanel('Models', items))
+    console.log()
+
+    // Still show task status even without manifest
+    for (const task of ALL_TASKS) {
+      console.log(`  ${theme.primary(task.padEnd(12))} ${warningText('not installed')}`)
+    }
+    console.log()
+    return
+  }
+
+  let manifest: ModelManifest
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+  } catch {
+    console.log(errorText('Failed to parse manifest.json'))
+    return
+  }
+
+  let totalSize = 0
+  const rows: string[] = []
+
+  for (const task of ALL_TASKS) {
+    const entry = manifest.models?.[task]
+    if (!entry) {
+      rows.push(`  ${theme.primary(task.padEnd(12))} ${warningText('not installed')}`)
+      continue
+    }
+
+    const modelPath = join(paths.models, entry.file)
+    const installed = existsSync(modelPath)
+
+    let sizeStr = '—'
+    if (installed) {
+      try {
+        const size = statSync(modelPath).size
+        totalSize += size
+        sizeStr = formatBytes(size)
+      } catch {
+        sizeStr = '?'
+      }
+    }
+
+    const status = installed ? successText('installed') : warningText('missing')
+    const version = entry.version ? dimText(`v${entry.version}`) : ''
+    const accuracy = entry.accuracy != null ? dimText(`${(entry.accuracy * 100).toFixed(1)}%`) : ''
+
+    rows.push(
+      `  ${theme.primary(task.padEnd(12))} ${status.padEnd(24)} ${version.padEnd(14)} ${accuracy.padEnd(10)} ${dimText(sizeStr)}`
+    )
+  }
+
+  // Header
+  console.log(
+    `  ${dimText('Task'.padEnd(12))} ${dimText('Status'.padEnd(14))} ${dimText('Version'.padEnd(14))} ${dimText('Accuracy'.padEnd(10))} ${dimText('Size')}`
+  )
+  for (const row of rows) {
+    console.log(row)
+  }
+  console.log()
+  console.log(`  ${dimText('Total size:')} ${dimText(formatBytes(totalSize))}`)
+  console.log()
+}
+
+// ─── download ─────────────────────────────────────────────────────
+
+function downloadModels(taskFilter: string, source: string) {
+  console.log()
+  console.log(renderLogo())
+  console.log()
+  console.log(heading('Download Models'))
+  console.log()
+
+  const paths = getHomePaths()
+
+  // Validate task filter
+  if (taskFilter !== 'all' && !ALL_TASKS.includes(taskFilter as ModelTask)) {
+    console.log(errorText(`Invalid task: ${taskFilter}`))
+    console.log(dimText(`Valid tasks: ${ALL_TASKS.join(', ')}`))
+    return
+  }
+
+  const tasks = taskFilter === 'all' ? ALL_TASKS : [taskFilter as ModelTask]
+
+  // Ensure models directory exists
+  if (!existsSync(paths.models)) {
+    mkdirSync(paths.models, { recursive: true })
+    console.log(successText(`Created models directory: ${paths.models}`))
+  }
+
+  // Release source — not yet implemented
+  if (source === 'release') {
+    console.log(
+      box(
+        'Downloading from release artifacts is not yet available.\n' +
+        'Use --source local to install from ~/slm-training/models/ instead.',
+        'Coming Soon'
+      )
+    )
+    console.log()
+    return
+  }
+
+  // Local source — copy from ~/slm-training/models/
+  const sourceDir = join(homedir(), 'slm-training', 'models')
+
+  console.log(`  ${dimText('Source:')} ${sourceDir}`)
+  console.log(`  ${dimText('Target:')} ${paths.models}`)
+  console.log()
+
+  if (!existsSync(sourceDir)) {
+    console.log(errorText(`Source directory not found: ${sourceDir}`))
+    console.log(dimText('Train models first, then place .onnx and .json files in the source directory.'))
+    return
+  }
+
+  let installed = 0
+  let totalBytes = 0
+  const installedTasks: ModelTask[] = []
+  const manifestModels: Partial<Record<ModelTask, ModelManifestEntry>> = {}
+
+  // Load existing manifest to preserve entries for tasks we're not updating
+  const manifestPath = join(paths.models, 'manifest.json')
+  if (existsSync(manifestPath)) {
+    try {
+      const existing: ModelManifest = JSON.parse(readFileSync(manifestPath, 'utf-8'))
+      if (existing.models) {
+        Object.assign(manifestModels, existing.models)
+      }
+    } catch {
+      // Ignore corrupt manifest, we'll overwrite it
+    }
+  }
+
+  for (const task of tasks) {
+    const onnxFile = `${task}.onnx`
+    const metaFile = `${task}.json`
+    const srcOnnx = join(sourceDir, onnxFile)
+    const srcMeta = join(sourceDir, metaFile)
+
+    if (!existsSync(srcOnnx)) {
+      console.log(`  ${warningText(`${onnxFile} not found in source — skipping`)}`)
+      continue
+    }
+
+    // Copy ONNX model
+    const dstOnnx = join(paths.models, onnxFile)
+    copyFileSync(srcOnnx, dstOnnx)
+
+    // Verify copied file is valid (non-empty and size matches source)
+    const srcSize = statSync(srcOnnx).size
+    const dstSize = statSync(dstOnnx).size
+    if (dstSize === 0 || dstSize !== srcSize) {
+      console.log(`  ${errorText(`${onnxFile} copy verification failed (src: ${formatBytes(srcSize)}, dst: ${formatBytes(dstSize)}) — skipping`)}`)
+      continue
+    }
+
+    totalBytes += dstSize
+    console.log(`  Copying ${onnxFile}... ${successText('done')} ${dimText(`(${formatBytes(dstSize)})`)}`)
+
+    // Copy metadata if present
+    let meta: Partial<ModelManifestEntry> = {}
+    if (existsSync(srcMeta)) {
+      const dstMeta = join(paths.models, metaFile)
+      copyFileSync(srcMeta, dstMeta)
+      try {
+        meta = JSON.parse(readFileSync(dstMeta, 'utf-8'))
+      } catch {
+        console.log(`  ${warningText(`Failed to parse ${metaFile} — using defaults`)}`)
+      }
+    }
+
+    // Build manifest entry for this task
+    // Map training metadata fields → manifest fields:
+    //   val_acc → accuracy, block_size → maxSeqLen, model_name → params
+    const metaAny = meta as Record<string, any>
+    manifestModels[task] = {
+      version: meta.version ?? '0.1.0',
+      file: onnxFile,
+      sha256: meta.sha256,
+      params: meta.params ?? metaAny.model_name,
+      accuracy: meta.accuracy ?? metaAny.val_acc,
+      labels: meta.labels,
+      maxSeqLen: meta.maxSeqLen ?? metaAny.block_size,
+    }
+
+    installedTasks.push(task)
+    installed++
+  }
+
+  console.log()
+
+  if (installed === 0) {
+    console.log(warningText('No models were installed.'))
+    console.log()
+    return
+  }
+
+  // Write manifest
+  const manifest: ModelManifest = { models: manifestModels }
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2))
+
+  // Auto-enable successfully installed models in config
+  const configPath = join(getClaudeBrainHome(), 'config.json')
+  const config = loadConfigFile(configPath)
+  if (!config.slm) config.slm = {}
+  config.slm.enabled = true
+  if (!config.slm.tasks) config.slm.tasks = {}
+  for (const task of installedTasks) {
+    config.slm.tasks[task] = 'model'
+  }
+  writeFileSync(configPath, JSON.stringify(config, null, 2))
+
+  console.log(successText(`Installed ${installed} model${installed !== 1 ? 's' : ''} (total: ${formatBytes(totalBytes)})`))
+  console.log(successText(`Auto-enabled ${installedTasks.join(', ')} in config`))
+  console.log(dimText(`Manifest written to ${manifestPath}`))
+  console.log()
+}
+
+// ─── enable ───────────────────────────────────────────────────────
+
+function enableTask(task: string) {
+  if (!task) {
+    console.log(errorText('Missing task argument'))
+    console.log(dimText(`Usage: claude-brain models enable <task>`))
+    console.log(dimText(`Tasks: ${ALL_TASKS.join(', ')}`))
+    return
+  }
+
+  if (!ALL_TASKS.includes(task as ModelTask)) {
+    console.log(errorText(`Invalid task: ${task}`))
+    console.log(dimText(`Valid tasks: ${ALL_TASKS.join(', ')}`))
+    return
+  }
+
+  const configPath = join(getClaudeBrainHome(), 'config.json')
+  const config = loadConfigFile(configPath)
+
+  // Ensure slm section exists
+  if (!config.slm) config.slm = {}
+  config.slm.enabled = true
+  if (!config.slm.tasks) config.slm.tasks = {}
+
+  // compress uses 'api' baseline, others use 'regex'
+  config.slm.tasks[task] = 'model'
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2))
+  console.log(successText(`Enabled model inference for task: ${task}`))
+  console.log(dimText(`Config updated: ${configPath}`))
+}
+
+// ─── disable ──────────────────────────────────────────────────────
+
+function disableTask(task: string) {
+  if (!task) {
+    console.log(errorText('Missing task argument'))
+    console.log(dimText(`Usage: claude-brain models disable <task>`))
+    console.log(dimText(`Tasks: ${ALL_TASKS.join(', ')}`))
+    return
+  }
+
+  if (!ALL_TASKS.includes(task as ModelTask)) {
+    console.log(errorText(`Invalid task: ${task}`))
+    console.log(dimText(`Valid tasks: ${ALL_TASKS.join(', ')}`))
+    return
+  }
+
+  const configPath = join(getClaudeBrainHome(), 'config.json')
+  const config = loadConfigFile(configPath)
+
+  if (!config.slm) config.slm = {}
+  if (!config.slm.tasks) config.slm.tasks = {}
+
+  // Revert to baseline: compress → 'api', others → 'regex'
+  config.slm.tasks[task] = task === 'compress' ? 'api' : 'regex'
+
+  writeFileSync(configPath, JSON.stringify(config, null, 2))
+  console.log(successText(`Disabled model inference for task: ${task}`))
+  console.log(dimText(`Reverted to ${task === 'compress' ? 'api' : 'regex'} mode`))
+}
+
+// ─── benchmark ────────────────────────────────────────────────────
+
+async function benchmarkTask(task: string) {
+  if (!task) {
+    console.log(errorText('Missing task argument'))
+    console.log(dimText(`Usage: claude-brain models benchmark <task>`))
+    console.log(dimText(`Tasks: ${ALL_TASKS.join(', ')}`))
+    return
+  }
+
+  if (!ALL_TASKS.includes(task as ModelTask)) {
+    console.log(errorText(`Invalid task: ${task}`))
+    console.log(dimText(`Valid tasks: ${ALL_TASKS.join(', ')}`))
+    return
+  }
+
+  console.log()
+  console.log(heading(`Benchmark: ${task}`))
+  console.log()
+
+  // Look for test data
+  const home = getClaudeBrainHome()
+  const testDataPath = join(home, 'training', 'benchmarks', 'baseline', `${task}_test.jsonl`)
+
+  if (!existsSync(testDataPath)) {
+    console.log(warningText(`Test data not found: ${testDataPath}`))
+    console.log(dimText('Generate test data first with: claude-brain export-training ' + task))
+    return
+  }
+
+  // Load test examples
+  const lines = readFileSync(testDataPath, 'utf-8').trim().split('\n').filter(Boolean)
+  if (lines.length === 0) {
+    console.log(warningText('Test file is empty'))
+    return
+  }
+
+  console.log(dimText(`Loaded ${lines.length} test examples from ${testDataPath}`))
+  console.log()
+
+  // Run through regex classifier for intent task
+  if (task === 'intent') {
+    await benchmarkIntent(lines)
+  } else {
+    // For non-intent tasks, just report data availability
+    console.log(dimText(`Benchmark for "${task}" requires model inference (ONNX).`))
+    console.log(dimText(`Regex-only benchmarking is available for the intent task.`))
+    console.log()
+    console.log(dimText(`Test data: ${lines.length} examples ready`))
+  }
+}
+
+async function benchmarkIntent(lines: string[]) {
+  // Dynamic import to avoid circular deps
+  const { IntentClassifier } = await import('@/routing/intent-classifier')
+  const classifier = new IntentClassifier()
+
+  let correct = 0
+  const labelCounts: Record<string, { tp: number; fp: number; fn: number }> = {}
+
+  for (const line of lines) {
+    let example: { input: string; output: { label: string } }
+    try {
+      example = JSON.parse(line)
+    } catch {
+      continue
+    }
+
+    const expected = example.output?.label
+    if (!expected) continue
+
+    const result = classifier.classify(example.input)
+    const predicted = result.primary
+
+    // Initialize counters
+    if (!labelCounts[expected]) labelCounts[expected] = { tp: 0, fp: 0, fn: 0 }
+    if (!labelCounts[predicted]) labelCounts[predicted] = { tp: 0, fp: 0, fn: 0 }
+
+    if (predicted === expected) {
+      correct++
+      labelCounts[expected].tp++
+    } else {
+      labelCounts[expected].fn++
+      labelCounts[predicted].fp++
+    }
+  }
+
+  const total = lines.length
+  const accuracy = total > 0 ? correct / total : 0
+
+  console.log(`  ${theme.bold('Overall Accuracy:')} ${accuracy >= 0.7 ? successText(`${(accuracy * 100).toFixed(1)}%`) : warningText(`${(accuracy * 100).toFixed(1)}%`)} (${correct}/${total})`)
+  console.log()
+
+  // Per-class metrics
+  console.log(`  ${dimText('Label'.padEnd(20))} ${dimText('Prec'.padEnd(8))} ${dimText('Recall'.padEnd(8))} ${dimText('F1'.padEnd(8))} ${dimText('Support')}`)
+  console.log(`  ${dimText('-'.repeat(52))}`)
+
+  const sortedLabels = Object.keys(labelCounts).sort()
+  for (const label of sortedLabels) {
+    const { tp, fp, fn } = labelCounts[label]
+    const precision = tp + fp > 0 ? tp / (tp + fp) : 0
+    const recall = tp + fn > 0 ? tp / (tp + fn) : 0
+    const f1 = precision + recall > 0 ? (2 * precision * recall) / (precision + recall) : 0
+    const support = tp + fn
+
+    console.log(
+      `  ${theme.primary(label.padEnd(20))} ${(precision * 100).toFixed(1).padStart(5)}%  ${(recall * 100).toFixed(1).padStart(5)}%  ${(f1 * 100).toFixed(1).padStart(5)}%  ${String(support).padStart(5)}`
+    )
+  }
+  console.log()
+}
+
+// ─── stats ────────────────────────────────────────────────────────
+
+async function showStats() {
+  console.log()
+  console.log(renderLogo())
+  console.log()
+  console.log(heading('Training Data Statistics'))
+  console.log()
+
+  const stats = getTrainingStats()
+  const items: Array<{ label: string; value: string; status?: 'success' | 'warning' | 'error' | 'info' }> = []
+
+  let grandTotal = 0
+  let grandVerified = 0
+
+  for (const task of ALL_TASKS) {
+    const { total, verified } = stats[task]
+    grandTotal += total
+    grandVerified += verified
+    items.push({
+      label: task,
+      value: `${total} total, ${verified} verified`,
+      status: total > 0 ? 'success' : 'warning'
+    })
+  }
+
+  items.push({
+    label: 'Total',
+    value: `${grandTotal} total, ${grandVerified} verified`,
+    status: grandTotal > 0 ? 'success' : 'warning'
+  })
+
+  console.log(summaryPanel('Training Data', items))
+  console.log()
+
+  // Check for model_feedback table
+  try {
+    const { Database } = await import('bun:sqlite') as any
+    const dbPath = join(getClaudeBrainHome(), 'data', 'memory.db')
+    if (existsSync(dbPath)) {
+      const db = new Database(dbPath, { readonly: true })
+      const hasTable = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='model_feedback'").get()
+      if (hasTable) {
+        const disagreements = (db.prepare('SELECT COUNT(*) as c FROM model_feedback WHERE model_label != regex_label').get() as any)?.c ?? 0
+        const totalFeedback = (db.prepare('SELECT COUNT(*) as c FROM model_feedback').get() as any)?.c ?? 0
+        console.log(`  ${dimText('Model Feedback:')} ${totalFeedback} entries, ${disagreements} disagreements`)
+        console.log()
+      }
+      db.close()
+    }
+  } catch {
+    // model_feedback table doesn't exist yet — that's fine
+  }
+}
+
+// ─── retrain ──────────────────────────────────────────────────────
+
+async function retrainModels(taskFilter: string, force: boolean) {
+  console.log()
+  console.log(renderLogo())
+  console.log()
+  console.log(heading('Retrain Models'))
+  console.log()
+
+  // Validate task filter
+  if (taskFilter !== 'all' && !ALL_TASKS.includes(taskFilter as ModelTask)) {
+    console.log(errorText(`Invalid task: ${taskFilter}`))
+    console.log(dimText(`Valid tasks: ${ALL_TASKS.join(', ')}, all`))
+    return
+  }
+
+  // Build config from schema defaults + config.json overrides
+  const configPath = join(getClaudeBrainHome(), 'config.json')
+  const userConfig = loadConfigFile(configPath)
+  const retrainCfg = userConfig?.slm?.retrain ?? {}
+
+  const config: RetrainConfig = {
+    minFeedbackCount: retrainCfg.minFeedbackCount ?? 100,
+    maxDisagreementRate: retrainCfg.maxDisagreementRate ?? 0.15,
+    pythonPath: retrainCfg.pythonPath ?? 'python3',
+    trainingDir: retrainCfg.trainingDir ?? '~/slm-training',
+    force,
+  }
+
+  console.log(`  ${dimText('Training dir:')} ${config.trainingDir}`)
+  console.log(`  ${dimText('Python path:')} ${config.pythonPath}`)
+  console.log(`  ${dimText('Min feedback:')} ${config.minFeedbackCount}`)
+  console.log(`  ${dimText('Max disagreement:')} ${(config.maxDisagreementRate * 100).toFixed(0)}%`)
+  if (force) console.log(`  ${warningText('Force mode enabled — skipping checks')}`)
+  console.log()
+
+  if (taskFilter === 'all') {
+    // Retrain all tasks that need it
+    const results = await retrainAll(config)
+
+    if (results.size === 0) {
+      console.log(dimText('  No tasks needed retraining.'))
+      console.log()
+      return
+    }
+
+    // Summary
+    console.log()
+    console.log(heading('Retrain Summary'))
+    console.log()
+    for (const [task, result] of results) {
+      if (result.success) {
+        const accStr = result.newAccuracy != null
+          ? `${(result.newAccuracy * 100).toFixed(1)}%`
+          : 'n/a'
+        const oldStr = result.oldAccuracy != null
+          ? ` (was ${(result.oldAccuracy * 100).toFixed(1)}%)`
+          : ''
+        console.log(`  ${successText(task.padEnd(12))} accuracy: ${accStr}${oldStr}  ${dimText(`${result.trainingDataCount} examples, ${(result.duration / 1000).toFixed(1)}s`)}`)
+      } else {
+        console.log(`  ${errorText(task.padEnd(12))} ${result.error}`)
+      }
+    }
+  } else {
+    // Single task
+    const task = taskFilter as ModelTask
+
+    if (!force) {
+      const check = shouldRetrain(task, config)
+      console.log(`  ${dimText('Feedback count:')} ${check.feedbackCount}`)
+      console.log(`  ${dimText('Disagreement rate:')} ${(check.disagreementRate * 100).toFixed(1)}%`)
+      console.log(`  ${dimText('Last retrain:')} ${check.lastRetrainDate ?? 'never'}`)
+      console.log(`  ${dimText('Needs retrain:')} ${check.needed ? 'yes' : 'no'} — ${check.reason}`)
+      console.log()
+
+      if (!check.needed) {
+        console.log(dimText('  Retrain not needed. Use --force to override.'))
+        console.log()
+        return
+      }
+    }
+
+    const result = await retrainTask(task, config)
+
+    console.log()
+    if (result.success) {
+      const accStr = result.newAccuracy != null
+        ? `${(result.newAccuracy * 100).toFixed(1)}%`
+        : 'n/a'
+      const oldStr = result.oldAccuracy != null
+        ? ` (was ${(result.oldAccuracy * 100).toFixed(1)}%)`
+        : ''
+      console.log(successText(`Retrain complete: accuracy ${accStr}${oldStr}`))
+      console.log(dimText(`  ${result.trainingDataCount} examples, ${(result.duration / 1000).toFixed(1)}s`))
+    } else {
+      console.log(errorText(`Retrain failed: ${result.error}`))
+    }
+  }
+
+  console.log()
+}
+
+// ─── help ─────────────────────────────────────────────────────────
+
+function printModelsHelp() {
+  console.log()
+  console.log(renderLogo())
+  console.log()
+  console.log(heading('SLM Model Management'))
+  console.log()
+
+  const subcommands = [
+    ['list', 'Show installed models and their status'],
+    ['download', 'Download pre-trained models (--task <task>|all)'],
+    ['enable <task>', 'Enable model inference for a task'],
+    ['disable <task>', 'Disable model inference for a task'],
+    ['benchmark <task>', 'Run accuracy benchmark on test data'],
+    ['stats', 'Show training data statistics'],
+    ['retrain [<task>|all]', 'Retrain models from feedback (--force)'],
+  ]
+
+  const lines = subcommands
+    .map(([cmd, desc]) => `  ${theme.primary(cmd!.padEnd(20))} ${dimText(desc!)}`)
+    .join('\n')
+
+  console.log(theme.bold('Usage:') + ' ' + dimText('claude-brain models <subcommand>'))
+  console.log()
+  console.log(theme.bold('Subcommands:'))
+  console.log(lines)
+  console.log()
+  console.log(theme.bold('Tasks:') + ' ' + dimText(ALL_TASKS.join(', ')))
+  console.log()
+  console.log(theme.bold('Examples:'))
+  console.log(`  ${dimText('claude-brain models list')}`)
+  console.log(`  ${dimText('claude-brain models enable intent')}`)
+  console.log(`  ${dimText('claude-brain models benchmark intent')}`)
+  console.log(`  ${dimText('claude-brain models stats')}`)
+  console.log(`  ${dimText('claude-brain models retrain intent')}`)
+  console.log(`  ${dimText('claude-brain models retrain all --force')}`)
+  console.log()
+}
+
+// ─── helpers ──────────────────────────────────────────────────────
+
+function loadConfigFile(configPath: string): Record<string, any> {
+  if (!existsSync(configPath)) return {}
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B'
+  const units = ['B', 'KB', 'MB', 'GB']
+  const i = Math.floor(Math.log(bytes) / Math.log(1024))
+  const val = bytes / Math.pow(1024, i)
+  return `${val.toFixed(i > 0 ? 1 : 0)} ${units[i]}`
+}