task-summary-extractor 8.3.0 → 9.0.0

package/src/services/video.js

@@ -14,6 +14,7 @@ const fs = require('fs');
 const path = require('path');
 const { SPEED, SEG_TIME, PRESET } = require('../config');
 const { fmtDuration } = require('../utils/format');
+const { c } = require('../utils/colors');
 
 // ======================== BINARY DETECTION ========================
 
@@ -181,7 +182,7 @@ function compressAndSegment(inputFile, outputDir) {
 
     const result = spawnSync(getFFmpeg(), args, { stdio: 'inherit' });
     if (result.status !== 0) {
-      console.warn(`  ⚠ ffmpeg exited with code ${result.status} (output may still be usable)`);
+      console.warn(`  ${c.warn(`ffmpeg exited with code ${result.status} (output may still be usable)`)}`);
     }
   } else {
     console.log(`  Compressing (single output, ${effectiveDuration ? fmtDuration(effectiveDuration) : '?'} effective)...`);
@@ -196,7 +197,7 @@ function compressAndSegment(inputFile, outputDir) {
 
     const result = spawnSync(getFFmpeg(), args, { stdio: 'inherit' });
     if (result.status !== 0) {
-      console.warn(`  ⚠ ffmpeg exited with code ${result.status}`);
+      console.warn(`  ${c.warn(`ffmpeg exited with code ${result.status}`)}`);
     }
   }
 
@@ -214,7 +215,7 @@ function compressAndSegment(inputFile, outputDir) {
       valid.push(seg);
     } else {
       corrupt.push(seg);
-      console.warn(`  ⚠ Corrupt segment detected: ${path.basename(seg)} (missing moov atom)`);
+      console.warn(`  ${c.warn(`Corrupt segment detected: ${path.basename(seg)} (missing moov atom)`)}`);
     }
   }
 
