task-summary-extractor 9.2.2 → 9.3.1

package/.env.example

@@ -12,8 +12,8 @@ GEMINI_API_KEY=your_gemini_api_key
 GEMINI_MODEL=gemini-2.5-flash
 
 # ======================== VIDEO PROCESSING ========================
-# Speed multiplier (default: 1.5)
-VIDEO_SPEED=1.5
+# Speed multiplier (default: 1.6)
+VIDEO_SPEED=1.6
 # Segment duration in seconds (default: 280)
 VIDEO_SEGMENT_TIME=280
 # ffmpeg preset: ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow
@@ -36,3 +36,7 @@ THINKING_BUDGET=24576
 COMPILATION_THINKING_BUDGET=10240
 # Max polling time for Gemini File API processing in ms (default: 300000 = 5 min)
 GEMINI_POLL_TIMEOUT_MS=300000
+
+# ======================== NPM PUBLISHING ========================
+# Automation token for npm publish (optional — if not set, browser sign-in is used)
+# NPM_TOKEN=npm_your_token_here

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-summary-extractor",
-  "version": "9.2.2",
+  "version": "9.3.1",
   "description": "AI-powered meeting analysis & document generation CLI — video + document processing, deep dive docs, dynamic mode, interactive CLI with model selection, confidence scoring, learning loop, git progress tracking",
   "main": "process_and_upload.js",
   "bin": {
@@ -15,8 +15,7 @@
     ".env.example",
     "README.md",
     "QUICK_START.md",
-    "ARCHITECTURE.md",
-    "EXPLORATION.md"
+    "ARCHITECTURE.md"
   ],
   "scripts": {
     "setup": "node setup.js",

package/src/config.js

@@ -220,7 +220,7 @@ function getMaxThinkingBudget() {
 
 // ======================== VIDEO PROCESSING ========================
 
-const SPEED = envFloat('VIDEO_SPEED', 1.5);
+const SPEED = envFloat('VIDEO_SPEED', 1.6);
 const SEG_TIME = envInt('VIDEO_SEGMENT_TIME', 280); // seconds — produces segments < 5 min
 const PRESET = env('VIDEO_PRESET', 'slow');
 const VIDEO_EXTS = ['.mp4', '.mkv', '.avi', '.mov', '.webm'];

package/src/modes/deep-summary.js

@@ -0,0 +1,375 @@
+/**
+ * Deep Summary — pre-summarizes context documents before segment analysis
+ * to dramatically reduce input tokens per segment.
+ *
+ * Instead of sending full document content (potentially 500K+ tokens) to
+ * every segment, this module:
+ *  1. Groups documents by priority tier
+ *  2. Sends each group to Gemini for intelligent condensation
+ *  3. Replaces full content with condensed summaries
+ *  4. Preserves "excluded" docs at full fidelity (user-chosen focus docs)
+ *  5. Ensures summaries capture all ticket IDs, action items, statuses
+ *
+ * The user can pick specific docs to EXCLUDE from summarization — these stay
+ * full. The summary pass receives extra instructions to focus on extracting
+ * information related to these excluded docs' topics.
+ *
+ * Token savings: typically 60-80% reduction in per-segment context tokens.
+ */
+
+'use strict';
+
+const { extractJson } = require('../utils/json-parser');
+const { withRetry } = require('../utils/retry');
+const { estimateTokens } = require('../utils/context-manager');
+const { c } = require('../utils/colors');
+const config = require('../config');
+
+// ======================== CONSTANTS ========================
+
+/** Max tokens for a single summarization call output */
+const SUMMARY_MAX_OUTPUT = 16384;
+
+/** Max input chars to send in one summarization batch (~200K tokens @ 0.3 tok/char) */
+const BATCH_MAX_CHARS = 600000;
+
+/** Minimum content length (chars) to bother summarizing — below this, keep full */
+const MIN_SUMMARIZE_LENGTH = 500;
+
+// ======================== BATCH BUILDER ========================
+
+/**
+ * Group documents into batches that fit within the batch char limit.
+ * Each batch will be summarized in a single Gemini call.
+ *
+ * @param {Array} docs - Context docs to batch [{type, fileName, content}]
+ * @param {number} [maxChars=BATCH_MAX_CHARS] - Max chars per batch
+ * @returns {Array<Array>} Batches of docs
+ */
+function buildBatches(docs, maxChars = BATCH_MAX_CHARS) {
+  const batches = [];
+  let currentBatch = [];
+  let currentChars = 0;
+
+  for (const doc of docs) {
+    const docChars = doc.content ? doc.content.length : 0;
+
+    // If this single doc exceeds the batch limit, it gets its own batch
+    if (docChars > maxChars) {
+      if (currentBatch.length > 0) {
+        batches.push(currentBatch);
+        currentBatch = [];
+        currentChars = 0;
+      }
+      batches.push([doc]);
+      continue;
+    }
+
+    if (currentChars + docChars > maxChars && currentBatch.length > 0) {
+      batches.push(currentBatch);
+      currentBatch = [];
+      currentChars = 0;
+    }
+
+    currentBatch.push(doc);
+    currentChars += docChars;
+  }
+
+  if (currentBatch.length > 0) {
+    batches.push(currentBatch);
+  }
+
+  return batches;
+}
+
+// ======================== SUMMARIZE ONE BATCH ========================
+
+/**
+ * Summarize a batch of documents into a condensed representation.
+ *
+ * @param {object} ai - Gemini AI instance
+ * @param {Array} docs - Documents in this batch
+ * @param {object} [opts]
+ * @param {string[]} [opts.focusTopics=[]] - Topics to focus on (from excluded docs)
+ * @param {number} [opts.thinkingBudget=8192] - Thinking token budget
+ * @param {number} [opts.batchIndex=0] - Batch number for logging
+ * @param {number} [opts.totalBatches=1] - Total batches for logging
+ * @returns {Promise<{summaries: Map<string, string>, tokenUsage: object}|null>}
+ */
+async function summarizeBatch(ai, docs, opts = {}) {
+  const {
+    focusTopics = [],
+    thinkingBudget = 8192,
+    batchIndex = 0,
+    totalBatches = 1,
+  } = opts;
+
+  const docEntries = docs
+    .filter(d => d.type === 'inlineText' && d.content)
+    .map(d => `=== DOCUMENT: ${d.fileName} ===\n${d.content}`);
+
+  if (docEntries.length === 0) return null;
+
+  const focusSection = focusTopics.length > 0
+    ? `\n\nFOCUS AREAS — The user has selected certain documents to keep at full fidelity. ` +
+      `Your summaries must be especially thorough about information related to these topics:\n` +
+      focusTopics.map((t, i) => `  ${i + 1}. ${t}`).join('\n') +
+      `\n\nFor every ticket ID, action item, blocker, or status mentioned in relation to these ` +
+      `focus areas, include them verbatim in the summary. Do NOT omit any IDs or assignments.`
+    : '';
+
+  const promptText = `You are a precision document summarizer for a meeting analysis pipeline.
+
+Your job: read ALL documents below and produce a CONDENSED version of each that preserves:
+- Every ticket ID, task ID, CR number, or reference number (verbatim)
+- All assignees, reviewers, and responsible parties
+- All statuses (open, closed, in_progress, blocked, etc.)
+- All action items and their owners
+- All blockers, dependencies, and deadlines
+- Key decisions and their rationale
+- File paths and code references
+- Numerical data (percentages, counts, dates, versions)
+
+What to remove:
+- Verbose explanations of well-known concepts
+- Redundant phrasing and filler text
+- Formatting-only content (decorative headers, dividers)
+- Boilerplate/template text that adds no information
+${focusSection}
+
+OUTPUT FORMAT:
+Return valid JSON with this structure:
+{
+  "summaries": {
+    "<fileName>": "<condensed text — plain text, preserving all key info>",
+    ...
+  },
+  "metadata": {
+    "originalTokensEstimate": <number>,
+    "summaryTokensEstimate": <number>,
+    "compressionRatio": <number between 0 and 1>
+  }
+}
+
+Aim for 70-80% size reduction while preserving ALL actionable information.
+Every ID, every name, every status must survive the summarization.
+
+DOCUMENTS TO SUMMARIZE (${docEntries.length} documents):
+
+${docEntries.join('\n\n')}`;
+
+  const requestPayload = {
+    model: config.GEMINI_MODEL,
+    contents: [{ role: 'user', parts: [{ text: promptText }] }],
+    config: {
+      systemInstruction: 'You are a lossless information compressor. Preserve every ID, name, status, assignment, and actionable detail. Output valid JSON only.',
+      maxOutputTokens: SUMMARY_MAX_OUTPUT,
+      temperature: 0,
+      thinkingConfig: { thinkingBudget },
+    },
+  };
+
+  try {
+    const label = totalBatches > 1
+      ? `Deep summary batch ${batchIndex + 1}/${totalBatches}`
+      : 'Deep summary';
+
+    const response = await withRetry(
+      () => ai.models.generateContent(requestPayload),
+      { label, maxRetries: 2, baseDelay: 3000 }
+    );
+
+    const rawText = response.text;
+    const parsed = extractJson(rawText);
+
+    if (!parsed || !parsed.summaries) return null;
+
+    const usage = response.usageMetadata || {};
+    const tokenUsage = {
+      inputTokens: usage.promptTokenCount || 0,
+      outputTokens: usage.candidatesTokenCount || 0,
+      totalTokens: usage.totalTokenCount || 0,
+      thoughtTokens: usage.thoughtsTokenCount || 0,
+    };
+
+    return { summaries: parsed.summaries, metadata: parsed.metadata || {}, tokenUsage };
+  } catch (err) {
+    console.warn(`    ${c.warn(`Deep summary batch ${batchIndex + 1} failed: ${err.message}`)}`);
+    return null;
+  }
+}
+
+// ======================== MAIN ENTRY POINT ========================
+
+/**
+ * Run deep summarization on context documents.
+ *
+ * @param {object} ai - Gemini AI instance
+ * @param {Array} contextDocs - All prepared context docs
+ * @param {object} [opts]
+ * @param {string[]} [opts.excludeFileNames=[]] - Doc fileNames to keep at full fidelity
+ * @param {number} [opts.thinkingBudget=8192] - Thinking budget per batch
+ * @param {Function} [opts.onProgress] - Callback(done, total) for progress
+ * @returns {Promise<{docs: Array, stats: object}>}
+ */
+async function deepSummarize(ai, contextDocs, opts = {}) {
+  const {
+    excludeFileNames = [],
+    thinkingBudget = 8192,
+    onProgress = null,
+  } = opts;
+
+  const excludeSet = new Set(excludeFileNames.map(n => n.toLowerCase()));
+
+  // Partition: docs to summarize vs docs to keep full
+  const toSummarize = [];
+  const keepFull = [];
+
+  for (const doc of contextDocs) {
+    // Keep non-text docs (fileData = PDF etc.) as-is
+    if (doc.type !== 'inlineText') {
+      keepFull.push(doc);
+      continue;
+    }
+
+    // Keep excluded docs at full fidelity
+    if (excludeSet.has(doc.fileName.toLowerCase())) {
+      keepFull.push(doc);
+      continue;
+    }
+
+    // Skip tiny docs — not worth summarizing
+    if (!doc.content || doc.content.length < MIN_SUMMARIZE_LENGTH) {
+      keepFull.push(doc);
+      continue;
+    }
+
+    toSummarize.push(doc);
+  }
+
+  if (toSummarize.length === 0) {
+    return {
+      docs: contextDocs,
+      stats: {
+        summarized: 0,
+        keptFull: keepFull.length,
+        originalTokens: 0,
+        summaryTokens: 0,
+        savedTokens: 0,
+        savingsPercent: 0,
+        totalInputTokens: 0,
+        totalOutputTokens: 0,
+      },
+    };
+  }
+
+  // Build focus topics from excluded docs (tell summarizer what to prioritize)
+  const focusTopics = keepFull
+    .filter(d => d.type === 'inlineText' && excludeSet.has(d.fileName.toLowerCase()))
+    .map(d => d.fileName);
+
+  // Batch documents
+  const batches = buildBatches(toSummarize);
+
+  console.log(`    Batched ${c.highlight(toSummarize.length)} doc(s) into ${c.highlight(batches.length)} summarization batch(es)`);
+  if (focusTopics.length > 0) {
+    console.log(`    Focus topics from ${c.highlight(focusTopics.length)} excluded doc(s):`);
+    focusTopics.forEach(t => console.log(`      ${c.dim('•')} ${c.cyan(t)}`));
+  }
+
+  // Process batches (sequential for now; can add parallelization later)
+  const allSummaries = new Map();
+  let totalInput = 0;
+  let totalOutput = 0;
+  let batchesDone = 0;
+
+  for (let i = 0; i < batches.length; i++) {
+    const result = await summarizeBatch(ai, batches[i], {
+      focusTopics,
+      thinkingBudget,
+      batchIndex: i,
+      totalBatches: batches.length,
+    });
+
+    batchesDone++;
+    if (onProgress) onProgress(batchesDone, batches.length);
+
+    if (result && result.summaries) {
+      for (const [fileName, summary] of Object.entries(result.summaries)) {
+        allSummaries.set(fileName.toLowerCase(), summary);
+      }
+      totalInput += result.tokenUsage.inputTokens;
+      totalOutput += result.tokenUsage.outputTokens;
+    }
+  }
+
+  // Replace doc content with summaries
+  let originalTokens = 0;
+  let summaryTokens = 0;
+  const resultDocs = [];
+
+  for (const doc of contextDocs) {
+    if (doc.type !== 'inlineText') {
+      resultDocs.push(doc);
+      continue;
+    }
+
+    // Check if this doc was excluded (kept full)
+    if (excludeSet.has(doc.fileName.toLowerCase())) {
+      resultDocs.push(doc);
+      continue;
+    }
+
+    // Check if we have a summary for this doc
+    const summaryKey = doc.fileName.toLowerCase();
+    const summary = allSummaries.get(summaryKey);
+
+    if (summary && summary.length > 0) {
+      const origTokens = estimateTokens(doc.content);
+      const sumTokens = estimateTokens(summary);
+      originalTokens += origTokens;
+      summaryTokens += sumTokens;
+
+      resultDocs.push({
+        ...doc,
+        content: `[Deep Summary — original: ~${origTokens.toLocaleString()} tokens → condensed: ~${sumTokens.toLocaleString()} tokens]\n\n${summary}`,
+        _originalLength: doc.content.length,
+        _summaryLength: summary.length,
+        _deepSummarized: true,
+      });
+    } else {
+      // No summary returned — keep original
+      resultDocs.push(doc);
+    }
+  }
+
+  const savedTokens = originalTokens - summaryTokens;
+  const savingsPercent = originalTokens > 0
+    ? parseFloat(((savedTokens / originalTokens) * 100).toFixed(1))
+    : 0;
+
+  return {
+    docs: resultDocs,
+    stats: {
+      summarized: allSummaries.size,
+      keptFull: keepFull.length,
+      originalTokens,
+      summaryTokens,
+      savedTokens,
+      savingsPercent,
+      totalInputTokens: totalInput,
+      totalOutputTokens: totalOutput,
+    },
+  };
+}
+
+// ======================== EXPORTS ========================
+
+module.exports = {
+  deepSummarize,
+  summarizeBatch,
+  buildBatches,
+  SUMMARY_MAX_OUTPUT,
+  BATCH_MAX_CHARS,
+  MIN_SUMMARIZE_LENGTH,
+};

package/src/phases/discover.js

@@ -85,6 +85,7 @@ async function phaseDiscover(ctx) {
   if (opts.resume) activeFlags.push('resume');
   if (opts.reanalyze) activeFlags.push('reanalyze');
   if (opts.dryRun) activeFlags.push('dry-run');
+  if (opts.deepSummary) activeFlags.push('deep-summary');
   if (activeFlags.length > 0) {
     console.log(`  Flags: ${c.yellow(activeFlags.join(', '))}`);
   }

package/src/phases/init.js

@@ -67,6 +67,10 @@ async function phaseInit() {
     disableDiff: !!flags['no-diff'],
     noHtml: !!flags['no-html'],
     deepDive: !!flags['deep-dive'],
+    deepSummary: !!flags['deep-summary'],
+    deepSummaryExclude: typeof flags['exclude-docs'] === 'string'
+      ? flags['exclude-docs'].split(',').map(s => s.trim()).filter(Boolean)
+      : [],  // populated by CLI flag, interactive picker, or kept empty
     dynamic: !!flags.dynamic,
     request: typeof flags.request === 'string' ? flags.request : null,
     updateProgress: !!flags['update-progress'],
@@ -94,36 +98,10 @@ async function phaseInit() {
     opts.runMode = mode;
 
     if (mode !== 'custom') {
-      // Apply preset overrides
-      const { selectRunMode: _ignore, ...cliModule } = require('../utils/cli');
-      // Access RUN_PRESETS from the module
-      const presetOverrides = {
-        fast: {
-          disableFocusedPass: true,
-          disableLearning: true,
-          disableDiff: true,
-          format: 'md,json',
-          formats: new Set(['md', 'json']),
-          modelTier: 'economy',
-        },
-        balanced: {
-          disableFocusedPass: false,
-          disableLearning: false,
-          disableDiff: false,
-          format: 'all',
-          formats: new Set(['md', 'html', 'json', 'pdf', 'docx']),
-          modelTier: 'balanced',
-        },
-        detailed: {
-          disableFocusedPass: false,
-          disableLearning: false,
-          disableDiff: false,
-          format: 'all',
-          formats: new Set(['md', 'html', 'json', 'pdf', 'docx']),
-          modelTier: 'premium',
-        },
-      };
-      const preset = presetOverrides[mode];
+      // Apply preset overrides from the shared RUN_PRESETS definition
+      const { RUN_PRESETS } = require('../utils/cli');
+      const presetDef = RUN_PRESETS[mode];
+      const preset = presetDef ? presetDef.overrides : null;
       if (preset) {
         opts.disableFocusedPass = preset.disableFocusedPass;
         opts.disableLearning = preset.disableLearning;
@@ -322,6 +300,7 @@ function _printRunSummary(opts, modelId, models, targetDir) {
   if (!opts.disableLearning) features.push(c.green('learning'));
   if (!opts.disableDiff) features.push(c.green('diff'));
   if (opts.deepDive) features.push(c.cyan('deep-dive'));
+  if (opts.deepSummary) features.push(c.cyan('deep-summary'));
   if (opts.dynamic) features.push(c.cyan('dynamic'));
   if (opts.resume) features.push(c.yellow('resume'));
   if (opts.dryRun) features.push(c.yellow('dry-run'));

package/src/phases/services.js

@@ -7,6 +7,9 @@ const path = require('path');
 const { initFirebase, uploadToStorage, storageExists } = require('../services/firebase');
 const { initGemini, prepareDocsForGemini } = require('../services/gemini');
 
+// --- Modes ---
+const { deepSummarize } = require('../modes/deep-summary');
+
 // --- Utils ---
 const { parallelMap } = require('../utils/retry');
 
@@ -101,4 +104,61 @@ async function phaseServices(ctx) {
   return { ...ctx, storage, firebaseReady, ai, contextDocs, docStorageUrls, callName };
 }
 
-module.exports = phaseServices;
+// ======================== PHASE: DEEP SUMMARY ========================
+
+/**
+ * Pre-summarize context documents to save input tokens per segment.
+ * Runs only when --deep-summary flag is active.
+ *
+ * @param {object} ctx - Pipeline context with ai, contextDocs, opts
+ * @returns {object} Updated ctx with summarized contextDocs and deepSummaryStats
+ */
+async function phaseDeepSummary(ctx) {
+  const log = getLog();
+  const { opts, ai, contextDocs } = ctx;
+
+  if (!opts.deepSummary || !ai || contextDocs.length === 0) {
+    return { ...ctx, deepSummaryStats: null };
+  }
+
+  console.log('');
+  console.log(c.cyan('  ── Deep Summary — Pre-summarizing context documents ──'));
+  log.step('Deep summary: starting context document pre-summarization');
+  if (log && log.phaseStart) log.phaseStart('deep_summary');
+
+  const excludeNames = opts.deepSummaryExclude || [];
+  let updatedDocs = contextDocs;
+  let deepSummaryStats = null;
+
+  try {
+    const result = await deepSummarize(ai, contextDocs, {
+      excludeFileNames: excludeNames,
+      thinkingBudget: Math.min(8192, opts.thinkingBudget),
+    });
+
+    updatedDocs = result.docs;
+    deepSummaryStats = result.stats;
+
+    if (deepSummaryStats.summarized > 0) {
+      console.log(`  ${c.success(`Summarized ${c.highlight(deepSummaryStats.summarized)} doc(s) — saved ~${c.highlight(deepSummaryStats.savedTokens.toLocaleString())} tokens (${c.yellow(deepSummaryStats.savingsPercent + '%')} reduction)`)}`);
+      console.log(`    ${c.dim('Original:')} ~${deepSummaryStats.originalTokens.toLocaleString()} tokens → ${c.dim('Condensed:')} ~${deepSummaryStats.summaryTokens.toLocaleString()} tokens`);
+      if (deepSummaryStats.keptFull > 0) {
+        console.log(`    ${c.dim('Kept full:')} ${deepSummaryStats.keptFull} doc(s) (excluded from summary)`);
+      }
+      log.step(`Deep summary: ${deepSummaryStats.summarized} docs summarized, ${deepSummaryStats.savedTokens} tokens saved (${deepSummaryStats.savingsPercent}%)`);
+      log.metric('deep_summary', deepSummaryStats);
+    } else {
+      console.log(`  ${c.dim('No documents needed summarization')}`);
+    }
+  } catch (err) {
+    console.warn(`  ${c.warn(`Deep summary failed (continuing with full docs): ${err.message}`)}`);
+    log.warn(`Deep summary failed: ${err.message}`);
+  }
+
+  if (log && log.phaseEnd) log.phaseEnd({ stats: deepSummaryStats });
+  console.log('');
+
+  return { ...ctx, contextDocs: updatedDocs, deepSummaryStats };
+}
+
+module.exports = { phaseServices, phaseDeepSummary };

package/src/pipeline.js

@@ -32,7 +32,7 @@ const { getLog, isShuttingDown, PKG_ROOT, PROJECT_ROOT } = require('./phases/_sh
 // --- Pipeline phases ---
 const phaseInit        = require('./phases/init');
 const phaseDiscover    = require('./phases/discover');
-const phaseServices    = require('./phases/services');
+const { phaseServices, phaseDeepSummary } = require('./phases/services');
 const phaseProcessVideo = require('./phases/process-media');
 const phaseCompile     = require('./phases/compile');
 const phaseOutput      = require('./phases/output');
@@ -46,7 +46,7 @@ const phaseDeepDive    = require('./phases/deep-dive');
 // --- Utils (for run orchestration + alt modes) ---
 const { c } = require('./utils/colors');
 const { findDocsRecursive } = require('./utils/fs');
-const { promptUserText } = require('./utils/cli');
+const { promptUserText, selectDocsToExclude } = require('./utils/cli');
 const { createProgressBar } = require('./utils/progress-bar');
 const { buildHealthReport, printHealthDashboard } = require('./utils/health-dashboard');
 const { saveHistory, buildHistoryEntry } = require('./utils/learning-loop');
@@ -92,9 +92,21 @@ async function run() {
 
   // Phase 3: Services
   bar.setPhase('services');
-  const fullCtx = await phaseServices(ctx);
+  let fullCtx = await phaseServices(ctx);
   bar.tick('Services ready');
 
+  // Phase 3.5 (optional): Deep Summary — pre-summarize context docs
+  if (fullCtx.opts.deepSummary && fullCtx.ai && fullCtx.contextDocs.length > 0) {
+    // Interactive picker: let user choose docs to keep at full fidelity
+    if (process.stdin.isTTY && fullCtx.opts.deepSummaryExclude.length === 0) {
+      const excluded = await selectDocsToExclude(fullCtx.contextDocs);
+      fullCtx.opts.deepSummaryExclude = excluded;
+    }
+    bar.setPhase('deep-summary', 1);
+    fullCtx = await phaseDeepSummary(fullCtx);
+    bar.tick('Docs summarized');
+  }
+
   // Phase 4: Process each media file (video or audio)
   const allSegmentAnalyses = [];
   const allSegmentReports = [];
@@ -117,6 +129,7 @@ async function run() {
     contextDocuments: fullCtx.contextDocs.map(d => d.fileName),
     documentStorageUrls: fullCtx.docStorageUrls,
     firebaseAuthenticated: fullCtx.firebaseReady,
+    deepSummary: fullCtx.deepSummaryStats || null,
     files: [],
   };
 

package/src/services/gemini.js

@@ -90,7 +90,7 @@ async function prepareDocsForGemini(ai, docFileList) {
         const pollStart = Date.now();
         while (file.state === 'PROCESSING') {
           if (Date.now() - pollStart > GEMINI_POLL_TIMEOUT_MS) {
-            console.warn(`    ${c.warn(`${name} — polling timed out after ${(GEMINI_POLL_TIMEOUT_MS / 1000).toFixed(0)}s, skipping`)}`);
+            console.warn(`    ${c.warn(`${name} — file is still processing after ${(GEMINI_POLL_TIMEOUT_MS / 1000).toFixed(0)}s, skipping (you can increase the wait time with GEMINI_POLL_TIMEOUT_MS in .env)`)}`);
             file = null;
             break;
           }
@@ -287,7 +287,7 @@ async function processWithGemini(ai, filePath, displayName, contextDocs = [], pr
     const pollStart = Date.now();
     while (uploaded.state === 'PROCESSING') {
       if (Date.now() - pollStart > GEMINI_POLL_TIMEOUT_MS) {
-        throw new Error(`Gemini file processing timed out after ${(GEMINI_POLL_TIMEOUT_MS / 1000).toFixed(0)}s for ${displayName}. Try again or increase GEMINI_POLL_TIMEOUT_MS.`);
+        throw new Error(`File "${displayName}" is still processing after ${(GEMINI_POLL_TIMEOUT_MS / 1000).toFixed(0)}s. Try again or increase the wait time by setting GEMINI_POLL_TIMEOUT_MS in your .env file.`);
       }
       process.stdout.write(`    Processing${'.'.repeat((waited % 3) + 1)}   \r`);
       await new Promise(r => setTimeout(r, 5000));
@@ -343,7 +343,7 @@ async function processWithGemini(ai, filePath, displayName, contextDocs = [], pr
     buildProgressiveContext(previousAnalyses, userName) || ''
   );
   const docBudget = Math.max(100000, config.GEMINI_CONTEXT_WINDOW - 350000 - prevContextEstimate);
-  console.log(`    Context budget: ${(docBudget / 1000).toFixed(0)}K tokens for docs (${contextDocs.length} available)`);
+  console.log(`    Reference docs budget: ${(docBudget / 1000).toFixed(0)}K (${contextDocs.length} doc${contextDocs.length !== 1 ? 's' : ''} available)`);
 
   const { selected: selectedDocs, excluded, stats } = selectDocsByBudget(
     contextDocs, docBudget, { segmentIndex }

package/src/utils/cli.js

@@ -35,7 +35,7 @@ function parseArgs(argv) {
     'skip-upload', 'force-upload', 'no-storage-url',
     'skip-compression', 'skip-gemini',
     'resume', 'reanalyze', 'dry-run',
-    'dynamic', 'deep-dive', 'update-progress',
+    'dynamic', 'deep-dive', 'deep-summary', 'update-progress',
     'no-focused-pass', 'no-learning', 'no-diff',
     'no-html',
   ]);
@@ -371,6 +371,8 @@ ${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')}
+${f('--deep-summary', 'Pre-summarize context docs (saves ~60-80% input tokens)')}
+${f('--exclude-docs <list>', 'Comma-separated doc names to keep full (use with --deep-summary)')}
 
   ${h('CORE OPTIONS')}
 ${f('--name <name>', 'Your name (skip interactive prompt)')}
@@ -435,6 +437,8 @@ ${f('--version, -v', 'Show version')}
     ${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 --deep-summary "call 1" ${c.dim('# Pre-summarize docs, save tokens')}
+    ${c.dim('$')} taskex --deep-summary --exclude-docs "board.md,spec.md" "call 1" ${c.dim('# Keep specific docs full')}
     ${c.dim('$')} taskex --update-progress --repo ./my-project "call 1"
   `);
   // Signal early exit — pipeline checks for help flag before calling this
@@ -444,6 +448,7 @@ ${f('--version, -v', 'Show version')}
 module.exports = {
   parseArgs, showHelp, discoverFolders, selectFolder, selectModel,
   promptUser, promptUserText, selectRunMode, selectFormats, selectConfidence,
+  selectDocsToExclude,
 };
 
 // ======================== INTERACTIVE PROMPTS ========================
@@ -527,6 +532,9 @@ const RUN_PRESETS = {
   },
 };
 
+// Attach RUN_PRESETS to exports (defined after module.exports due to const ordering)
+module.exports.RUN_PRESETS = RUN_PRESETS;
+
 /**
  * Interactive run-mode selector. Shows preset options and returns the chosen
  * preset key. The caller applies overrides to opts.
@@ -721,3 +729,83 @@ async function selectConfidence() {
     });
   });
 }
+
+// ======================== DEEP SUMMARY DOC EXCLUSION PICKER ========================
+
+/**
+ * Interactive picker: let user select documents to EXCLUDE from deep summary.
+ * Excluded docs stay at full fidelity; the summary pass focuses on their topics.
+ *
+ * @param {Array<{fileName: string, type: string, content?: string}>} contextDocs - Prepared docs
+ * @returns {Promise<string[]>} Array of excluded fileName strings
+ */
+async function selectDocsToExclude(contextDocs) {
+  const readline = require('readline');
+
+  // Only show inlineText docs with actual content
+  const eligible = contextDocs
+    .filter(d => d.type === 'inlineText' && d.content && d.content.length > 0)
+    .map(d => ({
+      fileName: d.fileName,
+      chars: d.content.length,
+      tokensEst: Math.ceil(d.content.length * 0.3),
+    }));
+
+  if (eligible.length === 0) return [];
+
+  console.log('');
+  console.log(`  ${c.bold('📋 Deep Summary — Choose What to Keep in Full')}`);
+  console.log(c.dim('  ' + '─'.repeat(60)));
+  console.log('');
+  console.log(`  ${c.dim('To save processing time, we can create short summaries of your')}`);
+  console.log(`  ${c.dim('reference documents. The AI will still read them — just faster.')}`);
+  console.log('');
+  console.log(`  ${c.bold('If a document is especially important to you, select it below')}`);
+  console.log(`  ${c.bold('to keep it in full.')} The rest will be smartly condensed.`);
+  console.log('');
+
+  eligible.forEach((d, i) => {
+    const num = c.cyan(`[${i + 1}]`);
+    const size = d.tokensEst >= 1000
+      ? c.dim(`~${(d.tokensEst / 1000).toFixed(0)}K words`)
+      : c.dim(`~${d.tokensEst} words`);
+    console.log(`    ${num} ${c.bold(d.fileName)} ${size}`);
+  });
+  console.log('');
+  console.log(c.dim('  Tip: Enter = condense all · Type numbers to keep full (e.g. 1,3)'));
+  console.log('');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question('  Keep full (e.g. 1,3 or Enter = condense all): ', answer => {
+      rl.close();
+      const trimmed = (answer || '').trim();
+
+      if (!trimmed) {
+        console.log(c.success('Got it — all documents will be condensed for faster processing'));
+        resolve([]);
+        return;
+      }
+
+      const parts = trimmed.split(/[\s,]+/).filter(Boolean);
+      const excluded = [];
+
+      for (const p of parts) {
+        const num = parseInt(p, 10);
+        if (num >= 1 && num <= eligible.length) {
+          excluded.push(eligible[num - 1].fileName);
+        }
+      }
+
+      if (excluded.length === 0) {
+        console.log(c.warn('No valid selections — condensing all documents'));
+        resolve([]);
+        return;
+      }
+
+      console.log(c.success(`Keeping ${excluded.length} doc(s) in full — the rest will be condensed:`));
+      excluded.forEach(f => console.log(`    ${c.dim('•')} ${c.cyan(f)}`));
+      resolve(excluded);
+    });
+  });
+}

package/EXPLORATION.md

@@ -1,514 +0,0 @@
-# Task Summary Extractor — Where We Are & Where We Can Go
-
-> **Version 9.0.0** — March 2026  
-> Module map, codebase stats, and future roadmap.  
-> For setup and CLI reference, see [README.md](README.md) · [Quick Start](QUICK_START.md)  
-> For architecture diagrams and algorithms, see [ARCHITECTURE.md](ARCHITECTURE.md)
-
----
-
-## Part 1: Where We Are Now
-
-### Architecture Overview
-
-```text
-┌─────────────────────────────────────────────────────────────────────┐
-│          taskex (bin/taskex.js) or process_and_upload.js            │
-│                          (Entry Points)                             │
-└─────────────────────────┬───────────────────────────────────────────┘
-                          │
-┌─────────────────────────▼───────────────────────────────────────────┐
-│                       pipeline.js (~920 lines)                      │
-│              9-Phase Orchestrator + src/phases/                      │
-│                                                                     │
-│  Init ──────► Discover ──► Services ──► ProcessVideo ──► Compile    │
-│  │ learning                               │    │           │        │
-│  │ insights                         ┌─────▼────▼──┐    Diff        │
-│  │ loaded                           │ For each    │   Engine       │
-│  │                                  │ segment:    │      │         │
-│  │                                  │ ┌─────────┐ │   Output      │
-│  │                                  │ │Compress │ │   (MD+HTML)    │
-│  │                                  │ │Upload   │ │      │         │
-│  │                                  │ │Analyze ◄──┼── Quality Gate │
-│  │                                  │ │ ↻Retry  │ │   + Confidence│
-│  │                                  │ │ 🔍Focus │ │   Scoring     │
-│  │                                  │ └─────────┘ │               │
-│  │                                  └─────────────┘   Summary     │
-│  │                                                       │         │
-│  └──────────────────── learning history saved ◄──────────┘         │
-└────┬──────────┬──────────┬──────────┬──────┬─────────┬─────────────┘
-     │          │          │          │      │         │
-┌────▼───┐ ┌───▼──────┐ ┌▼────────┐ ┌▼─────┐ ┌▼─────┐┌▼─────────┐
-│Services│ │  Utils   │ │Renderers│ │Logger│ │Schema││  Config  │
-│        │ │          │ │         │ │      │ │      ││          │
-│gemini  │ │quality   │ │markdown │ │JSONL │ │seg   ││dotenv    │
-│firebase│ │-gate     │ │(801 ln) │ │struct│ │comp  ││validation│
-│video   │ │colors    │ │html.js  │ │spans │ │      ││env helper│
-│git     │ │progress  │ │(673 ln) │ │phases│ │      ││model reg │
-│doc-    │ │-bar      │ │pdf.js   │ │metric│ │      ││          │
-│parser  │ │confidence│ │docx.js  │ │      │ │      ││          │
-│        │ │-filter   │ │shared   │ │      │ │      ││          │
-│        │ │          │ │(212 ln) │ │      │ │      ││          │
-│        │ │schema-   │ │         │ │      │ │      ││          │
-│        │ │validator │ │         │ │      │ │      ││          │
-│        │ │+15 more  │ │         │ │      │ │      ││          │
-└────────┘ └──────────┘ └─────────┘ └──────┘ └──────┘└──────────┘
-```
-
-### Codebase Stats
-
-| Category | Files | Lines |
-| ---------- | ------- | ------- |
-| Pipeline orchestrator | 1 | ~920 |
-| Pipeline phases (`src/phases/`) | 9 | ~1,800 |
-| Services (Gemini, Firebase, Video, Git, Doc-Parser) | 5 | ~1,650 |
-| Modes (AI pipeline phases) | 5 | 2,054 |
-| Utilities (19 modules) | 19 | ~4,100 |
-| Renderers (markdown, html, pdf, docx, shared) | 5 | ~2,100 |
-| Config + Logger | 2 | 597 |
-| Schemas (JSON) | 2 | ~400 |
-| Entry points (taskex + legacy) | 2 | 79 |
-| Setup script | 1 | 418 |
-| Prompt (JSON) | 1 | 333 |
-| Tests (vitest) | 13 | ~3,200 |
-| **Total** | **~63 files** | **~13,000+ lines** |
-
-### Version History
-
-| Version | Theme | Key Additions |
-| --------- | ------- | --------------- |
-| **v3** | Core Improvements | dotenv, logger, retry logic, CLI args, graceful shutdown, config validation, progress persistence, error handling, video fixes, parallel uploads |
-| **v4** | Architecture & Orchestration | Phase decomposition (7 phases), CostTracker, configurable thinking budget, poll timeouts, dead code cleanup, no `process.exit()`, CLI enhancements |
-| **v5** | Smart & Accurate | Quality Gate (4-dimension scoring), auto-retry with corrective hints, adaptive thinking budget, smart boundary detection, health dashboard, enhanced prompt engineering, compilation quality assessment |
-| **v6** | Self-Improving Intelligence | Confidence scoring per item, focused re-analysis for weak areas, learning loop (historical auto-tuning), diff-aware compilation (cross-run deltas), structured JSONL logging with phase spans, confidence badges in Markdown |
-| **v6.1** | Smart Change Detection | Git-based progress tracking, AI-powered change correlation, automatic item status assessment (DONE/IN_PROGRESS/NOT_STARTED), progress markdown reports, `--update-progress` mode |
-| **v6.2** | Deep Dive | `--deep-dive` generates explanatory docs per topic, 8 content categories |
-| **v7.0** | Dynamic Mode | `--dynamic` doc-only mode, interactive folder selection, fully flexible pipeline |
-| **v7.1** | Dynamic + Video | `--dynamic` now processes videos: compress, segment, analyze — works with any content |
-| **v7.2** | Model Selection | Interactive model selector, `--model` flag, 5-model registry with pricing, runtime model switching |
-| **v7.2.1** | Storage URL + Audit | Firebase Storage URLs as Gemini External URLs (skip File API upload), 3-strategy file resolution, URI reuse for retry/focused pass, Gemini file cleanup, confidence % fix, logger/firebase/git/version fixes |
-| **v7.2.2** | Upload Control | `--force-upload` to re-upload existing files, `--no-storage-url` to force Gemini File API, production-ready docs |
-| **v7.2.3** | Production Hardening | Cross-platform ffmpeg detection, shell injection fix (spawnSync), auto git init for `--update-progress`, `runs/` excluded from doc discovery, entry point docs updated |
-| **v8.0.0** | npm Package | Global CLI (`taskex`), `--gemini-key`/`--firebase-*` config flags, CWD-based path resolution, CWD-first `.env`, `bin/taskex.js` entry point, npm publish-ready `package.json` |
-| **v8.1.0** | Smart Global Config | Persistent `~/.taskexrc` config, `taskex config` subcommand, first-run API key prompting, 5-level config resolution, production audit (14 fixes), shared CLI flag injection, boolean flag parser fix |
-| **v8.2.0** | Architecture Cleanup | `src/modes/` for AI pipeline phases, `retry.js` self-contained defaults, dead code removal, export trimming, `process_and_upload.js` slim shim, `progress.js` → `checkpoint.js`, merged `prompt.js` into `cli.js` |
-| **v8.3.0** | Universal Content Analysis | prompt.json v4.0.0 — input type auto-detection (video/audio/document/mixed), timestamps conditional, domain-adaptive extraction for any content source, gemini.js bridge text generalized |
-| **v9.0.0** | CLI UX + Pipeline Decomposition | Colors & progress bar, HTML reports (`results.html`), PDF & DOCX output (`results.pdf`, `results.docx`), JSON Schema validation (`src/schemas/`), confidence filter (`--min-confidence`), pipeline decomposed into `src/phases/` (9 modules), test suite (285 tests via vitest), multi-format output (`--format`: md/html/json/pdf/docx/all), doc-parser service, shared renderer utilities |
-
-### What v6 Delivers
-
-#### 1. Confidence Scoring Per Extracted Item
-
-Every ticket, action item, CR, blocker, and scope change now carries a `confidence` field (HIGH / MEDIUM / LOW) and a `confidence_reason` explaining the evidence basis.
-
-| Confidence | Meaning | Example |
-| ------------ | --------- | --------- |
-| **HIGH** | Explicitly stated + corroborated by docs/context | "Mentioned by name with ticket ID in VTT and Azure DevOps" |
-| **MEDIUM** | Partially stated or single-source | "Discussed verbally but no written reference" |
-| **LOW** | Inferred from context, not directly stated | "Implied from related discussion, not explicitly assigned" |
-
-**Where it shows up:**
-
-- **Quality Gate** (`quality-gate.js` — 366 lines): New 15-point confidence coverage dimension in density scoring. Flags missing confidence fields and suspicious uniformity (all HIGH = likely not calibrated). Generates retry hints for poor confidence.
-- **Markdown Renderer** (`markdown.js` — 879 lines): Confidence badges (🟢 🟡 🔴) on every ticket header, action item row, CR row, blocker, scope change, and todo item. "📊 Confidence Distribution" summary table near report header.
-- **Prompt** (`prompt.json` — 333 lines): Explicit confidence scoring instructions injected into extraction prompt. Self-verification checklist updated.
-
-#### 2. Focused Re-Analysis (`focused-reanalysis.js` — 268 lines)
-
-When the quality gate identifies specific weak dimensions (score <60, ≥2 weak areas), a **targeted second pass** runs instead of a full re-analysis.
-
-| Component | What It Does |
-| ----------- | -------------- |
-| `identifyWeaknesses()` | Analyzes quality dimensions + confidence coverage to find gaps (missing tickets, sparse assignees, low confidence items, broken cross-refs) |
-| `runFocusedPass()` | Sends a focused Gemini prompt targeting ONLY the weak areas, with reduced thinking budget (12K tokens) |
-| `mergeFocusedResults()` | Intelligent merge: updates existing items by ID, appends new items, marks `_enhanced_by_focused_pass` / `_from_focused_pass` |
-
-**Pipeline integration**: Runs after the quality gate + retry cycle for each segment. Controlled by `--no-focused-pass` flag. Costs tracked separately in cost tracker.
-
-#### 3. Learning & Improvement Loop (`learning-loop.js` — 269 lines)
-
-The pipeline remembers its past performance and auto-tunes for the future.
-
-**How it works:**
-
-1. **Before processing**: `loadHistory()` reads `history.json` (up to 50 past runs), `analyzeHistory()` computes trends and budget adjustments
-2. **Budget auto-tuning**: If avg quality <45 across recent runs → boost thinking budget +4096 tokens. If >80 → reduce by 2048 to save cost.
-3. **Retry effectiveness**: Tracks whether retries actually improve quality. If retry success rate <30%, recommends increasing base budget instead.
-4. **After processing**: `saveHistory()` persists compact metrics (quality scores, extraction counts, costs, budgets, retry stats) for the next run.
-
-```text
-  📈 Learning Insights:
-    Historical runs : 12
-    Quality trend   : improving (avg: 74/100)
-    Budget adjust   : -2048 tokens (analysis)
-    Recommendations :
-      • High average quality (74/100) — reducing thinking budget by 2048 tokens to save cost
-      • Focused re-analysis was used in 3/10 runs — system is self-correcting effectively
-```
-
-#### 4. Diff-Aware Compilation (`diff-engine.js` — 277 lines)
-
-Compares the current run's compiled analysis against the previous run to produce a delta report.
-
-| Diff Category | What's Detected |
-| --------------- | ----------------- |
-| **New items** | Tickets, CRs, action items, blockers, scope changes that didn't exist before |
-| **Removed items** | Items from the previous run that no longer appear |
-| **Changed items** | Status, priority, assignee, or confidence changes on existing items |
-| **Unchanged** | Items that remain identical |
-
-**Output**: Appended to `results.md` as a "🔄 Changes Since Previous Run" section with summary table + detailed new/removed/changed listings. Also saved as `diff.json` in the run folder.
-
-#### 5. Structured Logging & Observability (`logger.js` — 306 lines)
-
-The logger now writes **three parallel outputs**:
-
-| Output | Format | Purpose |
-| -------- | -------- | --------- |
-| `*_detailed.log` | Human-readable | Full debug/info/warn/error messages |
-| `*_minimal.log` | Compact steps | Steps + timestamps only |
-| `*_structured.jsonl` | Machine-readable JSONL | Every event as a JSON object with level, timestamp, context, phase |
-
-**New capabilities:**
-
-- **Phase spans**: `phaseStart(name)` / `phaseEnd(meta)` track timing per pipeline phase with structured records
-- **Operation context**: `setContext()` / `clearContext()` stack for enriching log entries with segment/operation metadata
-- **Structured metrics**: `metric(name, value)` for recording quantitative data (confidence coverage, token counts, etc.)
-- All phase timers auto-emit structured span events
-
-#### 6. Enhanced Quality Gate (`quality-gate.js` — 366 lines)
-
-**New in v6:** Confidence coverage is now a scoring dimension within density (15 points):
-
-- Checks percentage of items with valid confidence fields
-- Detects suspicious uniformity (all same confidence = likely not calibrated)
-- New `getConfidenceStats(analysis)` export returns `{total, high, medium, low, missing, coverage}`
-- Two new retry hint generators for missing/uniform confidence
-
-### All v5 Features Retained
-
-| Feature | Module | Description |
-| --------- | -------- | ------------- |
-| Quality Gate | `quality-gate.js` | 4-dimension scoring (structure, density, integrity, cross-refs), auto-retry on FAIL |
-| Adaptive Thinking Budget | `adaptive-budget.js` | Segment position, complexity, context docs → dynamic 8K–32K range |
-| Smart Boundary Detection | `context-manager.js` | Mid-conversation detection, open ticket carry-forward, continuity hints |
-| Health Dashboard | `health-dashboard.js` | Quality scores, extraction density bars, retry stats, efficiency metrics |
-| Enhanced Prompt | `prompt.json` | Universal content analysis (v4.0.0): input type detection, timestamps conditional on content type, domain-adaptive extraction, self-verification checklist |
-
-### Current Capabilities
-
-| Capability | Status | Description |
-| ------------ | -------- | ------------- |
-| Video compression | ✅ Mature | ffmpeg-based, CRF, configurable speed/preset |
-| Video segmentation | ✅ Mature | Time-based splitting, segment pre-validation |
-| Firebase upload | ✅ Mature | Parallel, retry, skip-existing, anonymous auth, async I/O, `--force-upload` re-upload |
-| Storage URL optimization | ✅ v7.2.1 New | Firebase download URLs used as Gemini External URLs — skips File API upload, `--no-storage-url` to disable |
-| Gemini segment analysis | ✅ Premium | 1M context, VTT slicing, progressive context, adaptive budget, 3-strategy file resolution |
-| Gemini file cleanup | ✅ v7.2.1 New | Auto-delete File API uploads after all passes complete |
-| Quality gate + retry | ✅ Enhanced | 4-dimension scoring + confidence coverage dimension, auto-retry with hints |
-| Confidence scoring | ✅ v6 New | HIGH/MEDIUM/LOW per item with evidence reasoning |
-| Focused re-analysis | ✅ v6 New | Targeted second pass for weak quality dimensions |
-| Learning loop | ✅ v6 New | Historical auto-tuning of budgets/thresholds across runs |
-| Diff engine | ✅ v6 New | Cross-run delta reports (new/removed/changed items) |
-| Structured logging | ✅ v6 New | JSONL structured log, phase spans, operation contexts, metrics |
-| Cross-segment continuity | ✅ Premium | Progressive context compression, boundary detection, focus instructions |
-| AI compilation | ✅ Premium | Dedup, name normalization, adaptive compilation budget |
-| Markdown rendering | ✅ Enhanced | Name clustering, ID dedup, confidence badges, diff section |
-| Cost tracking | ✅ Mature | Per-segment + compilation + focused passes, long-context tier pricing |
-| Progress persistence | ✅ Mature | Checkpoint/resume after crashes |
-| CLI | ✅ Complete | 18 flags, help, version, output dir |
-| Logging | ✅ v6 Rewritten | Triple output: detailed + minimal + structured JSONL |
-| Health dashboard | ✅ Mature | Quality, density, retries, efficiency |
-
-### CLI Reference
-
-```text
-Usage: taskex [options] [folder]
-
-Install: npm i -g task-summary-extractor
-
-If no folder is specified, shows an interactive folder selector.
-
-Configuration (override .env):
-  --gemini-key <key>                Gemini API key
-  --firebase-key <key>              Firebase API key
-  --firebase-project <id>           Firebase project ID
-  --firebase-bucket <bucket>        Firebase storage bucket
-  --firebase-domain <domain>        Firebase auth domain
-
-Modes:
-  (default)                         Video analysis — compress, analyze, extract, compile
-  --dynamic                         Document-only mode — no video required
-  --update-progress                 Track item completion via git
-  --deep-dive                       Generate explanatory docs per topic discussed
-
-Core Options:
-  --name <name>                     Your name (skips interactive prompt)
-  --model <id>                      Gemini model to use (skips interactive selector)
-  --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
-  --reanalyze                       Force re-analysis of all segments
-  --dry-run                         Show what would be done without executing
-
-Dynamic Mode:
-  --dynamic                         Enable document-only mode
-  --request <text>                  What to generate (prompted if omitted)
-
-Progress Tracking:
-  --repo <path>                     Path to the project git repo
-
-Tuning:
-  --parallel <n>                    Max parallel uploads (default: 3)
-  --parallel-analysis <n>           Concurrent segment analysis batches (default: 2)
-  --thinking-budget <n>             Thinking tokens per segment (default: 24576)
-  --compilation-thinking-budget <n> Thinking tokens for compilation (default: 10240)
-  --log-level <level>               debug | info | warn | error (default: info)
-  --output <dir>                    Custom output directory for results
-  --no-focused-pass                 Disable focused re-analysis
-  --no-learning                     Disable learning loop
-  --no-diff                         Disable diff comparison
-
-Output:
-  --format <type>                   Output format: md, html, json, pdf, docx, all (default: md)
-  --min-confidence <level>          Filter by confidence: high, medium, low
-  --no-html                         Suppress HTML report generation
-
-Info:
-  --help, -h                        Show help
-  --version, -v                     Show version
-```
-
-### Full Module Map
-
-```text
-bin/
-└── taskex.js                 65 ln  ★ v8.0.0 — Global CLI entry point, config flag injection
-
-src/
-├── config.js                291 ln  Central config, env vars, model registry, validation
-├── logger.js                306 ln  ★ v6 — Triple output: detailed + minimal + structured JSONL, phase spans, metrics
-├── pipeline.js            ~920 ln  Multi-mode orchestrator with lazy phase imports, Storage URL optimization, upload control flags, learning loop, diff engine
-├── phases/                         ★ v9.0.0 — Decomposed pipeline phase modules
-│   ├── _shared.js                  Shared phase utilities (logging, error helpers)
-│   ├── init.js                     Phase 1: CLI parsing, config validation, logger setup
-│   ├── discover.js                 Phase 2: Find videos/audio, discover docs, resolve name
-│   ├── services.js                 Phase 3: Firebase auth, Gemini init, doc prep
-│   ├── process-media.js            Phase 4: Compress, upload, analyze, quality gate
-│   ├── compile.js                  Phase 5: Cross-segment compilation, diff engine
-│   ├── output.js                   Phase 6: Write JSON, render MD + HTML
-│   ├── summary.js                  Phase 8: Save learning history, print summary
-│   └── deep-dive.js                Phase 9: Optional deep-dive generation
-├── modes/                          ★ v8.2.0 — AI-heavy pipeline phase modules
-│   ├── change-detector.js   417 ln  Git-based change correlation engine
-│   ├── deep-dive.js         473 ln  ★ v6.2 — Topic discovery, parallel doc generation, index builder
-│   ├── dynamic-mode.js      494 ln  ★ v7.0 — Context-only doc generation, topic planning, parallel writing
-│   ├── focused-reanalysis.js 268 ln ★ v6 — Weakness detection, targeted second pass, intelligent merge
-│   └── progress-updater.js  402 ln  ★ v6.1 — AI-powered progress assessment, status report generation
-├── renderers/
-│   ├── markdown.js          801 ln  ★ v6 — Confidence badges (🟢🟡🔴), confidence distribution table, diff section
-│   ├── html.js              673 ln  ★ v9.0.0 — Self-contained HTML report: collapsible sections, confidence badges, filtering, dark mode
-│   ├── pdf.js                       ★ v9.0.0 — PDF report renderer: HTML → PDF conversion via puppeteer
-│   ├── docx.js                      ★ v9.0.0 — DOCX report renderer: programmatic Word document via docx npm package
-│   └── shared.js            212 ln  ★ v9.0.0 — Shared renderer utilities (name clustering, dedup, formatting)
-├── services/
-│   ├── firebase.js           92 ln  Init, upload, exists check (with retry, async I/O)
-│   ├── gemini.js            677 ln  ★ v7.2.1 — 3-strategy file resolution, External URL support, cleanup, doc prep, analysis, compilation
-│   ├── git.js               264 ln  ★ v7.2.3 — Git CLI wrapper: log, diff, status, changed files, auto-init
-│   ├── video.js             273 ln  ★ v7.2.3 — ffmpeg compress, segment, probe (cross-platform, spawnSync)
-│   └── doc-parser.js        346 ln  ★ v9.0.0 — Document text extraction (DOCX, XLSX, PPTX, HTML, ODT, RTF, EPUB)
-└── utils/                          Pure utilities — parsing, retry, budget, config
-    ├── adaptive-budget.js   230 ln  ★ v5 — Transcript complexity → dynamic budget
-    ├── checkpoint.js        145 ln  Checkpoint/resume persistence (renamed from progress.js in v8.2.0)
-    ├── cli.js               391 ln  ★ v8.0.0 — Interactive prompts, model selector, folder picker, config flags, taskex help
-    ├── context-manager.js   420 ln  4-tier priority, VTT slicing, progressive context, boundary detection
-    ├── cost-tracker.js      140 ln  Token counting, USD cost estimation (+ focused pass tracking)
-    ├── diff-engine.js       277 ln  ★ v6 — Cross-run delta: new/removed/changed items, Markdown rendering
-    ├── format.js             27 ln  Duration, bytes formatting
-    ├── fs.js                 34 ln  Recursive doc finder (skips runs/)
-    ├── global-config.js     274 ln  ★ v8.1.0 — ~/.taskexrc persistent config, interactive setup
-    ├── health-dashboard.js  191 ln  ★ v5 — Quality report, density bars, efficiency metrics
-    ├── inject-cli-flags.js   49 ln  ★ v8.1.0 — CLI flag → env var injection
-    ├── json-parser.js       216 ln  5-strategy JSON extraction + repair
-    ├── learning-loop.js     269 ln  ★ v6 — History I/O, trend analysis, budget auto-tuning, recommendations
-    ├── quality-gate.js      366 ln  ★ v6 — 4+1 dimension scoring (+ confidence coverage), retry hints
-    ├── retry.js             118 ln  Exponential backoff, parallel map (self-contained defaults)
-    ├── colors.js             84 ln  ★ v9.0.0 — Zero-dep ANSI color utility (bold, red, green, yellow, cyan, dim, reset)
-    ├── progress-bar.js      287 ln  ★ v9.0.0 — Visual progress bar with phase tracking, ETA, cost display, TTY-aware
-    ├── confidence-filter.js 130 ln  ★ v9.0.0 — Filter extracted items by confidence level (--min-confidence flag)
-    └── schema-validator.js  260 ln  ★ v9.0.0 — JSON Schema validation using ajv (segment + compiled schemas)
-
-schemas/
-├── analysis-segment.schema.json    ★ v9.0.0 — JSON Schema for segment analysis output
-└── analysis-compiled.schema.json   ★ v9.0.0 — JSON Schema for compiled analysis output
-
-prompt.json                  333 ln  ★ v4.0.0 — Universal content analysis: video, audio, documents, mixed input; auto-detects input type + domain
-process_and_upload.js         14 ln  Backward-compatible shim — delegates to bin/taskex.js
-setup.js                     418 ln  Automated first-time setup & environment validation (v8.0.0)
-```
-
----
-
-## Part 2: Where We Can Go
-
-### Already Implemented (v6)
-
-The following features from the original exploration have been **fully implemented**:
-
-| Feature | Status | Implemented In |
-| --------- | -------- | ---------------- |
-| 📊 Confidence Scoring Per Extracted Item | ✅ Done | `prompt.json`, `quality-gate.js`, `markdown.js` |
-| 🔄 Multi-Pass Analysis (Focused Re-extraction) | ✅ Done | `modes/focused-reanalysis.js` (268 ln), pipeline integration |
-| 🧠 Learning & Improvement Loop | ✅ Done | `learning-loop.js` (270 ln), pipeline init + save |
-| 📝 Diff-Aware Compilation | ✅ Done | `diff-engine.js` (280 ln), pipeline output + MD |
-| 🔍 Structured Logging & Observability | ✅ Done | `logger.js` rewritten (303 ln), JSONL + spans + metrics |
-| Parallel segment analysis (via CLI) | ✅ Done | `--parallel-analysis` flag, pipeline batching |
-| 🔎 Smart Change Detection & Progress Tracking | ✅ Done | `git.js` (310 ln), `modes/change-detector.js` (417 ln), `modes/progress-updater.js` (402 ln), pipeline `--update-progress` mode |
-| 🗓️ Deep Dive Document Generation | ✅ Done | `modes/deep-dive.js` (473 ln), pipeline phase 9 |
-| 📝 Dynamic Mode (doc-only generation) | ✅ Done | `modes/dynamic-mode.js` (494 ln), pipeline `--dynamic` route |
-| 🤖 Runtime Model Selection | ✅ Done | `config.js` model registry, `cli.js` selector, `--model` flag |
-| 📊 Progress Bar | ✅ Done | `progress-bar.js` (287 ln), pipeline integration, TTY-aware |
-| 🌐 HTML Report Viewer | ✅ Done | `renderers/html.js` (673 ln), self-contained HTML with filtering, dark mode |
-| 🔧 JSON Schema Validation | ✅ Done | `schema-validator.js` (260 ln), `schemas/` (2 files), ajv-based |
-| 🎯 Confidence Filter | ✅ Done | `confidence-filter.js` (130 ln), `--min-confidence` flag |
-| 🏗️ Pipeline Decomposition | ✅ Done | `src/phases/` (9 modules), `pipeline.js` reduced to ~920 lines |
-| 🧪 Test Suite | ✅ Done | 285 tests across 13 files using vitest |
-| 🎨 ANSI Colors | ✅ Done | `colors.js` (84 ln), zero-dep ANSI color utility wired throughout CLI |
-| 📄 Doc Parser Service | ✅ Done | `doc-parser.js` (346 ln), DOCX/XLSX/PPTX/HTML/ODT/RTF/EPUB extraction |
-
----
-
-### Tier 1: High-Impact, Medium Effort
-
-#### 🔊 Speaker Diarization & Attribution
-
-**What**: Automatically identify who is speaking at each moment in the video.  
-**How**: Use Gemini's audio understanding or integrate a dedicated diarization API (e.g., AssemblyAI, Deepgram) as a preprocessing step. Map speaker segments to VTT timestamps.  
-**Impact**: Dramatically improves action item attribution ("Mohamed said X" vs. "someone said X"). Currently relies on Gemini inferring speakers from VTT voice tags or contextual clues.  
-**Modules affected**: New `services/diarization.js`, updates to `gemini.js` content building, `context-manager.js` for speaker-aware slicing.
-
-#### 🌐 ~~Web Dashboard / Viewer~~ ✅ Done (v9.0.0)
-
-**Status**: Implemented as `src/renderers/html.js` — self-contained HTML report with collapsible sections, confidence badges, filtering, dark mode, and print-friendly styling. Generated as `results.html` alongside `results.md`.
-**Next step**: Build a hosted React/Next.js viewer that reads from Firebase for team-wide access.
-
----
-
-### Tier 2: Differentiation Features
-
-#### 🎯 Task Board Integration (Azure DevOps / Jira / Linear)
-
-**What**: Push extracted action items and tickets directly to your project management tool.  
-**How**: After compilation, map extracted items to work item templates. Use Azure DevOps REST API / Jira API / Linear API to create/update items. Cross-reference extracted CR numbers with existing work items.  
-**Impact**: Closes the loop — call discussions automatically become tracked work items. No manual "meeting notes → task creation" step.  
-**Modules affected**: New `services/task-board.js`, integration config in `config.js`, new CLI flags (`--push-to-jira`, `--sync-devops`).
-
-#### 🎙️ Real-Time / Live Analysis Mode
-
-**What**: Analyze calls as they happen, producing running analysis instead of post-call batch processing.  
-**How**: Stream audio/video chunks to Gemini in real-time using Live API. Maintain a rolling context window. Produce incremental analysis updates.  
-**Impact**: During the call, participants see extracted items appearing in real-time. Post-call report is instant.  
-**Modules affected**: New `services/live-stream.js`, new `pipeline-live.js`, WebSocket output to a dashboard.
-
----
-
-### Tier 3: Platform Evolution
-
-#### 🏗️ Plugin Architecture
-
-**What**: Allow custom plugins for different output formats, analysis types, and integrations.  
-**How**: Define hook points: `onSegmentAnalyzed`, `onCompiled`, `onOutput`. Plugins register handlers. Ship with built-in plugins (markdown, json, firebase). Community can add: Slack notifications, email summaries, PDF reports, custom prompts per team.  
-**Impact**: Transforms from a single-purpose tool to a platform. Different teams customize for their workflow.
-
-#### 🤖 Multi-Model Support
-
-**What**: Support different AI models beyond Gemini — OpenAI GPT-4o, Claude, Llama local models.  
-**Status**: *Partially implemented in v7.2* — runtime model selection across 5 Gemini models with `--model` flag and interactive selector. Full multi-provider abstraction (OpenAI, Claude, local) remains a future enhancement.  
-**Next step**: Abstract the AI service behind a provider interface. Each provider implements: `upload()`, `analyze()`, `compile()`. Config selects the active provider.  
-**Impact**: Users choose the best model for their budget/accuracy needs. Can run local models for sensitive content. Enables A/B testing between models.
-
-#### 📱 Mobile App / Bot
-
-**What**: Telegram/Teams/Slack bot that accepts video links and returns analysis.  
-**How**: Bot receives a shared video/meeting link → triggers pipeline → sends back the compiled Markdown or a link to the web dashboard.  
-**Impact**: Zero-friction usage — share a link, get a task summary. No CLI needed.
-
-#### 🔐 Multi-Tenant SaaS
-
-**What**: Hosted version where teams sign up, configure their projects, and get analysis as a service.  
-**How**: Next.js frontend, Node.js API (reusing current pipeline), per-team Firebase/S3 storage, Stripe billing, queue-based processing.  
-**Impact**: Commercial product. Teams pay per call analyzed. Revenue model.
-
----
-
-### Tier 4: Polish & Reliability
-
-#### 🧪 ~~Test Suite~~ ✅ Done (v9.0.0)
-
-**Status**: 285 tests across 13 files using vitest. Covers: quality-gate, adaptive-budget, json-parser, confidence-filter, context-manager, diff-engine, format, progress-bar, retry, schema-validator, cli, and renderers (html, markdown).
-**Commands**: `npm test`, `npm run test:watch`, `npm run test:coverage`.
-
-#### 📦 ~~Packaging & Distribution~~ ✅ Done (v8.0.0)
-
-**Status**: Published as `task-summary-extractor` on npm. Global CLI: `taskex`. Install: `npm i -g task-summary-extractor`.  
-**What was done**: `bin/taskex.js` entry point, `--gemini-key`/`--firebase-*` CLI config flags, CWD-based `.env` resolution, `PKG_ROOT`/`PROJECT_ROOT` path split for global compatibility.
-
-#### 🔍 Advanced Observability (OpenTelemetry)
-
-**What**: Extend the existing structured JSONL logging with OpenTelemetry trace export for external monitoring.  
-**How**: Wrap existing `phaseStart`/`phaseEnd` spans with OTel SDK. Export traces to Jaeger/Grafana. Add alert rules on quality metric degradation.  
-**Impact**: Production monitoring. Performance profiling across runs. Alert on quality regression trends.  
-**Note**: Basic structured logging is already done in v6. This extends it to distributed tracing systems.
-
-#### 🌍 i18n Prompt Library
-
-**What**: Support different language pairs beyond Arabic+English. Ship prompt templates per domain.  
-**How**: Move prompt.json to a `prompts/` directory with variants: `arabic-english-dotnet.json`, `spanish-english-react.json`, `french-english-java.json`. CLI flag: `--prompt-template react-english`.  
-**Impact**: Anyone can use this tool regardless of their team's language or tech stack.
-
----
-
-### Quick Wins (< 1 day each)
-
-| Feature | Effort | Impact |
-| --------- | -------- | -------- |
-| **Email summary** — send compiled MD via SMTP after processing | ~2 hrs | Users get results in inbox |
-| **Slack webhook** — post summary to a channel | ~1 hr | Team-wide visibility |
-| **Segment preview** — show first 3 VTT lines per segment before analyzing | ~30 min | Better UX during processing |
-| **Custom output templates** — Handlebars/Mustache for MD output | ~4 hrs | Teams customize report format |
-| **~~Audio-only mode~~** | ~~Done~~ | prompt.json v4.0.0 supports audio/doc/mixed — pipeline video requirement is next |
-| **Watch mode** — monitor a folder and auto-process new recordings | ~3 hrs | Hands-free automation |
-| **Git integration** — auto-commit results to repo | ~1 hr | Version-controlled meeting history |
-| **Confidence threshold filter** | ~~Done~~ | ★ v9.0.0 `--min-confidence` flag implemented in `confidence-filter.js` |
-| **History viewer** — CLI command to print learning loop trends without running pipeline | ~2 hrs | Introspect past performance |
-
----
-
-### Recommended Next Sprint
-
-Based on impact vs. effort, here's a suggested 5-item sprint building on v7.2:
-
-1. **~~Test suite foundation~~** — ✅ Done (v9.0.0) — 285 tests across 13 files using vitest
-2. **~~Web dashboard / viewer~~** — ✅ Done (v9.0.0) — Self-contained HTML report with filtering and collapsible sections
-3. **Speaker diarization** — Gemini audio understanding for speaker attribution (1.5 days)
-4. **Task board integration** — Push tickets/CRs to Azure DevOps or Jira (1.5 days)
-5. **Slack/email notification** — Post compiled results automatically (half day)
-
-These five deliver: reliability (tests), accessibility (dashboard), accuracy (speakers), workflow integration (task board), and team visibility (notifications).
-
----
-
-*Generated from the v9.0.0 codebase — ~63 files, ~13,000+ lines of self-improving pipeline intelligence. npm: `task-summary-extractor` · CLI: `taskex`*
-
----
-
-## See Also
-
-| Doc | What's In It |
-| ----- | ------------- |
-| 📖 [README.md](README.md) | Setup, CLI flags, configuration, features |
-| 📖 [QUICK_START.md](QUICK_START.md) | Step-by-step first-time walkthrough |
-| 🏗️ [ARCHITECTURE.md](ARCHITECTURE.md) | Pipeline phases, processing flows, Mermaid diagrams |