geotechcli 0.4.0 → 0.4.2

package/dist/commands/ai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/commands/ai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+WpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyN5D;AAMD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwChE;AAMD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgDzD;AAkGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8K3D;AAMD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0I1D;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4F5D"}
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../../src/commands/ai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6lBpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4Q5D;AAMD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwChE;AAMD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgDzD;AAkGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8K3D;AAMD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0I1D;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuF5D"}

package/dist/commands/ai.js

@@ -1,11 +1,10 @@
 import { Command } from 'commander';
 import { readFileSync, writeFileSync } from 'node:fs';
-import ora from 'ora';
 import chalk from 'chalk';
 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 } from '../ui/terminal.js';
+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, resolveStructuredOutputTarget, HOSTED_BETA_REQUEST_SAFE_BYTES, } from '../util/vision-output.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
@@ -40,8 +39,8 @@ function describeVisionInput(file) {
     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 PDFs, export a single page to PNG/JPG first, or split the PDF into smaller files.'));
-    console.log(chalk.gray('    The CLI will block oversized PDFs before upload to avoid the hosted-beta body limit.'));
+    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) {
@@ -84,6 +83,200 @@ function formatMaybe(value, suffix = '') {
         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***');
 }
@@ -122,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);
@@ -249,13 +447,13 @@ 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 file = readVisionInput(imagePath);
             describeVisionInput(file);
@@ -273,7 +471,7 @@ export function registerVisionCommand(program) {
                 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));
@@ -288,20 +486,20 @@ 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 file = readVisionInput(imagePath);
             describeVisionInput(file);
@@ -319,7 +517,7 @@ export function registerVisionCommand(program) {
                 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'));
@@ -341,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);
@@ -354,7 +552,7 @@ 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 file = readVisionInput(imagePath);
             describeVisionInput(file);
@@ -371,8 +569,8 @@ export function registerVisionCommand(program) {
                 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('');
@@ -388,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);
@@ -402,25 +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 file = readVisionInput(filePath);
             describeVisionInput(file);
             const config = buildLLMConfig();
-            maybeCheckHostedBetaVisionPayload(config, file, {
+            const requestDetails = {
                 prompt: 'Extract structured borehole log data.',
                 systemPrompt: 'You are analyzing a geotechnical image.',
                 temperature: 0.1,
                 maxTokens: 900,
-            });
-            const result = await interpretBoreholeLog(file.base64, file.mimeType, config, opts.boreholeId);
-            spinner?.succeed(`Extraction complete: ${result.layers.length} layers (${result.latencyMs}ms)`);
+            };
+            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) => [
@@ -441,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);
@@ -460,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);
@@ -471,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'));
@@ -485,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);
@@ -506,7 +742,7 @@ 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 file = readVisionInput(opts.doc);
             describeVisionInput(file);
@@ -531,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);
@@ -630,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);
@@ -643,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('');
         }
@@ -660,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) {
@@ -695,7 +931,7 @@ 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) {
                     const outputTarget = resolveStructuredOutputTarget({
@@ -722,7 +958,7 @@ export function registerAgentCommand(program) {
             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) {
@@ -752,7 +988,7 @@ 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) {
                     const outputTarget = resolveStructuredOutputTarget({
@@ -781,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);
@@ -792,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('');
@@ -888,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);
@@ -940,12 +1176,7 @@ export function registerReportCommand(program) {
             if (!useCaseFile && !(await checkQuota('llmCalls'))) {
                 return;
             }
-            spinner = flags.json
-                ? null
-                : ora({
-                    text: useCaseFile ? 'Assembling case-file report...' : 'Generating report...',
-                    indent: 2,
-                }).start();
+            spinner = startProgress(flags, useCaseFile ? 'Assembling case-file report...' : 'Generating report...');
             const report = useCaseFile
                 ? await generateReportFromCaseFile({
                     projectId: opts.projectId,
@@ -996,7 +1227,7 @@ export function registerReportCommand(program) {
         }
         catch (err) {
             spinner?.fail('Report generation failed');
-            handleCommandError(err, flags, 'report_generation_failed');
+            handleCommandErrorClean(err, flags, 'report_generation_failed');
         }
     });
     addGlobalFlags(cmd);