@@ -239,7 +240,7 @@ function compressAndSegment(inputFile, outputDir) {
         const dest = path.join(outputDir, 'segment_00.mp4');
         fs.renameSync(fallbackPath, dest);
         segments = [dest];
-        console.log(`  ✓ Re-encoded successfully as single segment`);
+        console.log(`  ${c.success('Re-encoded successfully as single segment')}`);
       } else {
         // Re-segment the fallback
         const reSegDir = path.join(outputDir, '_reseg');
@@ -264,10 +265,10 @@ function compressAndSegment(inputFile, outputDir) {
           .filter(f => f.startsWith('segment_') && f.endsWith('.mp4'))
           .sort()
           .map(f => path.join(outputDir, f));
-        console.log(`  ✓ Re-segmented from fallback: ${segments.length} segment(s)`);
+        console.log(`  ${c.success(`Re-segmented from fallback: ${segments.length} segment(s)`)}`);
       }
     } else {
-      console.error(`  ✗ Fallback re-encode also failed`);
+      console.error(`  ${c.error('Fallback re-encode also failed')}`);
       try { fs.unlinkSync(fallbackPath); } catch {}
     }
   } else if (corrupt.length > 0 && !needsSegmentation) {
@@ -285,9 +286,122 @@ function compressAndSegment(inputFile, outputDir) {
     const retryResult = spawnSync(getFFmpeg(), retryArgs, { stdio: 'inherit' });
     if (retryResult.status === 0 && verifySegment(retryPath)) {
       segments = [retryPath];
-      console.log(`  ✓ Retry succeeded`);
+      console.log(`  ${c.success('Retry succeeded')}`);
     } else {
-      console.error(`  ✗ Retry also produced invalid output`);
+      console.error(`  ${c.error('Retry also produced invalid output')}`);
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * Compress and segment an audio-only file using ffmpeg.
+ * No video stream — just audio compression + segmentation in MP4/M4A container
+ * (for Gemini File API compatibility).
+ *
+ * Returns sorted array of segment file paths.
+ */
+function compressAndSegmentAudio(inputFile, outputDir) {
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const duration = probeFormat(inputFile, 'duration');
+  const durationSec = duration ? parseFloat(duration) : null;
+  const effectiveDuration = durationSec ? durationSec / SPEED : null;
+  const channels = parseInt(probe(inputFile, 'a:0', 'channels') || '1', 10);
+  const sampleRate = probe(inputFile, 'a:0', 'sample_rate') || '16000';
+  const audioBr = channels >= 2 ? '128k' : '64k';
+
+  console.log(`  Duration : ${duration ? fmtDuration(parseFloat(duration)) : 'unknown'}${effectiveDuration ? ` (${fmtDuration(effectiveDuration)} at ${SPEED}x)` : ''}`);
+  console.log(`  Audio-only mode | ${SPEED}x speed | ${audioBr} bitrate`);
+
+  const encodingArgs = [
+    '-af', `atempo=${SPEED}`,
+    '-c:a', 'aac', '-b:a', audioBr, '-ar', sampleRate, '-ac', String(channels),
+    '-vn',  // no video
+    '-movflags', '+faststart',
+  ];
+
+  const needsSegmentation = effectiveDuration === null || effectiveDuration > SEG_TIME;
+
+  if (needsSegmentation) {
+    console.log(`  Compressing (segmented, ${SEG_TIME}s chunks)...`);
+    const args = [
+      '-y', '-i', inputFile,
+      ...encodingArgs,
+      '-f', 'segment', '-segment_time', String(SEG_TIME), '-reset_timestamps', '1',
+      path.join(outputDir, 'segment_%02d.m4a'),
+    ];
+    const result = spawnSync(getFFmpeg(), args, { stdio: 'inherit' });
+    if (result.status !== 0) {
+      console.warn(`  ${c.warn(`ffmpeg exited with code ${result.status} (output may still be usable)`)}`);
+    }
+  } else {
+    console.log(`  Compressing (single output, ${effectiveDuration ? fmtDuration(effectiveDuration) : '?'} effective)...`);
+    const outPath = path.join(outputDir, 'segment_00.m4a');
+    const args = ['-y', '-i', inputFile, ...encodingArgs, outPath];
+    const result = spawnSync(getFFmpeg(), args, { stdio: 'inherit' });
+    if (result.status !== 0) {
+      console.warn(`  ${c.warn(`ffmpeg exited with code ${result.status}`)}`);
+    }
+  }
+
+  // Collect segments (both .mp4 and .m4a)
+  let segments = fs.readdirSync(outputDir)
+    .filter(f => f.startsWith('segment_') && (f.endsWith('.m4a') || f.endsWith('.mp4')))
+    .sort()
+    .map(f => path.join(outputDir, f));
+
+  // Validate segments
+  const valid = [];
+  const corrupt = [];
+  for (const seg of segments) {
+    if (verifySegment(seg)) {
+      valid.push(seg);
+    } else {
+      corrupt.push(seg);
+      console.warn(`  ${c.warn(`Corrupt audio segment: ${path.basename(seg)}`)}`);
+    }
+  }
+
+  if (corrupt.length > 0) {
+    console.log(`  Retrying ${corrupt.length} corrupt segment(s)...`);
+    const fallbackPath = path.join(outputDir, '_fallback_full.m4a');
+    const fbArgs = ['-y', '-i', inputFile, ...encodingArgs, fallbackPath];
+    const fbResult = spawnSync(getFFmpeg(), fbArgs, { stdio: 'inherit' });
+    if (fbResult.status === 0 && verifySegment(fallbackPath)) {
+      for (const seg of corrupt) { try { fs.unlinkSync(seg); } catch {} }
+      if (segments.length === 1) {
+        const dest = path.join(outputDir, 'segment_00.m4a');
+        fs.renameSync(fallbackPath, dest);
+        segments = [dest];
+        console.log(`  ${c.success('Re-encoded as single segment')}`);
+      } else {
+        // Re-segment
+        const reSegDir = path.join(outputDir, '_reseg');
+        fs.mkdirSync(reSegDir, { recursive: true });
+        const rsArgs = [
+          '-y', '-i', fallbackPath,
+          '-c', 'copy', '-vn',
+          '-f', 'segment', '-segment_time', String(SEG_TIME), '-reset_timestamps', '1',
+          path.join(reSegDir, 'segment_%02d.m4a'),
+        ];
+        spawnSync(getFFmpeg(), rsArgs, { stdio: 'inherit' });
+        const reSegs = fs.readdirSync(reSegDir).filter(f => f.endsWith('.m4a')).sort();
+        for (const f of reSegs) {
+          fs.renameSync(path.join(reSegDir, f), path.join(outputDir, f));
+        }
+        try { fs.rmSync(reSegDir, { recursive: true }); } catch {}
+        try { fs.unlinkSync(fallbackPath); } catch {}
+        segments = fs.readdirSync(outputDir)
+          .filter(f => f.startsWith('segment_') && (f.endsWith('.m4a') || f.endsWith('.mp4')))
+          .sort()
+          .map(f => path.join(outputDir, f));
+        console.log(`  ${c.success(`Re-segmented from fallback: ${segments.length} segment(s)`)}`);
+      }
+    } else {
+      console.error(`  ${c.error('Fallback audio re-encode failed')}`);
+      try { fs.unlinkSync(fallbackPath); } catch {}
     }
   }
 
@@ -299,6 +413,7 @@ module.exports = {
   probe,
   probeFormat,
   compressAndSegment,
+  compressAndSegmentAudio,
   verifySegment,
   getFFmpeg,
   getFFprobe,

package/src/utils/adaptive-budget.js

@@ -14,6 +14,8 @@
 
 'use strict';
 
+const config = require('../config');
+
 // ======================== BUDGET RANGES ========================
 
 const BUDGET = {
@@ -21,12 +23,12 @@ const BUDGET = {
   MIN: 8192,
   /** Base thinking budget for a simple segment */
   BASE: 16384,
-  /** Maximum thinking budget per segment (avoid eating output token pool) */
-  MAX: 32768,
+  /** Maximum thinking budget per segment — dynamically read from model config */
+  get MAX() { return config.getMaxThinkingBudget(); },
   /** Base compilation thinking budget */
   COMPILATION_BASE: 10240,
-  /** Max compilation thinking budget */
-  COMPILATION_MAX: 24576,
+  /** Max compilation thinking budget — dynamically read from model config */
+  get COMPILATION_MAX() { return config.getMaxThinkingBudget(); },
 };
 
 // ======================== COMPLEXITY ANALYSIS ========================

package/src/utils/checkpoint.js

@@ -11,6 +11,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { c } = require('./colors');
 
 const STATE_FILE = '.pipeline-state.json';
 
@@ -68,7 +69,7 @@ class Progress {
     try {
       fs.writeFileSync(this.filePath, JSON.stringify(this.state, null, 2), 'utf8');
     } catch (err) {
-      console.warn(`  ⚠ Could not save progress: ${err.message}`);
+      console.warn(`  ${c.warn(`Could not save progress: ${err.message}`)}`);
     }
   }
 

package/src/utils/cli.js

@@ -17,6 +17,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { c } = require('./colors');
 
 /**
  * Parse command-line arguments into flags and positional args.
@@ -36,6 +37,7 @@ function parseArgs(argv) {
     'resume', 'reanalyze', 'dry-run',
     'dynamic', 'deep-dive', 'update-progress',
     'no-focused-pass', 'no-learning', 'no-diff',
+    'no-html',
   ]);
 
   for (let i = 0; i < argv.length; i++) {
@@ -89,7 +91,12 @@ const SKIP_FOLDER_NAMES = new Set([
  */
 function discoverFolders(projectRoot) {
   const VIDEO_EXTS = new Set(['.mp4', '.mkv', '.avi', '.mov', '.webm']);
-  const DOC_EXTS = new Set(['.vtt', '.txt', '.pdf', '.docx', '.doc', '.srt', '.csv', '.md']);
+  const AUDIO_EXTS = new Set(['.mp3', '.wav', '.m4a', '.ogg', '.flac', '.aac', '.wma']);
+  const DOC_EXTS = new Set([
+    '.vtt', '.txt', '.pdf', '.docx', '.doc', '.srt', '.csv', '.md',
+    '.xlsx', '.xls', '.pptx', '.ppt', '.odt', '.odp', '.ods', '.rtf', '.epub',
+    '.html', '.htm',
+  ]);
   const folders = [];
 
   let entries;
@@ -105,6 +112,7 @@ function discoverFolders(projectRoot) {
 
     const absPath = path.join(projectRoot, entry.name);
     let hasVideo = false;
+    let hasAudio = false;
     let docCount = 0;
     let hasRuns = false;
 
@@ -116,6 +124,7 @@ function discoverFolders(projectRoot) {
         if (item.isFile()) {
           const ext = path.extname(item.name).toLowerCase();
           if (VIDEO_EXTS.has(ext)) hasVideo = true;
+          if (AUDIO_EXTS.has(ext)) hasAudio = true;
           if (DOC_EXTS.has(ext)) docCount++;
         } else if (item.isDirectory() && depth === 0) {
           if (item.name === 'runs') hasRuns = true;
@@ -128,15 +137,17 @@ function discoverFolders(projectRoot) {
     scan(absPath);
 
     // Only include folders with at least some content
-    if (hasVideo || docCount > 0) {
+    if (hasVideo || hasAudio || docCount > 0) {
       const parts = [];
       if (hasVideo) parts.push('video');
+      if (hasAudio) parts.push('audio');
       if (docCount > 0) parts.push(`${docCount} doc(s)`);
       if (hasRuns) parts.push('has runs');
       folders.push({
         name: entry.name,
         absPath,
         hasVideo,
+        hasAudio,
         docCount,
         hasRuns,
         description: parts.join(', '),
@@ -159,18 +170,23 @@ async function selectFolder(projectRoot) {
   const folders = discoverFolders(projectRoot);
 
   if (folders.length === 0) {
-    console.log('\n  No call/project folders found in the current directory.');
-    console.log('  Create a folder with your recording or documents, then run again.\n');
+    console.log('');
+    console.log(c.warn('No call/project folders found in the current directory.'));
+    console.log(c.muted('  Create a folder with your recording or documents, then run again.'));
+    console.log('');
     return null;
   }
 
   console.log('');
-  console.log('  Available folders:');
-  console.log('  ─────────────────');
+  console.log(c.heading('  📂 Available Folders'));
+  console.log(c.dim('  ' + '─'.repeat(50)));
   folders.forEach((f, i) => {
-    const icon = f.hasVideo ? '🎥' : '📄';
-    const mode = f.hasVideo ? '' : ' (docs only → use --dynamic)';
-    console.log(`    [${i + 1}] ${icon} ${f.name}  — ${f.description}${mode}`);
+    const icon = f.hasVideo ? '🎥' : f.hasAudio ? '🎵' : '📄';
+    const num = c.cyan(`[${i + 1}]`);
+    const name = c.bold(f.name);
+    const desc = c.dim(f.description);
+    const mode = (!f.hasVideo && !f.hasAudio) ? c.yellow(' (docs only)') : '';
+    console.log(`    ${num} ${icon} ${name}  ${desc}${mode}`);
   });
   console.log('');
 
@@ -237,24 +253,24 @@ async function selectModel(GEMINI_MODELS, currentModel) {
   }
 
   console.log('');
-  console.log('  ┌──────────────────────────────────────────────────────────────────────────────┐');
-  console.log('  │                        🤖  Gemini Model Selection                            │');
-  console.log('  └──────────────────────────────────────────────────────────────────────────────┘');
+  console.log(c.heading('  ┌──────────────────────────────────────────────────────────────────────────────┐'));
+  console.log(c.heading('  │                        🤖  Gemini Model Selection                            │'));
+  console.log(c.heading('  └──────────────────────────────────────────────────────────────────────────────┘'));
 
   for (const [, tier] of Object.entries(tiers)) {
     if (tier.models.length === 0) continue;
     console.log('');
-    console.log(`  ${tier.icon} ${tier.label}`);
-    console.log('  ' + '─'.repeat(76));
+    console.log(`  ${tier.icon} ${c.bold(tier.label)}`);
+    console.log(c.dim('  ' + '─'.repeat(76)));
 
     for (const m of tier.models) {
       const isDefault = m.id === currentModel;
-      const marker = isDefault ? ' ← default' : '';
-      const thinkTag = m.thinking ? ' [thinking]' : '';
+      const marker = isDefault ? c.green(' ← default') : '';
+      const thinkTag = m.thinking ? c.magenta(' [thinking]') : '';
 
       // Line 1: number, name, description
-      console.log(`    [${m.idx}] ${m.name}${thinkTag}${marker}`);
-      console.log(`        ${m.description}`);
+      console.log(`    ${c.cyan(`[${m.idx}]`)} ${c.bold(m.name)}${thinkTag}${marker}`);
+      console.log(`        ${c.dim(m.description)}`);
 
       // Line 2: specs
       const ctxStr = fmtContext(m.contextWindow);
@@ -262,8 +278,8 @@ async function selectModel(GEMINI_MODELS, currentModel) {
       const inPrice = `$${m.pricing.inputPerM.toFixed(m.pricing.inputPerM < 0.1 ? 4 : 2)}/1M in`;
       const outPrice = `$${m.pricing.outputPerM.toFixed(m.pricing.outputPerM < 1 ? 2 : 2)}/1M out`;
       const thinkPrice = m.thinking ? ` · $${m.pricing.thinkingPerM.toFixed(2)}/1M think` : '';
-      console.log(`        Context: ${ctxStr} tokens · Max output: ${outStr} · ${m.costEstimate}`);
-      console.log(`        Pricing: ${inPrice} · ${outPrice}${thinkPrice}`);
+      console.log(`        ${c.dim('Context:')} ${ctxStr} · ${c.dim('Max output:')} ${outStr} · ${c.highlight(m.costEstimate)}`);
+      console.log(`        ${c.dim('Pricing:')} ${inPrice} · ${outPrice}${thinkPrice}`);
     }
   }
 
@@ -277,7 +293,7 @@ async function selectModel(GEMINI_MODELS, currentModel) {
 
       // Enter = keep default
       if (!trimmed) {
-        console.log(`  → Using ${GEMINI_MODELS[currentModel].name}`);
+        console.log(c.success(`Using ${GEMINI_MODELS[currentModel].name}`));
         resolve(currentModel);
         return;
       }
@@ -286,14 +302,14 @@ async function selectModel(GEMINI_MODELS, currentModel) {
       const num = parseInt(trimmed, 10);
       if (!isNaN(num) && indexMap[num]) {
         const chosen = indexMap[num];
-        console.log(`  → Selected ${GEMINI_MODELS[chosen].name}`);
+        console.log(c.success(`Selected ${GEMINI_MODELS[chosen].name}`));
         resolve(chosen);
         return;
       }
 
       // Direct model ID input
       if (GEMINI_MODELS[trimmed]) {
-        console.log(`  → Selected ${GEMINI_MODELS[trimmed].name}`);
+        console.log(c.success(`Selected ${GEMINI_MODELS[trimmed].name}`));
         resolve(trimmed);
         return;
       }
@@ -305,12 +321,12 @@ async function selectModel(GEMINI_MODELS, currentModel) {
         GEMINI_MODELS[id].name.toLowerCase().includes(lower)
       );
       if (match) {
-        console.log(`  → Matched ${GEMINI_MODELS[match].name}`);
+        console.log(c.success(`Matched ${GEMINI_MODELS[match].name}`));
         resolve(match);
         return;
       }
 
-      console.log(`  ⚠ Unknown selection "${trimmed}" — using default (${currentModel})`);
+      console.log(c.warn(`Unknown selection "${trimmed}" — using default (${currentModel})`));
       resolve(currentModel);
     });
   });
@@ -321,92 +337,97 @@ async function selectModel(GEMINI_MODELS, currentModel) {
  * Callers should catch this and exit cleanly (no process.exit in library code).
  */
 function showHelp() {
+  const h = (s) => c.heading(s);
+  const f = (flag, desc) => `    ${c.green(flag.padEnd(38))}${desc}`;
+  const f2 = (desc) => `    ${''.padEnd(38)}${c.dim(desc)}`;
+
+  const pkg = (() => {
+    try { return JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf8')); }
+    catch { return { version: '?.?.?' }; }
+  })();
+
   console.log(`
-  Usage: taskex [options] [folder]
-         taskex config [--show | --clear]
-         node process_and_upload.js [options] [folder]
-
-  AI-powered meeting analysis & document generation pipeline.
-  If no folder is specified, shows an interactive folder selector.
-  If you cd into a folder, just run: taskex
-
-  Subcommands:
-    config                            Interactive global config setup (~/.taskexrc)
-    config --show                     Show saved config (masked secrets)
-    config --clear                    Remove global config file
-
-  Arguments:
-    [folder]                          Path to the call/project folder (optional — interactive if omitted)
-
-  Modes:
-    (default)                         Video analysis — compress, analyze, extract, compile
-    --dynamic                         Document-only mode — no video required, generates docs from context + request
-    --update-progress                 Track item completion via git since last analysis
-    --deep-dive                       (after video analysis) Generate explanatory docs per topic discussed
-
-  Core Options:
-    --name <name>                     Your name (skips interactive prompt)
-    --model <id>                      Gemini model to use (skips interactive selector)
-                                      Models: gemini-3.1-pro-preview, gemini-3-flash-preview,
-                                      gemini-2.5-pro, gemini-2.5-flash (default), gemini-2.5-flash-lite
-    --skip-upload                     Skip all Firebase Storage uploads
-    --force-upload                    Re-upload files even if they already exist in Storage
-    --no-storage-url                  Disable Storage URL optimization (force Gemini File API)
-    --skip-compression                Skip video compression (use existing segments)
-    --skip-gemini                     Skip Gemini AI analysis
-    --resume                          Resume from last checkpoint (skip completed steps)
-    --reanalyze                       Force re-analysis of all segments
-    --dry-run                         Show what would be done without executing
-
-  Dynamic Mode:
-    --dynamic                         Enable document-only mode (no video required)
-    --request <text>                  What to generate — e.g. "Plan migration from X to Y"
-                                      (prompted interactively if omitted)
-
-  Progress Tracking:
-    --repo <path>                     Path to the project git repo (for change detection)
-
-  Configuration:
-    --gemini-key <key>                Gemini API key (overrides .env / ~/.taskexrc)
-    --firebase-key <key>              Firebase API key (overrides .env / ~/.taskexrc)
-    --firebase-project <id>           Firebase project ID (overrides .env / ~/.taskexrc)
-    --firebase-bucket <bucket>        Firebase storage bucket (overrides .env / ~/.taskexrc)
-    --firebase-domain <domain>        Firebase auth domain (overrides .env / ~/.taskexrc)
-
-    Config resolution (highest wins):
-      CLI flags → env vars → CWD .env → ~/.taskexrc → package .env
-
-  Tuning:
-    --parallel <n>                    Max parallel uploads (default: 3)
-    --parallel-analysis <n>           Concurrent segment analysis batches (default: 2)
-    --thinking-budget <n>             Thinking token budget per segment (default: 24576)
-    --compilation-thinking-budget <n> Thinking tokens for final compilation (default: 10240)
-    --log-level <level>               Log level: debug, info, warn, error (default: info)
-    --output <dir>                    Custom output directory for results
-    --no-focused-pass                 Disable focused re-analysis for weak segments
-    --no-learning                     Disable learning loop (historical budget adjustments)
-    --no-diff                         Disable diff comparison against previous runs
-
-  Info:
-    --help, -h                        Show this help message
-    --version, -v                     Show version
-
-  Examples:
-    taskex                                                                  Interactive (cd into folder first)
-    taskex "call 1"                                                         Analyze a call (with video)
-    taskex --name "Jane" --skip-upload "call 1"                             Skip Firebase, set name
-    taskex --gemini-key "AIza..." --skip-upload "call 1"                    Pass API key inline (no .env)
-    taskex --model gemini-2.5-pro "call 1"                                  Use Gemini 2.5 Pro model
-    taskex --resume "call 1"                                                Resume interrupted run
-    taskex --deep-dive "call 1"                                             Video analysis + deep dive docs
-    taskex --dynamic "my-project"                                           Doc-only mode (prompted for request)
-    taskex --dynamic --request "Plan API migration" "specs"                 Dynamic with request
-    taskex --update-progress --repo "C:\\my-project" "call 1"               Progress tracking via git
-
-  First-time setup:
-    taskex config                                                           Save API keys globally (~/.taskexrc)
-    taskex config --show                                                    View saved config
-    taskex config --clear                                                   Remove saved config
+  ${c.bold(c.cyan('taskex'))} ${c.dim(`v${pkg.version}`)} — AI-powered meeting analysis & document generation
+
+  ${h('USAGE')}
+    ${c.bold('taskex')} ${c.dim('[options]')} ${c.cyan('[folder]')}
+    ${c.bold('taskex setup')} ${c.dim('[--check | --silent]')}
+    ${c.bold('taskex config')} ${c.dim('[--show | --clear]')}
+
+  ${h('SUBCOMMANDS')}
+${f('setup', 'Full interactive setup (prerequisites, deps, .env)')}
+${f('setup --check', 'Validation only — verify environment')}
+${f('config', 'Interactive global config (~/.taskexrc)')}
+${f('config --show', 'Show saved config (masked secrets)')}
+${f('config --clear', 'Remove global config')}
+
+  ${h('MODES')}
+${f('(default)', 'Video/audio analysis — compress, analyze, compile')}
+${f('--dynamic', 'Document generation — no media required')}
+${f('--update-progress', 'Track item completion via git changes')}
+${f('--deep-dive', 'Generate explanatory docs per topic')}
+
+  ${h('CORE OPTIONS')}
+${f('--name <name>', 'Your name (skip interactive prompt)')}
+${f('--model <id>', 'Gemini model (skip interactive selector)')}
+${f('--format <type>', 'Output formats: md, html, json, pdf, docx, all (default: all)')}
+${f('--min-confidence <level>', 'Filter: high, medium, low (default: all)')}
+${f('--output <dir>', 'Custom output directory for results')}
+${f('--skip-upload', 'Skip Firebase Storage uploads')}
+${f('--skip-compression', 'Use existing segments (no re-compress)')}
+${f('--skip-gemini', 'Skip AI analysis')}
+${f('--resume', 'Resume from last checkpoint')}
+${f('--reanalyze', 'Force re-analysis of all segments')}
+${f('--dry-run', 'Preview without executing')}
+
+  ${h('TUNING')}
+${f('--parallel <n>', 'Max parallel uploads (default: 3)')}
+${f('--parallel-analysis <n>', 'Concurrent analysis batches (default: 2)')}
+${f('--thinking-budget <n>', 'Thinking tokens per segment (default: 24576)')}
+${f('--compilation-thinking-budget <n>', 'Thinking tokens for compilation (default: 10240)')}
+${f('--no-focused-pass', 'Disable focused re-analysis')}
+${f('--no-learning', 'Disable learning loop')}
+${f('--no-diff', 'Disable diff comparison')}
+${f('--no-html', 'Skip HTML output (Markdown only)')}
+${f('--log-level <level>', 'debug, info, warn, error (default: info)')}
+
+  ${h('DYNAMIC MODE')}
+${f('--dynamic', 'Enable document generation mode')}
+${f('--request <text>', 'What to generate (prompted if omitted)')}
+
+  ${h('PROGRESS TRACKING')}
+${f('--update-progress', 'Detect changes via git since last analysis')}
+${f('--repo <path>', 'Path to project git repo')}
+
+  ${h('UPLOAD & STORAGE')}
+${f('--skip-upload', 'Skip all Firebase uploads')}
+${f('--force-upload', 'Re-upload even if files exist')}
+${f('--no-storage-url', 'Force Gemini File API (no storage URLs)')}
+
+  ${h('CONFIGURATION')}
+${f('--gemini-key <key>', 'Gemini API key (overrides .env)')}
+${f('--firebase-key <key>', 'Firebase API key')}
+${f('--firebase-project <id>', 'Firebase project ID')}
+${f('--firebase-bucket <bucket>', 'Firebase storage bucket')}
+${f('--firebase-domain <domain>', 'Firebase auth domain')}
+${f2('Resolution: CLI flags → env → .env → ~/.taskexrc')}
+
+  ${h('INFO')}
+${f('--help, -h', 'Show this help message')}
+${f('--version, -v', 'Show version')}
+
+  ${h('EXAMPLES')}
+    ${c.dim('$')} taskex ${c.dim('# Interactive mode')}
+    ${c.dim('$')} taskex "call 1" ${c.dim('# Analyze a call')}
+    ${c.dim('$')} taskex --name "Jane" --skip-upload "call 1"
+    ${c.dim('$')} taskex --model gemini-2.5-pro --deep-dive "call 1"
+    ${c.dim('$')} taskex --dynamic --request "Plan API migration" "specs"
+    ${c.dim('$')} taskex --min-confidence medium "call 1" ${c.dim('# Filter low-confidence')}
+    ${c.dim('$')} taskex --format md "call 1" ${c.dim('# Markdown only')}
+    ${c.dim('$')} taskex --format pdf "call 1" ${c.dim('# PDF report')}
+    ${c.dim('$')} taskex --format docx "call 1" ${c.dim('# Word document')}
+    ${c.dim('$')} taskex --resume "call 1" ${c.dim('# Resume interrupted run')}
+    ${c.dim('$')} taskex --update-progress --repo ./my-project "call 1"
   `);
   // Signal early exit — pipeline checks for help flag before calling this
   throw Object.assign(new Error('HELP_SHOWN'), { code: 'HELP_SHOWN' });