task-summary-extractor 9.6.0 → 9.8.0

package/ARCHITECTURE.md

@@ -15,6 +15,7 @@
   - [Per-Segment Processing](#per-segment-processing)
     - [File Resolution Strategies](#file-resolution-strategies)
     - [Quality Gate Decision Table](#quality-gate-decision-table)
+  - [Multi-Segment Batching](#multi-segment-batching)
   - [Smart Change Detection](#smart-change-detection)
     - [Correlation Strategies](#correlation-strategies)
     - [Assessment Thresholds](#assessment-thresholds)
@@ -249,6 +250,56 @@ After all passes complete, any Gemini File API uploads are cleaned up (fire-and-
 
 ---
 
+## Multi-Segment Batching
+
+When the Gemini context window has enough headroom, consecutive video segments are grouped into single API calls. This reduces the number of Gemini calls and gives the model better cross-segment awareness.
+
+```mermaid
+flowchart TB
+    START(["All Segments"]) --> CHECK{"Batching enabled?\n!noBatch && !skipGemini\n&& segments > 1"}
+    CHECK -->|No| SINGLE["Single-segment\nprocessing (original)"]
+    CHECK -->|Yes| PLAN["planSegmentBatches()\nGreedy bin-packing"]
+
+    PLAN --> BUDGET["Calculate token budget:\ncontextWindow (1M)\n− promptOverhead (120K)\n− docTokens\n− prevAnalysesTokens\n= available for video"]
+
+    BUDGET --> FIT{"batchSize > 1?"}
+    FIT -->|No| SINGLE
+    FIT -->|Yes| BATCH["Process in batches"]
+
+    BATCH --> B1["Batch 1:\nsegs 1–N"]
+    BATCH --> B2["Batch 2:\nsegs N+1–M"]
+    BATCH --> BN["..."]
+
+    B1 --> CALL["processSegmentBatch()\nMultiple fileData parts\nper Gemini call"]
+    CALL --> PARSE["Parse + Quality Gate\n+ Schema Validation"]
+    PARSE --> TAG["Tag items with\nsource_segment"]
+
+    CALL -->|Error| FALLBACK["Fall back to\nsingle-segment mode"]
+    FALLBACK --> SINGLE
+```
+
+### How It Works
+
+| Step | Detail |
+| ------ | -------- |
+| **Token budget** | `contextWindow − 120K overhead − docTokens − prevAnalysesTokens = available` |
+| **Video cost** | ~300 tokens/sec × segment duration |
+| **Bin-packing** | Greedy: add consecutive segments until budget or max batch size (8) reached |
+| **Deep summary synergy** | Deep summary frees 60–80% of doc tokens → more room for video → larger batches |
+| **Fallback** | Any batch failure → entire remaining file falls back to single-segment processing |
+| **Cache aware** | Cached segment runs are loaded from disk; only uncached batches hit the API |
+| **Disable** | `--no-batch` forces original single-segment behavior |
+
+### Token Math Example
+
+| Scenario | Doc Tokens | Available | Seg Duration | Tokens/Seg | Batch Size |
+| ---------- | ----------- | ----------- | ------------- | ----------- | ----------- |
+| No deep summary | 300K | ~580K | 280s | 84K | 6 |
+| With deep summary | 60K | ~820K | 280s | 84K | 9 |
+| Raw mode | 60K | ~820K | 1200s | 360K | 2 |
+
+---
+
 ## Smart Change Detection
 
 The `--update-progress` mode tracks which extracted items have been addressed:

package/QUICK_START.md

@@ -236,6 +236,17 @@ my-project/runs/{timestamp}/
 
 ---
 
+## Advanced Features
+
+| Feature | Flag | Description |
+| --------- | ------ | ------------- |
+| **Deep Summary** | `--deep-summary` | Pre-summarizes context docs — saves 60-80% input tokens per segment |
+| **Deep Dive** | `--deep-dive` | Generates explanatory docs for each discussion topic |
+| **Multi-Segment Batching** | enabled by default | When context window has headroom, groups consecutive segments into single API calls — fewer requests, better cross-segment awareness. Use `--no-batch` to disable |
+| **Raw Video Mode** | `--no-compress` | Skip re-encoding — pass video directly to Gemini |
+
+---
+
 ## Troubleshooting
 
 | Problem | Fix |

package/README.md

@@ -1,13 +1,13 @@
 # Task Summary Extractor
 
-> **v9.4.0** — AI-powered content analysis CLI — meetings, recordings, documents, or any mix. Install globally, run anywhere.
+> **v9.8.0** — AI-powered content analysis CLI — meetings, recordings, documents, or any mix. Install globally, run anywhere.
 
 <p align="center">
   <img src="https://img.shields.io/badge/node-%3E%3D18.0.0-green" alt="Node.js" />
   <img src="https://img.shields.io/badge/gemini-2.5--flash-blue" alt="Gemini" />
-  <img src="https://img.shields.io/badge/firebase-11.x-orange" alt="Firebase" />
-  <img src="https://img.shields.io/badge/version-9.4.0-brightgreen" alt="Version" />
-  <img src="https://img.shields.io/badge/tests-331%20passing-brightgreen" alt="Tests" />
+  <img src="https://img.shields.io/badge/firebase-12.x-orange" alt="Firebase" />
+  <img src="https://img.shields.io/badge/version-9.7.0-brightgreen" alt="Version" />
+  <img src="https://img.shields.io/badge/tests-345%20passing-brightgreen" alt="Tests" />
   <img src="https://img.shields.io/badge/npm-task--summary--extractor-red" alt="npm" />
 </p>
 
@@ -183,7 +183,7 @@ These are the ones you'll actually use:
 | `--resume` | Continue an interrupted run | `--resume` |
 | `--reanalyze` | Force fresh analysis (ignore cache) | `--reanalyze` |
 | `--dry-run` | Preview what would run, without running | `--dry-run` |
-| `--format <type>` | Output format: `md`, `html`, `json`, `pdf`, `docx`, `all` (default: `md`) | `--format html` |
+| `--format <type>` | Output format: `md`, `html`, `json`, `pdf`, `docx`, `all` (default: `all`) | `--format html` |
 | `--min-confidence <level>` | Filter items by confidence: `high`, `medium`, `low` | `--min-confidence high` |
 | `--no-html` | Suppress HTML report generation | `--no-html` |
 | `--deep-summary` | Pre-summarize context docs (60-80% token savings) | `--deep-summary` |
@@ -273,6 +273,7 @@ Control how video is processed before AI analysis:
 | `--no-focused-pass` | enabled | Disable targeted re-analysis of weak segments |
 | `--no-learning` | enabled | Disable auto-tuning from historical run data |
 | `--no-diff` | enabled | Disable diff comparison with the previous run |
+| `--no-batch` | enabled | Disable multi-segment batching (force 1 segment per API call) |
 
 ### Available Models
 
@@ -304,7 +305,7 @@ DYNAMIC    --request <text>
 PROGRESS   --repo <path>
 TUNING     --thinking-budget  --compilation-thinking-budget  --parallel
            --parallel-analysis  --log-level  --output
-           --no-focused-pass  --no-learning  --no-diff
+           --no-focused-pass  --no-learning  --no-diff  --no-batch
 INFO       --help (-h)  --version (-v)
 ```
 
@@ -472,6 +473,7 @@ GEMINI_API_KEY=your-key-here
 | **Deep Summary** | `--deep-summary` pre-summarizes context docs, 60-80% token savings per segment |
 | **Context Window Safety** | Auto-truncation, pre-flight token checks, RESOURCE_EXHAUSTED recovery |
 | **Multi-Format Output** | `--format` flag: Markdown, HTML, JSON, PDF, DOCX, or all formats at once |
+| **Multi-Segment Batching** | Groups consecutive segments into single API calls when context window has headroom — fewer calls, better cross-segment awareness. `--no-batch` to disable |
 | **Interactive CLI** | Run with no args → guided experience |
 | **Resume / Checkpoint** | `--resume` continues interrupted runs |
 | **Firebase Upload** | Team access via cloud (optional) |
@@ -586,7 +588,7 @@ task-summary-extractor/
 | `npm run check` | Validate environment |
 | `npm start` | Run the pipeline |
 | `npm run help` | Show CLI help |
-| `npm test` | Run test suite (331 tests) |
+| `npm test` | Run test suite (345 tests) |
 | `npm run test:watch` | Run tests in watch mode |
 | `npm run test:coverage` | Run tests with coverage report |
 
@@ -596,6 +598,8 @@ task-summary-extractor/
 
 | Version | Highlights |
 |---------|-----------|
+| **v9.8.0** | **Schema hardening & transcript handling** — VTT/SRT auto-excluded from deep-summary (transcripts routed to workflow, not summarizer), `normalizeAnalysis()` fills missing `summary`/`confidence`/`discussed_state` defaults before validation, batch Storage URL→File API auto-retry on `INVALID_ARGUMENT`, focused re-analysis skips sparse segments (≤2 items + low density), 367 tests |
+| **v9.7.0** | **Multi-segment batching** — groups consecutive video segments into single Gemini API calls when context window has headroom, greedy bin-packing by token budget (`planSegmentBatches`), `processSegmentBatch()` multi-video API calls, automatic fallback to single-segment on failure, `--no-batch` to disable, codebase audit fixes (unused imports, variable shadowing) |
 | **v9.6.0** | **Interactive CLI UX** — arrow-key navigation for all selectors (folder, model, run mode, formats, confidence, doc exclusion), zero-dependency prompt engine (`interactive.js`), `selectOne()` with ↑↓+Enter, `selectMany()` with Space toggle + A all/none, non-TTY fallback to number input |
 | **v9.5.0** | **Video processing flags** — `--no-compress`, `--speed`, `--segment-time` CLI flags, hardcoded 1200s for raw mode, deprecated `--skip-compression` |
 | **v9.4.0** | **Context window safety** — pre-flight token checks, auto-truncation for oversized docs/VTTs, RESOURCE_EXHAUSTED recovery with automatic doc shedding, chunked compilation for large segment sets, P0/P1 hard cap (2× budget) prevents context overflow, improved deep-summary prompt quality |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-summary-extractor",
-  "version": "9.6.0",
+  "version": "9.8.0",
   "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": {

package/src/modes/deep-summary.js

@@ -27,6 +27,20 @@ const config = require('../config');
 
 // ======================== CONSTANTS ========================
 
+/**
+ * Transcript file extensions that should NEVER be summarized.
+ * VTT/SRT files are time-sliced per segment during analysis — summarising
+ * them would destroy the timestamp-indexed structure that `sliceVttForSegment`
+ * relies on. They are automatically kept at full fidelity.
+ */
+const TRANSCRIPT_EXTENSIONS = ['.vtt', '.srt'];
+
+/** Check whether a filename is a transcript file (VTT/SRT). */
+function isTranscriptFile(fileName) {
+  const lower = (fileName || '').toLowerCase();
+  return TRANSCRIPT_EXTENSIONS.some(ext => lower.endsWith(ext));
+}
+
 /** Max tokens for a single summarization call output */
 const SUMMARY_MAX_OUTPUT = 16384;
 
@@ -262,6 +276,13 @@ async function deepSummarize(ai, contextDocs, opts = {}) {
       continue;
     }
 
+    // Auto-exclude transcript files (VTT/SRT) — they are time-sliced per
+    // segment during analysis and must retain their timestamp structure.
+    if (isTranscriptFile(doc.fileName)) {
+      keepFull.push(doc);
+      continue;
+    }
+
     // Keep excluded docs at full fidelity
     if (excludeSet.has(doc.fileName.toLowerCase())) {
       keepFull.push(doc);
@@ -294,14 +315,22 @@ async function deepSummarize(ai, contextDocs, opts = {}) {
   }
 
   // Build focus topics from excluded docs (tell summarizer what to prioritize)
+  // NOTE: transcript files (VTT/SRT) are auto-excluded but NOT used as focus
+  // topics — they are time-sliced per segment and don't represent "topics".
   const focusTopics = keepFull
     .filter(d => d.type === 'inlineText' && excludeSet.has(d.fileName.toLowerCase()))
     .map(d => d.fileName);
 
+  // Count auto-excluded transcript files for logging
+  const autoExcludedTranscripts = keepFull.filter(d => isTranscriptFile(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 (autoExcludedTranscripts.length > 0) {
+    console.log(`    Auto-excluded ${c.highlight(autoExcludedTranscripts.length)} transcript file(s) (VTT/SRT — time-sliced per segment)`);
+  }
   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)}`));
@@ -350,6 +379,12 @@ async function deepSummarize(ai, contextDocs, opts = {}) {
       continue;
     }
 
+    // Auto-exclude transcript files (VTT/SRT)
+    if (isTranscriptFile(doc.fileName)) {
+      resultDocs.push(doc);
+      continue;
+    }
+
     // Check if we have a summary for this doc
     const summaryKey = doc.fileName.toLowerCase();
     const summary = allSummaries.get(summaryKey);
@@ -399,6 +434,8 @@ module.exports = {
   deepSummarize,
   summarizeBatch,
   buildBatches,
+  isTranscriptFile,
+  TRANSCRIPT_EXTENSIONS,
   SUMMARY_MAX_OUTPUT,
   BATCH_MAX_CHARS,
   MIN_SUMMARIZE_LENGTH,

package/src/modes/focused-reanalysis.js

@@ -136,9 +136,24 @@ function identifyWeaknesses(qualityReport, analysis) {
     );
   }
 
+  // ── Skip focused pass for simple / sparse segments ──────────────────────
+  // When the analysis has very few extracted items AND the density dimension
+  // is low, the segment is likely simple (chit-chat, small-talk, intro) or
+  // the AI legitimately had nothing to extract. A focused pass won't help.
+  const totalItems = [
+    ...(analysis.tickets || []),
+    ...(analysis.action_items || []),
+    ...(analysis.change_requests || []),
+    ...(analysis.blockers || []),
+    ...(analysis.scope_changes || []),
+  ].length;
+
+  const isSparseSegment = totalItems <= 2 && dims.density && dims.density.score < 30;
+
   const shouldReanalyze = focusInstructions.length > 0 &&
     qualityReport.score < 60 &&       // Only re-analyze if quality is truly lacking
-    weakAreas.length >= 2;            // At least 2 weak areas to justify the cost
+    weakAreas.length >= 2 &&          // At least 2 weak areas to justify the cost
+    !isSparseSegment;                 // Don't waste tokens on sparse / simple segments
 
   const focusPrompt = focusInstructions.length > 0
     ? focusInstructions.join('\n\n')

package/src/phases/init.js

@@ -66,6 +66,7 @@ async function phaseInit() {
     disableLearning: !!flags['no-learning'],
     disableDiff: !!flags['no-diff'],
     noHtml: !!flags['no-html'],
+    noBatch: !!flags['no-batch'],
     // Video processing flags
     noCompress: !!flags['no-compress'],
     speed: flags.speed ? parseFloat(flags.speed) : null,
@@ -355,6 +356,7 @@ function _printRunSummary(opts, modelId, models, targetDir) {
   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.noBatch) features.push(c.green('batch'));
   if (opts.resume) features.push(c.yellow('resume'));
   if (opts.dryRun) features.push(c.yellow('dry-run'));
   if (opts.skipUpload) features.push(c.dim('skip-upload'));
@@ -363,6 +365,7 @@ function _printRunSummary(opts, modelId, models, targetDir) {
   if (opts.disableFocusedPass) disabled.push(c.dim('no-focused'));
   if (opts.disableLearning) disabled.push(c.dim('no-learning'));
   if (opts.disableDiff) disabled.push(c.dim('no-diff'));
+  if (opts.noBatch) disabled.push(c.dim('no-batch'));
 
   if (features.length > 0) {
     console.log(`    ${c.dim('Features:')}    ${features.join(c.dim(' · '))}`);

package/src/phases/process-media.js

@@ -9,7 +9,7 @@ const { AUDIO_EXTS, SPEED } = config;
 
 // --- Services ---
 const { uploadToStorage, storageExists } = require('../services/firebase');
-const { processWithGemini, cleanupGeminiFiles } = require('../services/gemini');
+const { processWithGemini, processSegmentBatch, cleanupGeminiFiles } = require('../services/gemini');
 const { compressAndSegment, compressAndSegmentAudio, splitOnly, probeFormat, verifySegment } = require('../services/video');
 
 // --- Utils ---
@@ -19,7 +19,7 @@ const { parallelMap } = require('../utils/retry');
 const { assessQuality, formatQualityLine, getConfidenceStats, THRESHOLDS } = require('../utils/quality-gate');
 const { validateAnalysis, formatSchemaLine, schemaScore, normalizeAnalysis } = require('../utils/schema-validator');
 const { calculateThinkingBudget } = require('../utils/adaptive-budget');
-const { detectBoundaryContext, sliceVttForSegment } = require('../utils/context-manager');
+const { detectBoundaryContext, sliceVttForSegment, planSegmentBatches, estimateTokens, buildProgressiveContext } = require('../utils/context-manager');
 
 // --- Modes ---
 const { identifyWeaknesses, runFocusedPass, mergeFocusedResults } = require('../modes/focused-reanalysis');
@@ -245,6 +245,240 @@ async function phaseProcessVideo(ctx, videoPath, videoIndex) {
   const segmentAnalyses = [];
   const segmentReports = []; // Quality reports for health dashboard
 
+  // ════════════════════════════════════════════════════════════
+  //  Multi-Segment Batching — pass multiple segments per call
+  //  when the context window has enough headroom.
+  // ════════════════════════════════════════════════════════════
+  const useBatching = !opts.noBatch && !opts.skipGemini && !opts.dryRun && segments.length > 1;
+  let batchedSuccessfully = false;
+
+  if (useBatching) {
+    const prevTokens = estimateTokens(buildProgressiveContext(previousAnalyses, userName) || '');
+    const { batches, batchSize, reason } = planSegmentBatches(
+      segmentMeta, contextDocs,
+      {
+        contextWindow: config.GEMINI_CONTEXT_WINDOW || 1_048_576,
+        previousAnalysesTokens: prevTokens,
+      }
+    );
+
+    if (batchSize > 1) {
+      console.log(`  ${c.cyan('⚡ Multi-segment batching:')} ${batches.length} batch(es), up to ${batchSize} segments/batch`);
+      console.log(`    ${c.dim(reason)}`);
+      console.log('');
+      batchedSuccessfully = true; // will be set false if we need to fall back
+
+      for (let bIdx = 0; bIdx < batches.length; bIdx++) {
+        if (isShuttingDown()) break;
+        const batchIndices = batches[bIdx];
+        const batchSegs = batchIndices.map(i => ({
+          segPath: segmentMeta[i].segPath,
+          segName: segmentMeta[i].segName,
+          durSec: segmentMeta[i].durSec,
+          storageUrl: segmentMeta[i].storageUrl,
+        }));
+        const batchTimes = batchIndices.map(i => ({
+          startTimeSec: segmentMeta[i].startTimeSec,
+          endTimeSec: segmentMeta[i].endTimeSec,
+        }));
+
+        const batchLabel = batchIndices.length === 1
+          ? `seg ${batchIndices[0] + 1}`
+          : `segs ${batchIndices[0] + 1}–${batchIndices[batchIndices.length - 1] + 1}`;
+        console.log(`  ${c.cyan('══')} Batch ${c.highlight(`${bIdx + 1}/${batches.length}`)} (${batchLabel}) ${c.cyan('══')}`);
+
+        // Skip batches where all segments have cached runs and user didn't force re-analyze
+        if (!forceReanalyze) {
+          const allCached = batchIndices.every(i => {
+            const prefix = `segment_${String(i).padStart(2, '0')}_`;
+            const existing = fs.readdirSync(geminiRunsDir).filter(f => f.startsWith(prefix) && f.endsWith('.json'));
+            return existing.length > 0;
+          });
+          if (allCached) {
+            // Load cached results for all segments in this batch
+            let cacheOk = true;
+            for (const i of batchIndices) {
+              const prefix = `segment_${String(i).padStart(2, '0')}_`;
+              const existing = fs.readdirSync(geminiRunsDir).filter(f => f.startsWith(prefix) && f.endsWith('.json')).sort();
+              const latestFile = existing[existing.length - 1];
+              try {
+                const cached = JSON.parse(fs.readFileSync(path.join(geminiRunsDir, latestFile), 'utf8'));
+                const analysis = normalizeAnalysis(cached.output.parsed || { rawResponse: cached.output.raw });
+                analysis._geminiMeta = {
+                  model: cached.run.model,
+                  processedAt: cached.run.timestamp,
+                  durationMs: cached.run.durationMs,
+                  tokenUsage: cached.run.tokenUsage || null,
+                  runFile: path.relative(PROJECT_ROOT, path.join(geminiRunsDir, latestFile)),
+                  parseSuccess: cached.output.parseSuccess,
+                  skipped: true,
+                };
+                if (cached.run.tokenUsage) {
+                  costTracker.addSegment(segmentMeta[i].segName, cached.run.tokenUsage, cached.run.durationMs, true);
+                }
+                const cachedQuality = assessQuality(analysis, { parseSuccess: cached.output.parseSuccess, rawLength: (cached.output.raw || '').length });
+                segmentReports.push({ segmentName: segmentMeta[i].segName, qualityReport: cachedQuality, retried: false, retryImproved: false });
+                previousAnalyses.push(analysis);
+                segmentAnalyses.push(analysis);
+
+                fileResult.segments.push({
+                  segmentFile: segmentMeta[i].segName, segmentIndex: i,
+                  storagePath: segmentMeta[i].storagePath, storageUrl: segmentMeta[i].storageUrl,
+                  duration: fmtDuration(segmentMeta[i].durSec), durationSeconds: segmentMeta[i].durSec,
+                  fileSizeMB: parseFloat(segmentMeta[i].sizeMB),
+                  geminiRunFile: path.relative(PROJECT_ROOT, path.join(geminiRunsDir, latestFile)),
+                  analysis,
+                });
+                console.log(`    ${c.success(`seg ${i + 1}: loaded from cache (${latestFile})`)}`);
+              } catch (err) {
+                console.warn(`    ${c.warn(`seg ${i + 1}: cache corrupt — will re-analyze`)}`);
+                cacheOk = false;
+                break;
+              }
+            }
+            if (cacheOk) {
+              console.log('');
+              continue; // skip to next batch
+            }
+          }
+        }
+
+        // Verify all segments in batch
+        const invalidInBatch = batchIndices.filter(i => !verifySegment(segmentMeta[i].segPath));
+        if (invalidInBatch.length > 0) {
+          console.warn(`    ${c.warn(`${invalidInBatch.length} corrupt segment(s) in batch — falling back to single-segment mode`)}`);
+          batchedSuccessfully = false;
+          break;
+        }
+
+        try {
+          let batchRun;
+          try {
+            batchRun = await processSegmentBatch(
+              ai, batchSegs,
+              `${callName}_${baseName}_batch${bIdx}`,
+              contextDocs, previousAnalyses, userName, PKG_ROOT,
+              {
+                segmentIndices: batchIndices,
+                totalSegments: segments.length,
+                segmentTimes: batchTimes,
+                thinkingBudget: opts.thinkingBudget || 24576,
+                noStorageUrl: !!opts.noStorageUrl,
+              }
+            );
+          } catch (batchErr) {
+            const msg = batchErr.message || '';
+            // If Storage URL was rejected, retry batch with forced File API uploads
+            if (!opts.noStorageUrl && msg.includes('INVALID_ARGUMENT') && batchSegs.some(s => s.storageUrl)) {
+              console.log(`    ${c.warn('Storage URL rejected — retrying batch with File API uploads...')}`);
+              log.warn(`Batch ${bIdx} Storage URL rejected — retrying with noStorageUrl=true`);
+              batchRun = await processSegmentBatch(
+                ai, batchSegs,
+                `${callName}_${baseName}_batch${bIdx}`,
+                contextDocs, previousAnalyses, userName, PKG_ROOT,
+                {
+                  segmentIndices: batchIndices,
+                  totalSegments: segments.length,
+                  segmentTimes: batchTimes,
+                  thinkingBudget: opts.thinkingBudget || 24576,
+                  noStorageUrl: true,
+                }
+              );
+              console.log(`    ${c.success('File API batch retry succeeded')}`);
+            } else {
+              throw batchErr;
+            }
+          }
+
+          // Save batch run file
+          const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+          const batchRunFileName = `batch_${bIdx}_segs_${batchIndices[0]}-${batchIndices[batchIndices.length - 1]}_${ts}.json`;
+          const batchRunPath = path.join(geminiRunsDir, batchRunFileName);
+          fs.writeFileSync(batchRunPath, JSON.stringify(batchRun, null, 2), 'utf8');
+
+          const analysis = normalizeAnalysis(batchRun.output.parsed || { rawResponse: batchRun.output.raw });
+          analysis._geminiMeta = {
+            model: batchRun.run.model,
+            processedAt: batchRun.run.timestamp,
+            durationMs: batchRun.run.durationMs,
+            tokenUsage: batchRun.run.tokenUsage || null,
+            runFile: path.relative(PROJECT_ROOT, batchRunPath),
+            parseSuccess: batchRun.output.parseSuccess,
+            batchMode: true,
+            segmentIndices: batchIndices,
+          };
+
+          // Track cost
+          costTracker.addSegment(`batch_${bIdx}`, batchRun.run.tokenUsage, batchRun.run.durationMs, false);
+
+          // Quality gate
+          const qualityReport = assessQuality(analysis, {
+            parseSuccess: batchRun.output.parseSuccess,
+            rawLength: (batchRun.output.raw || '').length,
+          });
+          console.log(formatQualityLine(qualityReport, `batch ${bIdx + 1}`));
+
+          // Schema validation
+          const schemaReport = validateAnalysis(analysis, 'segment');
+          console.log(formatSchemaLine(schemaReport));
+
+          // Assign batch analysis to each segment in the batch
+          for (const i of batchIndices) {
+            segmentReports.push({ segmentName: segmentMeta[i].segName, qualityReport, retried: false, retryImproved: false });
+            fileResult.segments.push({
+              segmentFile: segmentMeta[i].segName, segmentIndex: i,
+              storagePath: segmentMeta[i].storagePath, storageUrl: segmentMeta[i].storageUrl,
+              duration: fmtDuration(segmentMeta[i].durSec), durationSeconds: segmentMeta[i].durSec,
+              fileSizeMB: parseFloat(segmentMeta[i].sizeMB),
+              geminiRunFile: path.relative(PROJECT_ROOT, batchRunPath),
+              analysis,
+            });
+          }
+
+          // Source-segment tagging
+          const tagSeg = (arr, segNum) => (arr || []).forEach(item => { if (!item.source_segment) item.source_segment = segNum; });
+          for (const i of batchIndices) {
+            tagSeg(analysis.action_items, i + 1);
+            tagSeg(analysis.change_requests, i + 1);
+            tagSeg(analysis.blockers, i + 1);
+            tagSeg(analysis.scope_changes, i + 1);
+          }
+
+          previousAnalyses.push(analysis);
+          segmentAnalyses.push(analysis);
+
+          // Cleanup Gemini File API uploads
+          if (batchRun._geminiFileNames && batchRun._geminiFileNames.length > 0 && ai) {
+            cleanupGeminiFiles(ai, batchRun._geminiFileNames).catch(() => {});
+          }
+
+          const dur = (batchRun.run.durationMs / 1000).toFixed(1);
+          console.log(`    ${c.success(`Batch analysis complete (${dur}s, ${batchIndices.length} segments)`)}`);
+          progress.markAnalyzed(`${baseName}_batch${bIdx}`, path.relative(PROJECT_ROOT, batchRunPath));
+        } catch (err) {
+          console.error(`    ${c.error(`Batch analysis failed: ${err.message}`)}`);
+          console.warn(`    ${c.warn('Falling back to single-segment processing for remaining segments')}`);
+          console.warn(`    ${c.dim('Tip: use --no-batch to disable batching if this persists.')}`);
+          log.error(`Batch ${bIdx} failed — ${err.message}`);
+          batchedSuccessfully = false;
+          break;
+        }
+        console.log('');
+      }
+
+      if (batchedSuccessfully) {
+        const totalSegs = batches.reduce((s, b) => s + b.length, 0);
+        console.log(`  ${c.success(`All ${batches.length} batch(es) complete: ${totalSegs} segments analyzed`)}`);
+        console.log('');
+      }
+    }
+  }
+
+  // ════════════════════════════════════════════════════════════
+  //  Single-Segment Processing (original path / fallback)
+  // ════════════════════════════════════════════════════════════
+  if (!batchedSuccessfully) {
+
   for (let j = 0; j < segments.length; j++) {
     if (isShuttingDown()) break;
 
@@ -647,6 +881,8 @@ async function phaseProcessVideo(ctx, videoPath, videoIndex) {
     console.log('');
   }
 
+  } // end if (!batchedSuccessfully) — single-segment fallback
+
   // Compute totals for this file
   fileResult.compressedTotalMB = fileResult.segments
     .reduce((sum, s) => sum + s.fileSizeMB, 0).toFixed(2);

package/src/phases/summary.js

@@ -40,11 +40,11 @@ function phaseSummary(ctx, results, { jsonPath, mdPath, runTs, compilationRun })
   if (cost.totalTokens > 0) {
     console.log('');
     console.log(`  ${c.heading(`Cost estimate (${config.GEMINI_MODEL}):`)}`);
-    console.log(`    Input tokens  : ${c.yellow(cost.inputTokens.toLocaleString())} ${c.dim(`($${cost.inputCost.toFixed(4)})`)}`);
-    console.log(`    Output tokens : ${c.yellow(cost.outputTokens.toLocaleString())} ${c.dim(`($${cost.outputCost.toFixed(4)})`)}`);
-    console.log(`    Thinking tokens: ${c.yellow(cost.thinkingTokens.toLocaleString())} ${c.dim(`($${cost.thinkingCost.toFixed(4)})`)}`);
-    console.log(`    Total         : ${c.highlight(cost.totalTokens.toLocaleString() + ' tokens')} | ${c.green('$' + cost.totalCost.toFixed(4))}`);
-    console.log(`    AI time       : ${c.yellow((cost.totalDurationMs / 1000).toFixed(1) + 's')}`);
+    console.log(`    Input:    ${c.yellow(cost.inputTokens.toLocaleString())} ${c.dim(`($${cost.inputCost.toFixed(4)})`)}`);
+    console.log(`    Output:   ${c.yellow(cost.outputTokens.toLocaleString())} ${c.dim(`($${cost.outputCost.toFixed(4)})`)}`);
+    console.log(`    Thinking: ${c.yellow(cost.thinkingTokens.toLocaleString())} ${c.dim(`($${cost.thinkingCost.toFixed(4)})`)}`);
+    console.log(`    Total:    ${c.highlight(cost.totalTokens.toLocaleString() + ' tokens')} | ${c.green('$' + cost.totalCost.toFixed(4))}`);
+    console.log(`    AI time:  ${c.yellow((cost.totalDurationMs / 1000).toFixed(1) + 's')}`);
   }
 
   if (firebaseReady && !opts.skipUpload) {

package/src/pipeline.js

@@ -151,7 +151,7 @@ async function run() {
     files: [],
   };
 
-  fullCtx.progress.setPhase('compress');
+  fullCtx.progress.setPhase('analyze');
   bar.setPhase('analyze', mediaFiles.length);
   if (log && log.phaseStart) log.phaseStart('process_videos');
 
@@ -702,6 +702,7 @@ async function runDynamic(initCtx) {
     });
   } catch (err) {
     console.error(`  ${c.error(`Topic planning failed: ${err.message}`)}`);
+    console.error(`    ${c.dim('Tip: check your Gemini API key, or try a simpler --request.')}`);
     log.error(`Dynamic topic planning failed: ${err.message}`);    bar.finish();    initCtx.progress.cleanup();
     log.close();
     return;

package/src/renderers/docx.js

@@ -13,7 +13,7 @@
 'use strict';
 
 const {
-  stripParens, clusterNames, resolve,
+  clusterNames, resolve,
   dedupBy,
 } = require('./shared');
 

package/src/renderers/html.js

@@ -13,9 +13,8 @@
 'use strict';
 
 const {
-  stripParens, normalizeKey, clusterNames, resolve,
+  clusterNames, resolve,
   dedupBy, normalizeDesc, dedupByDesc,
-  fmtTs, priBadge, confBadge, confBadgeFull,
   escHtml,
 } = require('./shared');