geotechcli 0.3.0 → 0.4.1

package/dist/commands/ai.js

@@ -1,10 +1,10 @@
 import { Command } from 'commander';
 import { readFileSync, writeFileSync } from 'node:fs';
-import ora from 'ora';
 import chalk from 'chalk';
-import { buildLLMConfig, analyzeCoreBox, classifyRMRFromImage, classifySoilFromDescription, interpretBoreholeLog, queryGBRDocument, interpretSensorImage, runAgent, runSwarm, AgentConversation, loadProject, getProjectAgentContext, addAgentSession, addArtifact, addNote, saveNamedDataset, saveDerivedParameter, setActiveAnalysisContext, generateReport, renderReportAsPdf, renderReportAsDocx, } from '@geotechcli/core';
-import { heading, keyValue, renderJSON, success, error, warn, renderTable } from '../ui/terminal.js';
+import { buildLLMConfig, DEFAULT_LLM_VISION_MODEL, analyzeCoreBox, classifyRMRFromImage, classifySoilFromDescription, interpretBoreholeLog, queryGBRDocument, interpretSensorImage, runAgent, runSwarm, AgentConversation, loadProject, getProjectAgentContext, addAgentSession, addArtifact, addNote, saveNamedDataset, saveDerivedParameter, setActiveAnalysisContext, generateReport, generateReportFromCaseFile, renderReportAsPdf, renderReportAsDocx, buildSwarmSessionProjectRecord, persistSwarmCaseFile, persistCaseFileEvidence, } from '@geotechcli/core';
+import { heading, keyValue, renderJSON, success, error, warn, renderTable, info } from '../ui/terminal.js';
 import { addGlobalFlags, getGlobalFlags } from '../util/flags.js';
+import { estimateHostedBetaVisionBodyBytes, formatByteSize, HOSTED_BETA_REQUEST_LIMIT_BYTES, readVisionInput, readVisionPdfPageInputs, resolveStructuredOutputTarget, HOSTED_BETA_REQUEST_SAFE_BYTES, } from '../util/vision-output.js';
 async function checkQuota(_callType) {
     // Strong-beta hosted limits are enforced server-side by the beta proxy.
     // Keep the CLI permissive here so successful completions, retries, and
@@ -32,11 +32,251 @@ function loadImageBase64(filePath) {
         mimeType: mimeMap[ext] ?? 'image/png',
     };
 }
+function describeVisionInput(file) {
+    if (file.kind !== 'pdf') {
+        return;
+    }
+    console.log('');
+    console.log(chalk.yellow('  PDF input detected.'));
+    console.log(chalk.gray('    GLM vision works best with PNG or JPG images.'));
+    console.log(chalk.gray('    For borehole logs, the CLI can split multi-page PDFs into page-level requests automatically.'));
+    console.log(chalk.gray('    Oversized PDF pages will still be blocked before upload to avoid the hosted-beta body limit.'));
+    console.log('');
+}
+function ensureHostedBetaVisionPayloadWithinLimit(file, details) {
+    const estimatedBytes = estimateHostedBetaVisionBodyBytes({
+        prompt: details.prompt,
+        systemPrompt: details.systemPrompt,
+        imageBase64: file.base64,
+        mimeType: file.mimeType,
+        model: details.model,
+        temperature: details.temperature,
+        maxTokens: details.maxTokens,
+        jsonMode: false,
+    });
+    if (estimatedBytes <= HOSTED_BETA_REQUEST_SAFE_BYTES) {
+        return;
+    }
+    const fileSize = formatByteSize(file.fileBytes);
+    const payloadSize = formatByteSize(estimatedBytes);
+    const limitSize = formatByteSize(HOSTED_BETA_REQUEST_SAFE_BYTES);
+    const capSize = formatByteSize(HOSTED_BETA_REQUEST_LIMIT_BYTES);
+    const baseMessage = file.kind === 'pdf'
+        ? 'PDF vision inputs are uploaded as a single base64 payload and are too large for the hosted beta proxy.'
+        : 'Image vision inputs are uploaded as a single base64 payload and are too large for the hosted beta proxy.';
+    const mitigation = file.kind === 'pdf'
+        ? 'Export one page as PNG or JPG, or split the PDF into smaller files, then retry.'
+        : 'Resize or crop the image to the relevant region, then retry.';
+    throw new Error(`${baseMessage} File: ${file.filePath} (${fileSize}). Estimated request body: ${payloadSize}. Safe limit: ${limitSize}. Hosted beta cap: ${capSize}.\n${mitigation}`);
+}
+function maybeCheckHostedBetaVisionPayload(config, file, details) {
+    if (config.provider !== 'hosted-beta') {
+        return;
+    }
+    ensureHostedBetaVisionPayloadWithinLimit(file, {
+        ...details,
+        model: config.visionModelId ?? DEFAULT_LLM_VISION_MODEL,
+    });
+}
 function formatMaybe(value, suffix = '') {
     if (value == null || value === '')
         return 'Unavailable';
     return `${value}${suffix}`;
 }
+function startProgress(flags, text) {
+    if (flags.json || flags.quiet) {
+        return null;
+    }
+    info(text);
+    return {
+        succeed(message) {
+            success(message);
+        },
+        fail(message) {
+            error(message);
+        },
+    };
+}
+const SWARM_AGENT_LABELS = {
+    orchestrator: 'Mohr',
+    interpretation: 'Bieniawski',
+    simulation: 'Terzaghi',
+    reviewer: 'Hoek',
+};
+function formatToolPreview(args, limit) {
+    if (!args) {
+        return '';
+    }
+    const serialized = JSON.stringify(args);
+    return serialized.length > limit ? `${serialized.slice(0, limit)}...` : serialized;
+}
+function renderWarningsCompact(warnings) {
+    if (warnings.length === 0)
+        return;
+    const uniqueWarnings = [...new Set(warnings.map((warning) => warning.trim()).filter(Boolean))];
+    const visibleWarnings = uniqueWarnings.slice(0, 5);
+    console.log(chalk.yellow('  Warnings:'));
+    for (const warning of visibleWarnings) {
+        console.log(chalk.yellow(`    - ${warning}`));
+    }
+    if (uniqueWarnings.length > visibleWarnings.length) {
+        console.log(chalk.yellow(`    - ${uniqueWarnings.length - visibleWarnings.length} more warning(s) omitted.`));
+    }
+}
+function renderParseSafetyCompact(result) {
+    keyValue('Parse status', result.parseStatus);
+    keyValue('Confidence', `${result.confidence}%`);
+    keyValue('Auto proceed', result.canAutoProceed ? 'Yes' : 'No');
+    renderWarningsCompact(result.warnings);
+}
+function mergeBoreholeLayers(layers) {
+    const deduped = new Map();
+    for (const layer of layers) {
+        const key = [
+            layer.depthFrom ?? 'na',
+            layer.depthTo ?? 'na',
+            (layer.description ?? '').trim().toLowerCase(),
+            (layer.uscsSymbol ?? '').trim().toUpperCase(),
+            layer.sptN ?? 'na',
+        ].join('|');
+        if (!deduped.has(key)) {
+            deduped.set(key, layer);
+        }
+    }
+    return [...deduped.values()].sort((left, right) => {
+        const leftDepth = left.depthFrom ?? Number.POSITIVE_INFINITY;
+        const rightDepth = right.depthFrom ?? Number.POSITIVE_INFINITY;
+        return leftDepth - rightDepth;
+    });
+}
+function mergeBoreholeInterpretations(pages, overrideBoreholeId) {
+    const validPages = pages.filter(({ result }) => result.layers.length > 0 || result.totalDepth != null || result.summary);
+    const sourcePages = validPages.length > 0 ? validPages : pages;
+    const mergedLayers = mergeBoreholeLayers(sourcePages.flatMap(({ result }) => result.layers));
+    const summaries = [...new Set(sourcePages.map(({ result }) => result.summary?.trim()).filter((value) => Boolean(value)))];
+    const warnings = [...new Set(pages.flatMap(({ pageNumber, result }) => result.warnings.map((warning) => `Page ${pageNumber}: ${warning}`)))];
+    const confidences = sourcePages.map(({ result }) => result.confidence);
+    const averageConfidence = confidences.length > 0
+        ? Math.round(confidences.reduce((sum, value) => sum + value, 0) / confidences.length)
+        : 0;
+    const totalDepth = sourcePages.reduce((maxDepth, { result }) => {
+        if (result.totalDepth == null)
+            return maxDepth;
+        return maxDepth == null ? result.totalDepth : Math.max(maxDepth, result.totalDepth);
+    }, null);
+    const waterTableDepth = sourcePages.reduce((selected, { result }) => {
+        if (result.waterTableDepth == null)
+            return selected;
+        return selected == null ? result.waterTableDepth : Math.min(selected, result.waterTableDepth);
+    }, null);
+    const parseStatus = mergedLayers.length > 0 && totalDepth != null
+        ? 'parsed'
+        : mergedLayers.length > 0 || summaries.length > 0 || totalDepth != null
+            ? 'partial'
+            : 'failed';
+    return {
+        boreholeId: overrideBoreholeId
+            ?? sourcePages.map(({ result }) => result.boreholeId).find((value) => value && value !== 'BH-unknown')
+            ?? 'BH-unknown',
+        totalDepth,
+        waterTableDepth,
+        layers: mergedLayers,
+        summary: summaries.length > 0 ? summaries.join(' ') : null,
+        rawLLMText: pages.map(({ pageNumber, result }) => `[Page ${pageNumber}]\n${result.rawLLMText}`).join('\n\n'),
+        latencyMs: pages.reduce((sum, { result }) => sum + result.latencyMs, 0),
+        parseStatus,
+        confidence: averageConfidence,
+        warnings,
+        canAutoProceed: parseStatus === 'parsed' && averageConfidence >= 70,
+    };
+}
+function handleCommandErrorClean(err, flags, code = 'command_failed') {
+    const message = getErrorMessage(err);
+    process.exitCode = 1;
+    if (flags.json) {
+        renderJSON({ error: { code, message } });
+        return;
+    }
+    if (code.includes('vision') || code.includes('corebox') || code.includes('rmr') || code.includes('sensor') || code.includes('borehole')) {
+        const lowered = message.toLowerCase();
+        if (lowered.includes('no content') ||
+            lowered.includes('empty') ||
+            lowered.includes('upstream') ||
+            lowered.includes('hosted beta proxy') ||
+            lowered.includes('too large for the hosted beta proxy') ||
+            lowered.includes('safe limit')) {
+            error(message);
+            console.log('');
+            console.log(chalk.gray('  Vision troubleshooting tips:'));
+            console.log(chalk.gray('    - Use PNG or JPG images (not PDF or BMP)'));
+            console.log(chalk.gray('    - Ensure the image is well-lit and clearly shows the subject'));
+            console.log(chalk.gray('    - Try a smaller image file (< 5 MB)'));
+            console.log(chalk.gray('    - Wait a moment and retry; the AI provider may be busy'));
+            console.log(chalk.gray('    - Run with --verbose to see the raw response'));
+            return;
+        }
+    }
+    error(message);
+}
+function renderAgentStepPlain(step, json, quiet = false) {
+    if (json || quiet)
+        return;
+    switch (step.type) {
+        case 'thought':
+            return;
+        case 'tool_call':
+            console.log(chalk.cyan(`  [Terzaghi] Tool: ${step.toolName}(${formatToolPreview(step.toolArgs, 120)})`));
+            return;
+        case 'tool_result':
+            if (step.toolResult?.success) {
+                console.log(chalk.green(`  [Terzaghi] Result: ${step.content}`));
+            }
+            else {
+                console.log(chalk.red(`  [Terzaghi] Error: ${step.content}`));
+            }
+            return;
+        case 'answer':
+            return;
+        case 'error':
+            console.log(chalk.red(`  [Terzaghi] Error: ${step.content}`));
+            return;
+    }
+}
+function renderSwarmStepPlain(step, json, quiet = false) {
+    if (json || quiet)
+        return;
+    const label = SWARM_AGENT_LABELS[step.agent] ?? step.agent;
+    const tag = `[${label}]`;
+    switch (step.type) {
+        case 'thought':
+            return;
+        case 'tool_call':
+            console.log(chalk.cyan(`  ${tag} Tool: ${step.toolName}(${formatToolPreview(step.toolArgs, 100)})`));
+            return;
+        case 'tool_result':
+            if (step.toolResult?.success) {
+                console.log(chalk.green(`  ${tag} Result: ${step.content.slice(0, 180)}`));
+            }
+            else {
+                console.log(chalk.red(`  ${tag} Error: ${step.content.slice(0, 180)}`));
+            }
+            return;
+        case 'handoff':
+            console.log(chalk.magenta(`  ${tag} Handoff: ${step.content}`));
+            return;
+        case 'review':
+            console.log(chalk.green(`  ${tag} Review: ${step.content}`));
+            return;
+        case 'correction':
+            console.log(chalk.red(`  ${tag} Correction: ${step.content.slice(0, 200)}`));
+            return;
+        case 'answer':
+            return;
+        case 'error':
+            console.log(chalk.red(`  ${tag} Error: ${step.content}`));
+            return;
+    }
+}
 function sanitizeErrorMessage(message) {
     return message.replace(/(?:Bearer |sk-|zhipu-|api[_-]?key[=: ]*)[^\s"'\]},]*/gi, '***REDACTED***');
 }
@@ -52,7 +292,13 @@ function handleCommandError(err, flags, code = 'command_failed') {
     }
     // Provide specific guidance for common vision errors
     if (code.includes('vision') || code.includes('corebox') || code.includes('rmr') || code.includes('sensor') || code.includes('borehole')) {
-        if (message.toLowerCase().includes('no content') || message.toLowerCase().includes('empty') || message.toLowerCase().includes('upstream')) {
+        const lowered = message.toLowerCase();
+        if (lowered.includes('no content') ||
+            lowered.includes('empty') ||
+            lowered.includes('upstream') ||
+            lowered.includes('hosted beta proxy') ||
+            lowered.includes('too large for the hosted beta proxy') ||
+            lowered.includes('safe limit')) {
             error(message);
             console.log('');
             console.log(chalk.gray('  Vision troubleshooting tips:'));
@@ -69,10 +315,15 @@ function handleCommandError(err, flags, code = 'command_failed') {
 function renderWarnings(warnings) {
     if (warnings.length === 0)
         return;
+    const uniqueWarnings = [...new Set(warnings.map((warning) => warning.trim()).filter(Boolean))];
+    const visibleWarnings = uniqueWarnings.slice(0, 5);
     console.log(chalk.yellow('  Warnings:'));
-    for (const warning of warnings) {
+    for (const warning of visibleWarnings) {
         console.log(chalk.yellow(`    - ${warning}`));
     }
+    if (uniqueWarnings.length > visibleWarnings.length) {
+        console.log(chalk.yellow(`    - ${uniqueWarnings.length - visibleWarnings.length} more warning(s) omitted.`));
+    }
 }
 function renderParseSafety(result) {
     keyValue('Parse status', result.parseStatus);
@@ -98,17 +349,34 @@ function persistSessionToProject(projectId, mode, query, session) {
             corrections: session.corrections,
         }
         : undefined;
-    addAgentSession(projectId, {
-        mode,
-        query,
-        answer,
-        summary: answer?.slice(0, 240) ?? `${mode} session for: ${query.slice(0, 120)}`,
-        stepCount: session.steps.length,
-        tokens: session.totalTokens,
-        latencyMs: session.totalLatencyMs,
-        context: session.context,
-        metadata: reviewMetadata,
-    });
+    if (mode === 'swarm') {
+        const swarmSession = session;
+        addAgentSession(projectId, buildSwarmSessionProjectRecord(query, swarmSession, {
+            mode,
+            answer,
+            summary: answer?.slice(0, 240) ?? `${mode} session for: ${query.slice(0, 120)}`,
+            metadata: reviewMetadata,
+        }));
+        const caseFileResult = persistSwarmCaseFile(projectId, query, swarmSession);
+        const evidenceRecords = persistCaseFileEvidence(projectId, caseFileResult.scenarioId);
+        addNote(projectId, `Updated swarm case file "${caseFileResult.scenarioId}" from the latest session.`);
+        if (evidenceRecords.length > 0) {
+            addNote(projectId, `Captured ${evidenceRecords.length} evidence record${evidenceRecords.length === 1 ? '' : 's'} for scenario "${caseFileResult.scenarioId}".`);
+        }
+    }
+    else {
+        addAgentSession(projectId, {
+            mode,
+            query,
+            answer,
+            summary: answer?.slice(0, 240) ?? `${mode} session for: ${query.slice(0, 120)}`,
+            stepCount: session.steps.length,
+            tokens: session.totalTokens,
+            latencyMs: session.totalLatencyMs,
+            context: session.context,
+            metadata: reviewMetadata,
+        });
+    }
     saveNamedDataset(projectId, {
         name: 'latest-agent-context',
         kind: 'agent-context',
@@ -151,6 +419,26 @@ function persistOutputArtifact(projectId, kind, title, path, metadata) {
         metadata,
     });
 }
+function buildAnalysisDocument(title, task, answer, mode) {
+    const content = [
+        `## Task`,
+        task,
+        '',
+        `## ${mode === 'swarm' ? 'Swarm Report' : 'Analysis'}`,
+        answer,
+    ].join('\n');
+    return {
+        title,
+        sections: [
+            {
+                title: 'Summary',
+                content,
+            },
+        ],
+        fullMarkdown: `# ${title}\n\n${content}\n`,
+        latencyMs: 0,
+    };
+}
 // ---------------------------------------------------------------------------
 // Vision Commands
 // ---------------------------------------------------------------------------
@@ -159,24 +447,31 @@ export function registerVisionCommand(program) {
         .description('AI vision analysis for geotechnical images');
     // Core box analysis
     const coreboxCmd = new Command('corebox')
-        .description('Analyze core box image → RQD, fracture spacing, weathering')
+        .description('Analyze a core box image for RQD, fracture spacing, and weathering')
         .argument('<image>', 'Path to core box image')
         .action(async (imagePath, opts) => {
         const flags = getGlobalFlags(opts);
         if (!(await checkQuota('visionCalls')))
             return;
-        const spinner = flags.json ? null : ora({ text: 'Analyzing core box image...', indent: 2 }).start();
+        const spinner = startProgress(flags, 'Analyzing core box image...');
         try {
-            const { base64, mimeType } = loadImageBase64(imagePath);
+            const file = readVisionInput(imagePath);
+            describeVisionInput(file);
             const config = buildLLMConfig();
-            const result = await analyzeCoreBox(base64, mimeType, config);
+            maybeCheckHostedBetaVisionPayload(config, file, {
+                prompt: 'Analyze this geotechnical image.',
+                systemPrompt: 'You are analyzing a geotechnical image.',
+                temperature: 0.1,
+                maxTokens: 900,
+            });
+            const result = await analyzeCoreBox(file.base64, file.mimeType, config);
             spinner?.succeed(`Analysis complete (${result.latencyMs}ms)`);
             if (flags.json) {
                 renderJSON(result);
                 return;
             }
             heading('Core Box Analysis');
-            renderParseSafety(result);
+            renderParseSafetyCompact(result);
             keyValue('RQD', formatMaybe(result.rqd, '%'));
             keyValue('Fracture spacing', formatMaybe(result.fractureSpacing));
             keyValue('Weathering grade', formatMaybe(result.weatheringGrade));
@@ -191,31 +486,38 @@ export function registerVisionCommand(program) {
         }
         catch (err) {
             spinner?.fail('Analysis failed');
-            handleCommandError(err, flags, 'corebox_analysis_failed');
+            handleCommandErrorClean(err, flags, 'corebox_analysis_failed');
         }
     });
     addGlobalFlags(coreboxCmd);
     vision.addCommand(coreboxCmd);
     // Hybrid RMR from image
     const rmrImageCmd = new Command('rmr')
-        .description('Hybrid RMR: vision extracts features → deterministic RMR scoring')
+        .description('Hybrid RMR: vision extracts features, then deterministic RMR scoring')
         .argument('<image>', 'Path to rock face / core image')
         .action(async (imagePath, opts) => {
         const flags = getGlobalFlags(opts);
         if (!(await checkQuota('visionCalls')))
             return;
-        const spinner = flags.json ? null : ora({ text: 'Extracting rock mass parameters from image...', indent: 2 }).start();
+        const spinner = startProgress(flags, 'Extracting rock mass parameters from image...');
         try {
-            const { base64, mimeType } = loadImageBase64(imagePath);
+            const file = readVisionInput(imagePath);
+            describeVisionInput(file);
             const config = buildLLMConfig();
-            const result = await classifyRMRFromImage(base64, mimeType, config);
+            maybeCheckHostedBetaVisionPayload(config, file, {
+                prompt: 'Estimate rock mass parameters from this image.',
+                systemPrompt: 'You are analyzing a geotechnical image.',
+                temperature: 0.1,
+                maxTokens: 700,
+            });
+            const result = await classifyRMRFromImage(file.base64, file.mimeType, config);
             spinner?.succeed(`RMR classification complete (${result.latencyMs}ms)`);
             if (flags.json) {
                 renderJSON(result);
                 return;
             }
             heading('Hybrid RMR Classification (Vision + Deterministic)');
-            renderParseSafety(result);
+            renderParseSafetyCompact(result);
             console.log('');
             console.log(chalk.gray('  Vision-extracted parameters:'));
             keyValue('  Estimated UCS', formatMaybe(result.visionExtraction.estimatedUCS, ' MPa'));
@@ -237,7 +539,7 @@ export function registerVisionCommand(program) {
         }
         catch (err) {
             spinner?.fail('RMR classification failed');
-            handleCommandError(err, flags, 'rmr_classification_failed');
+            handleCommandErrorClean(err, flags, 'rmr_classification_failed');
         }
     });
     addGlobalFlags(rmrImageCmd);
@@ -250,18 +552,25 @@ export function registerVisionCommand(program) {
         const flags = getGlobalFlags(opts);
         if (!(await checkQuota('visionCalls')))
             return;
-        const spinner = flags.json ? null : ora({ text: 'Interpreting sensor data...', indent: 2 }).start();
+        const spinner = startProgress(flags, 'Interpreting sensor data...');
         try {
-            const { base64, mimeType } = loadImageBase64(imagePath);
+            const file = readVisionInput(imagePath);
+            describeVisionInput(file);
             const config = buildLLMConfig();
-            const result = await interpretSensorImage(base64, mimeType, config);
+            maybeCheckHostedBetaVisionPayload(config, file, {
+                prompt: 'Interpret this sensor data image.',
+                systemPrompt: 'You are analyzing a geotechnical image.',
+                temperature: 0.1,
+                maxTokens: 700,
+            });
+            const result = await interpretSensorImage(file.base64, file.mimeType, config);
             spinner?.succeed(`Interpretation complete (${result.latencyMs}ms)`);
             if (flags.json) {
                 renderJSON(result);
                 return;
             }
-            heading(`Sensor Interpretation — ${result.sensorType ?? 'Unknown'}`);
-            renderParseSafety(result);
+            heading(`Sensor Interpretation - ${result.sensorType ?? 'Unknown'}`);
+            renderParseSafetyCompact(result);
             keyValue('Sensor type', formatMaybe(result.sensorType));
             keyValue('Measurements', formatMaybe(result.measurements));
             console.log('');
@@ -277,7 +586,7 @@ export function registerVisionCommand(program) {
         }
         catch (err) {
             spinner?.fail('Sensor interpretation failed');
-            handleCommandError(err, flags, 'sensor_interpretation_failed');
+            handleCommandErrorClean(err, flags, 'sensor_interpretation_failed');
         }
     });
     addGlobalFlags(sensorCmd);
@@ -291,18 +600,63 @@ export function registerVisionCommand(program) {
         const flags = getGlobalFlags(opts);
         if (!(await checkQuota('visionCalls')))
             return;
-        const spinner = flags.json ? null : ora({ text: 'Extracting borehole log data...', indent: 2 }).start();
+        const spinner = startProgress(flags, 'Extracting borehole log data...');
         try {
-            const { base64, mimeType } = loadImageBase64(filePath);
+            const file = readVisionInput(filePath);
+            describeVisionInput(file);
             const config = buildLLMConfig();
-            const result = await interpretBoreholeLog(base64, mimeType, config, opts.boreholeId);
-            spinner?.succeed(`Extraction complete: ${result.layers.length} layers (${result.latencyMs}ms)`);
+            const requestDetails = {
+                prompt: 'Extract structured borehole log data.',
+                systemPrompt: 'You are analyzing a geotechnical image.',
+                temperature: 0.1,
+                maxTokens: 900,
+            };
+            let result;
+            if (file.kind === 'pdf') {
+                const pageInputs = await readVisionPdfPageInputs(filePath);
+                if (!flags.json && !flags.quiet && pageInputs.length > 1) {
+                    info(`PDF contains ${pageInputs.length} pages. Processing borehole log pages sequentially.`);
+                }
+                const pageResults = [];
+                const pageFailures = [];
+                for (const pageInput of pageInputs) {
+                    if (!flags.json && !flags.quiet && pageInputs.length > 1) {
+                        info(`Processing PDF page ${pageInput.pageNumber}/${pageInput.totalPages}...`);
+                    }
+                    try {
+                        maybeCheckHostedBetaVisionPayload(config, pageInput, requestDetails);
+                        const pageResult = await interpretBoreholeLog(pageInput.base64, pageInput.mimeType, config, opts.boreholeId);
+                        pageResults.push({
+                            pageNumber: pageInput.pageNumber,
+                            result: pageResult,
+                        });
+                    }
+                    catch (pageError) {
+                        pageFailures.push(`Page ${pageInput.pageNumber}: ${getErrorMessage(pageError)}`);
+                    }
+                }
+                if (pageResults.length === 0) {
+                    throw new Error(pageFailures.length > 0
+                        ? `No PDF pages could be processed successfully.\n${pageFailures.join('\n')}`
+                        : 'No PDF pages could be processed successfully.');
+                }
+                result = mergeBoreholeInterpretations(pageResults, opts.boreholeId);
+                if (pageFailures.length > 0) {
+                    result.warnings = [...result.warnings, ...pageFailures];
+                }
+                spinner?.succeed(`Extraction complete: ${result.layers.length} layers from ${pageResults.length}/${pageInputs.length} page(s) (${result.latencyMs}ms)`);
+            }
+            else {
+                maybeCheckHostedBetaVisionPayload(config, file, requestDetails);
+                result = await interpretBoreholeLog(file.base64, file.mimeType, config, opts.boreholeId);
+                spinner?.succeed(`Extraction complete: ${result.layers.length} layers (${result.latencyMs}ms)`);
+            }
             if (flags.json) {
                 renderJSON(result);
                 return;
             }
-            heading(`Borehole Log — ${result.boreholeId}`);
-            renderParseSafety(result);
+            heading(`Borehole Log - ${result.boreholeId}`);
+            renderParseSafetyCompact(result);
             keyValue('Total depth', formatMaybe(result.totalDepth, ' m'));
             keyValue('Water table', result.waterTableDepth != null ? `${result.waterTableDepth} m` : 'Not detected');
             renderTable(['From (m)', 'To (m)', 'Description', 'USCS', 'SPT-N'], result.layers.map((l) => [
@@ -323,7 +677,7 @@ export function registerVisionCommand(program) {
         }
         catch (err) {
             spinner?.fail('Extraction failed');
-            handleCommandError(err, flags, 'borehole_extraction_failed');
+            handleCommandErrorClean(err, flags, 'borehole_extraction_failed');
         }
     });
     addGlobalFlags(logCmd);
@@ -342,7 +696,7 @@ export function registerAIClassifyCommand(program) {
         const description = descParts.join(' ');
         if (!(await checkQuota('llmCalls')))
             return;
-        const spinner = flags.json ? null : ora({ text: 'Classifying soil from description...', indent: 2 }).start();
+        const spinner = startProgress(flags, 'Classifying soil from description...');
         try {
             const config = buildLLMConfig();
             const result = await classifySoilFromDescription(description, config);
@@ -353,7 +707,7 @@ export function registerAIClassifyCommand(program) {
             }
             heading('AI Soil Classification');
             keyValue('Input', `"${description}"`);
-            renderParseSafety(result);
+            renderParseSafetyCompact(result);
             keyValue('USCS symbol', formatMaybe(result.uscsSymbol));
             keyValue('USCS name', formatMaybe(result.uscsName));
             keyValue('Friction angle', formatMaybe(result.estimatedProperties.frictionAngle, ' deg'));
@@ -367,7 +721,7 @@ export function registerAIClassifyCommand(program) {
         }
         catch (err) {
             spinner?.fail('Classification failed');
-            handleCommandError(err, flags, 'ai_classification_failed');
+            handleCommandErrorClean(err, flags, 'ai_classification_failed');
         }
     });
     addGlobalFlags(cmd);
@@ -388,11 +742,18 @@ export function registerGBRCommand(program) {
         const question = questionParts.join(' ');
         if (!(await checkQuota('llmCalls')))
             return;
-        const spinner = flags.json ? null : ora({ text: `Querying GBR: "${question.slice(0, 50)}..."`, indent: 2 }).start();
+        const spinner = startProgress(flags, `Querying GBR: "${question.slice(0, 50)}..."`);
         try {
-            const { base64, mimeType } = loadImageBase64(opts.doc);
+            const file = readVisionInput(opts.doc);
+            describeVisionInput(file);
             const config = buildLLMConfig();
-            const result = await queryGBRDocument(question, base64, mimeType, config);
+            maybeCheckHostedBetaVisionPayload(config, file, {
+                prompt: 'Answer questions about this GBR document.',
+                systemPrompt: 'You are analyzing a geotechnical document image.',
+                temperature: 0.1,
+                maxTokens: 700,
+            });
+            const result = await queryGBRDocument(question, file.base64, file.mimeType, config);
             spinner?.succeed(`Answer ready (${result.latencyMs}ms)`);
             if (flags.json) {
                 renderJSON({ question, answer: result.answer, latencyMs: result.latencyMs });
@@ -406,7 +767,7 @@ export function registerGBRCommand(program) {
         }
         catch (err) {
             spinner?.fail('GBR query failed');
-            handleCommandError(err, flags, 'gbr_query_failed');
+            handleCommandErrorClean(err, flags, 'gbr_query_failed');
         }
     });
     addGlobalFlags(chatCmd);
@@ -505,9 +866,9 @@ function renderSwarmStep(step, json, quiet = false) {
 }
 export function registerAgentCommand(program) {
     const cmd = new Command('agent')
-        .description('Agentic AI — reasons about your problem and executes real calculations')
+        .description('Agentic AI - reasons about your problem and executes real calculations')
         .argument('<task...>', 'Engineering task in natural language')
-        .option('--swarm', 'Use multi-agent swarm (Interpretation → Simulation → Reviewer)')
+        .option('--swarm', 'Use multi-agent swarm (Bieniawski -> Terzaghi -> Hoek)')
         .option('--project <id>', 'Load and persist context to a stored project')
         .action(async (taskParts, opts) => {
         const flags = getGlobalFlags(opts);
@@ -518,10 +879,10 @@ export function registerAgentCommand(program) {
         if (!flags.json) {
             console.log('');
             if (useSwarm) {
-                console.log(chalk.gray('  Swarm activated — Interpretation → Simulation → Reviewer'));
+                console.log(chalk.gray('  Swarm activated - Bieniawski, Terzaghi, and Hoek coordinated by Mohr'));
             }
             else {
-                console.log(chalk.gray('  Agent activated — planning and executing...'));
+                console.log(chalk.gray('  Agent activated - Terzaghi is planning and executing'));
             }
             console.log('');
         }
@@ -535,7 +896,7 @@ export function registerAgentCommand(program) {
             if (useSwarm) {
                 // Multi-agent swarm mode
                 const session = await runSwarm(task, config, (step) => {
-                    renderSwarmStep(step, flags.json, flags.quiet);
+                    renderSwarmStepPlain(step, flags.json, flags.quiet);
                 }, projectState?.context);
                 const answer = session.steps.find((s) => s.type === 'answer');
                 if (projectState) {
@@ -570,18 +931,34 @@ export function registerAgentCommand(program) {
                     const toolCalls = session.steps.filter((s) => s.type === 'tool_call').length;
                     const agents = [...new Set(session.steps.map((s) => s.agent))];
                     console.log(chalk.gray(`  (${agents.length} agents, ${toolCalls} tools executed, review: ${session.reviewPassed ? 'PASSED' : 'ISSUES NOTED'}, ${session.totalTokens} tokens)`));
-                    console.log(chalk.cyan('\n  Hint: To continue this session interactively, run: ') + chalk.white(`geotech chat${opts.project ? ` --project ${opts.project}` : ''}`));
+                    console.log(chalk.cyan('\n  Continue interactively with: ') + chalk.white(`geotech chat${opts.project ? ` --project ${opts.project}` : ''}`));
                 }
                 if (flags.output && answer) {
-                    writeFileSync(flags.output, answer.content);
-                    persistOutputArtifact(projectState?.id, 'swarm-report-file', 'swarm report output', flags.output, { task });
-                    success(`Report saved to ${flags.output}`);
+                    const outputTarget = resolveStructuredOutputTarget({
+                        outputPath: flags.output,
+                        defaultBaseName: 'swarm-report',
+                    });
+                    if (outputTarget.warning) {
+                        warn(outputTarget.warning);
+                    }
+                    if (outputTarget.kind === 'pdf' || outputTarget.kind === 'docx') {
+                        const document = buildAnalysisDocument('Swarm Report', task, answer.content, 'swarm');
+                        const buffer = outputTarget.kind === 'pdf'
+                            ? await renderReportAsPdf(document)
+                            : await renderReportAsDocx(document);
+                        writeFileSync(outputTarget.outputPath, buffer);
+                    }
+                    else {
+                        writeFileSync(outputTarget.outputPath, answer.content);
+                    }
+                    persistOutputArtifact(projectState?.id, 'swarm-report-file', 'swarm report output', outputTarget.outputPath, { task });
+                    success(`Report saved to ${outputTarget.outputPath}`);
                 }
             }
             else {
                 // Single-agent ReAct mode (default)
                 const session = await runAgent(task, config, (step) => {
-                    renderAgentStep(step, flags.json, flags.quiet);
+                    renderAgentStepPlain(step, flags.json, flags.quiet);
                 }, projectState?.context);
                 const answer = session.steps.find((s) => s.type === 'answer');
                 if (projectState) {
@@ -611,12 +988,28 @@ export function registerAgentCommand(program) {
                     console.log(answer.content);
                     console.log('');
                     console.log(chalk.gray(`  (${session.steps.filter((s) => s.type === 'tool_call').length} tools executed, ${session.totalTokens} tokens, ${session.totalLatencyMs}ms)`));
-                    console.log(chalk.cyan('\n  Hint: To continue this session interactively, run: ') + chalk.white(`geotech chat${opts.project ? ` --project ${opts.project}` : ''}`));
+                    console.log(chalk.cyan('\n  Continue interactively with: ') + chalk.white(`geotech chat${opts.project ? ` --project ${opts.project}` : ''}`));
                 }
                 if (flags.output && answer) {
-                    writeFileSync(flags.output, answer.content);
-                    persistOutputArtifact(projectState?.id, 'agent-report-file', 'agent analysis output', flags.output, { task });
-                    success(`Report saved to ${flags.output}`);
+                    const outputTarget = resolveStructuredOutputTarget({
+                        outputPath: flags.output,
+                        defaultBaseName: 'agent-analysis',
+                    });
+                    if (outputTarget.warning) {
+                        warn(outputTarget.warning);
+                    }
+                    if (outputTarget.kind === 'pdf' || outputTarget.kind === 'docx') {
+                        const document = buildAnalysisDocument('Agent Analysis', task, answer.content, 'single');
+                        const buffer = outputTarget.kind === 'pdf'
+                            ? await renderReportAsPdf(document)
+                            : await renderReportAsDocx(document);
+                        writeFileSync(outputTarget.outputPath, buffer);
+                    }
+                    else {
+                        writeFileSync(outputTarget.outputPath, answer.content);
+                    }
+                    persistOutputArtifact(projectState?.id, 'agent-report-file', 'agent analysis output', outputTarget.outputPath, { task });
+                    success(`Report saved to ${outputTarget.outputPath}`);
                 }
             }
             if (!flags.json) {
@@ -624,7 +1017,7 @@ export function registerAgentCommand(program) {
             }
         }
         catch (err) {
-            handleCommandError(err, flags, useSwarm ? 'swarm_failed' : 'agent_failed');
+            handleCommandErrorClean(err, flags, useSwarm ? 'swarm_failed' : 'agent_failed');
         }
     });
     addGlobalFlags(cmd);
@@ -635,12 +1028,12 @@ export function registerAgentCommand(program) {
 // ---------------------------------------------------------------------------
 export function registerChatCommand(program) {
     const cmd = new Command('chat')
-        .description('Interactive agentic session — type natural language, agent executes tools with memory')
+        .description('Interactive agentic session - type natural language, agent executes tools with memory')
         .option('--project <id>', 'Load and persist context to a stored project')
         .action(async (opts) => {
         const { createInterface } = await import('node:readline');
         console.log('');
-        console.log(chalk.bold.cyan('  geotech') + chalk.bold.white('CLI') + chalk.gray(' Agent — Interactive Mode'));
+        console.log(chalk.bold.cyan('  geotech') + chalk.bold.white('CLI') + chalk.gray(' Agent - Interactive Mode'));
         console.log(chalk.gray('  Type engineering questions. The agent will reason and execute calculations.'));
         console.log(chalk.gray('  Commands: /context (show memory), /clear (reset), /exit (quit)'));
         console.log('');
@@ -731,7 +1124,7 @@ export function registerChatCommand(program) {
             console.log('');
             try {
                 const session = await conversation.ask(input, config, (step) => {
-                    renderAgentStep(step, false, false);
+                    renderAgentStepPlain(step, false, false);
                 });
                 if (projectState) {
                     persistSessionToProject(projectState.id, 'chat', input, session);
@@ -762,53 +1155,79 @@ export function registerChatCommand(program) {
 export function registerReportCommand(program) {
     const cmd = new Command('report')
         .description('Generate AI-powered geotechnical report from analysis data')
-        .requiredOption('--data <file>', 'JSON file with analysis results')
+        .option('--data <file>', 'JSON file with analysis results')
+        .option('--from-case-file <scenarioId>', 'Assemble a deterministic report from a stored case file')
+        .option('--project-id <id>', 'Stored project id required with --from-case-file')
         .option('--type <type>', 'Report type: borehole|site-investigation|tunnel-design|foundation|slope|custom', 'site-investigation')
         .option('--project <name>', 'Project name')
         .option('--location <loc>', 'Project location')
         .option('--format <ext>', 'Export format: md|pdf|docx', 'md')
         .action(async (opts) => {
         const flags = getGlobalFlags(opts);
-        if (!(await checkQuota('llmCalls')))
-            return;
-        const spinner = flags.json ? null : ora({ text: 'Generating report...', indent: 2 }).start();
+        const useCaseFile = typeof opts.fromCaseFile === 'string' && opts.fromCaseFile.trim().length > 0;
+        let spinner = null;
         try {
-            const data = JSON.parse(readFileSync(opts.data, 'utf-8'));
-            const config = buildLLMConfig();
-            const report = await generateReport(data, {
-                type: opts.type,
-                projectName: opts.project,
-                location: opts.location,
-            }, config);
-            spinner?.succeed(`Report generated: ${report.sections.length} sections (${report.latencyMs}ms)`);
+            if (!useCaseFile && !opts.data) {
+                throw new Error('Provide either --data <file> or --from-case-file <scenarioId>.');
+            }
+            if (useCaseFile && !opts.projectId) {
+                throw new Error('--project-id is required when using --from-case-file.');
+            }
+            if (!useCaseFile && !(await checkQuota('llmCalls'))) {
+                return;
+            }
+            spinner = startProgress(flags, useCaseFile ? 'Assembling case-file report...' : 'Generating report...');
+            const report = useCaseFile
+                ? await generateReportFromCaseFile({
+                    projectId: opts.projectId,
+                    scenarioId: opts.fromCaseFile,
+                    projectName: opts.project,
+                    location: opts.location,
+                })
+                : await (async () => {
+                    const data = JSON.parse(readFileSync(opts.data, 'utf-8'));
+                    const config = buildLLMConfig();
+                    return generateReport(data, {
+                        type: opts.type,
+                        projectName: opts.project,
+                        location: opts.location,
+                    }, config);
+                })();
+            spinner?.succeed(`${useCaseFile ? 'Case-file report assembled' : 'Report generated'}: ${report.sections.length} sections (${report.latencyMs}ms)`);
             if (flags.json) {
                 renderJSON(report);
                 return;
             }
-            const format = opts.format.toLowerCase();
-            let outputFile = flags.output;
-            if (!outputFile) {
-                const baseName = (opts.project ? opts.project.replace(/\s+/g, '_') : 'report').toLowerCase();
-                outputFile = `${baseName}.${format}`;
+            const baseName = (opts.project
+                ? opts.project.replace(/\s+/g, '_')
+                : useCaseFile
+                    ? `${opts.projectId}_${opts.fromCaseFile}`
+                    : 'report').toLowerCase();
+            const outputTarget = resolveStructuredOutputTarget({
+                outputPath: flags.output,
+                requestedFormat: opts.format,
+                defaultBaseName: baseName,
+            });
+            if (outputTarget.warning) {
+                warn(outputTarget.warning);
             }
-            if (format === 'pdf') {
+            if (outputTarget.kind === 'pdf') {
                 const buf = await renderReportAsPdf(report);
-                writeFileSync(outputFile, buf);
+                writeFileSync(outputTarget.outputPath, buf);
             }
-            else if (format === 'docx') {
+            else if (outputTarget.kind === 'docx') {
                 const buf = await renderReportAsDocx(report);
-                writeFileSync(outputFile, buf);
+                writeFileSync(outputTarget.outputPath, buf);
             }
             else {
-                // Default to markdown
-                writeFileSync(outputFile, report.fullMarkdown);
+                writeFileSync(outputTarget.outputPath, report.fullMarkdown);
             }
-            success(`Report saved to ${outputFile}`);
+            success(`Report saved to ${outputTarget.outputPath}`);
             console.log('');
         }
         catch (err) {
             spinner?.fail('Report generation failed');
-            handleCommandError(err, flags, 'report_generation_failed');
+            handleCommandErrorClean(err, flags, 'report_generation_failed');
         }
     });
     addGlobalFlags(cmd);