voyageai-cli 1.29.0 → 1.30.1

package/src/commands/workflow.js

@@ -188,6 +188,12 @@ function registerWorkflow(program) {
       }
 
       // Execute workflow
+      const telemetry = require('../lib/telemetry');
+      const wfDone = telemetry.timer('cli_workflow_run', {
+        workflowName,
+        stepCount: definition.steps?.length || 0,
+        isBuiltin: !!(definition._source === 'builtin'),
+      });
       try {
         const result = await executeWorkflow(definition, {
           inputs: opts.input,
@@ -224,6 +230,8 @@ function registerWorkflow(program) {
           console.error();
         }
 
+        wfDone();
+
         // Output
         if (opts.json) {
           console.log(JSON.stringify(result.output, null, 2));
@@ -261,6 +269,269 @@ function registerWorkflow(program) {
       }
     });
 
+  // ── workflow check <path> ──
+  wfCmd
+    .command('check <path>')
+    .description('Run validation, security, and quality checks on a workflow package')
+    .option('--security', 'Run security checks only', false)
+    .option('--quality', 'Run quality checks only', false)
+    .option('--all', 'Run all check tiers', false)
+    .option('--json', 'Output machine-readable JSON', false)
+    .option('--ci', 'Output CI-optimized JSON with summary metadata', false)
+    .action((pkgPath, opts) => {
+      const { validateSchemaEnhanced, loadWorkflow } = require('../lib/workflow');
+      const { securityAudit, extractCapabilities } = require('../lib/security-audit');
+      const { qualityAudit } = require('../lib/quality-audit');
+      const fs = require('fs');
+
+      const resolvedPath = path.resolve(pkgPath);
+      const runAll = opts.all || (!opts.security && !opts.quality);
+
+      // Load workflow definition
+      let definition;
+      let pkg = {};
+      let workflowFile;
+
+      try {
+        // Check if it's a directory (package) or a single file
+        const stat = fs.statSync(resolvedPath);
+        if (stat.isDirectory()) {
+          // Package directory
+          const pkgJsonPath = path.join(resolvedPath, 'package.json');
+          if (fs.existsSync(pkgJsonPath)) {
+            pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+          }
+          // Find workflow file
+          workflowFile = pkg.main || 'workflow.json';
+          const wfPath = path.join(resolvedPath, workflowFile);
+          if (fs.existsSync(wfPath)) {
+            definition = JSON.parse(fs.readFileSync(wfPath, 'utf8'));
+          } else {
+            console.error(ui.error(`Workflow file not found: ${wfPath}`));
+            process.exit(1);
+          }
+        } else {
+          // Single file
+          definition = loadWorkflow(resolvedPath);
+        }
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+
+      const results = { schema: [], security: [], quality: [], capabilities: [] };
+
+      // L1: Schema validation (always runs)
+      if (runAll || (!opts.security && !opts.quality)) {
+        results.schema = validateSchemaEnhanced(definition);
+      }
+
+      // L2: Security
+      if (runAll || opts.security) {
+        const packageDir = fs.statSync(resolvedPath).isDirectory() ? resolvedPath : null;
+        results.security = securityAudit(definition, packageDir);
+        results.capabilities = [...extractCapabilities(definition)];
+      }
+
+      // L3: Quality
+      if (runAll || opts.quality) {
+        const packageDir = fs.statSync(resolvedPath).isDirectory() ? resolvedPath : null;
+        results.quality = qualityAudit(definition, pkg, packageDir);
+      }
+
+      // CI output (machine-readable JSON with summary metadata)
+      if (opts.ci) {
+        const criticalCount = results.security.filter(f => f.severity === 'critical').length;
+        const highCount = results.security.filter(f => f.severity === 'high').length;
+        const schemaPass = results.schema.length === 0;
+        const securityPass = criticalCount === 0 && highCount === 0;
+        const qualityPass = results.quality.filter(i => i.level === 'error').length === 0;
+        const ciOutput = {
+          schema: { pass: schemaPass, errors: results.schema },
+          security: { pass: securityPass, findings: results.security },
+          quality: { pass: qualityPass, issues: results.quality },
+          capabilities: results.capabilities,
+          summary: {
+            passAll: schemaPass && securityPass && qualityPass,
+            criticalCount,
+            highCount,
+          },
+        };
+        console.log(JSON.stringify(ciOutput, null, 2));
+        if (criticalCount > 0) process.exit(2);
+        if (highCount > 0) process.exit(1);
+        return;
+      }
+
+      // JSON output
+      if (opts.json) {
+        console.log(JSON.stringify(results, null, 2));
+        // Exit code 1 if critical/high security findings
+        const hasCritical = results.security.some(f => f.severity === 'critical' || f.severity === 'high');
+        if (hasCritical) process.exit(1);
+        return;
+      }
+
+      // Pretty output
+      console.log();
+      console.log(pc.bold(`Workflow Check: ${definition.name || pkgPath}`));
+      console.log(pc.dim('═'.repeat(50)));
+
+      // Schema
+      if (results.schema.length > 0) {
+        console.log();
+        console.log(pc.bold('Schema Validation:'));
+        for (const e of results.schema) {
+          console.log(`  ${pc.red('✗')} ${e}`);
+        }
+      } else if (runAll || (!opts.security && !opts.quality)) {
+        console.log();
+        console.log(`${pc.bold('Schema Validation:')} ${pc.green('✔ passed')}`);
+      }
+
+      // Security
+      if (runAll || opts.security) {
+        console.log();
+        console.log(pc.bold('Security Audit:'));
+        if (results.security.length === 0) {
+          console.log(`  ${pc.green('✔')} No security issues found`);
+        } else {
+          for (const f of results.security) {
+            const color = f.severity === 'critical' ? pc.red :
+                          f.severity === 'high' ? pc.red :
+                          f.severity === 'medium' ? pc.yellow : pc.dim;
+            const icon = f.severity === 'critical' || f.severity === 'high' ? '✗' : '⚠';
+            console.log(`  ${color(icon)} [${f.severity.toUpperCase()}] ${f.message}`);
+          }
+        }
+
+        // Capability flags
+        if (results.capabilities.length > 0) {
+          console.log();
+          console.log(pc.bold('Capabilities:'));
+          const capIcons = { NETWORK: '🌐', WRITE_DB: '💾', LLM: '🤖', LOOP: '🔄', READ_DB: '📊' };
+          for (const cap of results.capabilities) {
+            console.log(`  ${capIcons[cap] || '•'} ${cap}`);
+          }
+        }
+      }
+
+      // Quality
+      if (runAll || opts.quality) {
+        console.log();
+        console.log(pc.bold('Quality Audit:'));
+        if (results.quality.length === 0) {
+          console.log(`  ${pc.green('✔')} No quality issues found`);
+        } else {
+          for (const issue of results.quality) {
+            const color = issue.level === 'error' ? pc.red :
+                          issue.level === 'warning' ? pc.yellow : pc.dim;
+            const icon = issue.level === 'error' ? '✗' : issue.level === 'warning' ? '⚠' : 'ℹ';
+            console.log(`  ${color(icon)} [${issue.level.toUpperCase()}] ${issue.message}`);
+          }
+        }
+      }
+
+      console.log();
+
+      // Exit code 1 if critical/high security findings
+      const hasCritical = results.security.some(f => f.severity === 'critical' || f.severity === 'high');
+      if (hasCritical) process.exit(1);
+    });
+
+  // ── workflow test <path> ──
+  wfCmd
+    .command('test <path>')
+    .description('Run test fixtures for a workflow package')
+    .option('--test <name>', 'Run a specific test case by name')
+    .option('--json', 'Output machine-readable JSON', false)
+    .action(async (pkgPath, opts) => {
+      const { loadWorkflow } = require('../lib/workflow');
+      const { runAllTests, loadTestCases } = require('../lib/workflow-test-runner');
+      const fs = require('fs');
+
+      const resolvedPath = path.resolve(pkgPath);
+
+      // Load workflow definition
+      let definition;
+      try {
+        const stat = fs.statSync(resolvedPath);
+        if (stat.isDirectory()) {
+          const wfPath = path.join(resolvedPath, 'workflow.json');
+          if (fs.existsSync(wfPath)) {
+            definition = JSON.parse(fs.readFileSync(wfPath, 'utf8'));
+          } else {
+            console.error(ui.error(`Workflow file not found: ${wfPath}`));
+            process.exit(1);
+          }
+        } else {
+          console.error(ui.error('Path must be a workflow package directory'));
+          process.exit(1);
+        }
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+
+      // Check for tests directory
+      const testsDir = path.join(resolvedPath, 'tests');
+      if (!fs.existsSync(testsDir)) {
+        console.error(ui.error('No tests/ directory found in package'));
+        process.exit(1);
+      }
+
+      const testCases = loadTestCases(resolvedPath);
+      if (testCases.length === 0) {
+        console.error(ui.error('No *.test.json files found in tests/'));
+        process.exit(1);
+      }
+
+      try {
+        const aggregate = await runAllTests(definition, resolvedPath, {
+          testName: opts.test,
+        });
+
+        if (opts.json) {
+          console.log(JSON.stringify(aggregate, null, 2));
+          if (aggregate.failed > 0) process.exit(1);
+          return;
+        }
+
+        // Pretty output
+        console.log();
+        console.log(pc.bold(`Workflow Tests: ${definition.name || pkgPath}`));
+        console.log(pc.dim('═'.repeat(50)));
+        console.log();
+
+        for (const result of aggregate.results) {
+          const icon = result.passed ? pc.green('✔') : pc.red('✗');
+          console.log(`${icon} ${result.name || result.file}`);
+
+          if (result.error) {
+            console.log(`  ${pc.red(result.error)}`);
+          }
+
+          for (const assertion of result.assertions) {
+            const aIcon = assertion.pass ? pc.green('  ✔') : pc.red('  ✗');
+            console.log(`${aIcon} ${assertion.message}`);
+          }
+
+          for (const err of (result.errors || [])) {
+            console.log(`  ${pc.red('Error:')} ${err}`);
+          }
+        }
+
+        console.log();
+        console.log(`${pc.bold('Summary:')} ${pc.green(`${aggregate.passed} passed`)}, ${aggregate.failed > 0 ? pc.red(`${aggregate.failed} failed`) : `${aggregate.failed} failed`}`);
+        console.log();
+
+        if (aggregate.failed > 0) process.exit(1);
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+    });
+
   // ── workflow validate <file> ──
   wfCmd
     .command('validate <file>')
@@ -404,9 +675,11 @@ function registerWorkflow(program) {
         packageName = WORKFLOW_PREFIX + packageName;
       }
 
+      const telemetry = require('../lib/telemetry');
       console.log(`Installing ${pc.cyan(packageName)}...`);
 
       try {
+        telemetry.send('cli_workflow_install', { packageName });
         const result = installPackage(packageName, { global: opts.global });
         console.log(`${pc.green('✔')} Downloaded ${pc.cyan(packageName)}@${result.version}`);
 
@@ -417,6 +690,17 @@ function registerWorkflow(program) {
             const steps = validation.definition?.steps?.length || 0;
             const tools = (validation.pkg?.vai?.tools || []).join(', ');
             console.log(`${pc.green('✔')} Validated workflow definition (${steps} steps${tools ? `, tools: ${tools}` : ''})`);
+
+            // Display capability flags
+            if (validation.definition) {
+              const { extractCapabilities } = require('../lib/security-audit');
+              const caps = extractCapabilities(validation.definition);
+              if (caps.size > 0) {
+                const capIcons = { NETWORK: '🌐', WRITE_DB: '💾', LLM: '🤖', LOOP: '🔄', READ_DB: '📊' };
+                const capList = [...caps].map(c => `${capIcons[c] || '•'} ${c}`).join('  ');
+                console.log(`${pc.dim('Capabilities:')} ${capList}`);
+              }
+            }
           } else {
             console.log(`${pc.yellow('⚠')} Validation issues:`);
             for (const e of validation.errors) {
@@ -479,11 +763,13 @@ function registerWorkflow(program) {
     .action(async (query, opts) => {
       const { searchNpm } = require('../lib/npm-utils');
 
+      const telemetry = require('../lib/telemetry');
       console.log(`Searching npm for vai-workflow packages matching "${query}"...`);
       console.log();
 
       try {
         const results = await searchNpm(query, { limit: parseInt(opts.limit, 10) });
+        telemetry.send('cli_workflow_search', { query: query.slice(0, 50), resultCount: results.length });
 
         if (opts.json) {
           console.log(JSON.stringify(results, null, 2));

package/src/lib/capability-report.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const CAP_ICONS = {
+  NETWORK: '🌐',
+  WRITE_DB: '💾',
+  LLM: '🤖',
+  LOOP: '🔄',
+  READ_DB: '📊',
+};
+
+const SEVERITY_ICONS = {
+  critical: '🔴',
+  high: '🟠',
+  medium: '🟡',
+  low: '🔵',
+};
+
+/**
+ * Generate a markdown-formatted capability report for a workflow package.
+ *
+ * @param {object} definition - Parsed workflow JSON
+ * @param {Array<{severity: string, message: string, stepId?: string}>} securityFindings
+ * @param {Array<{level: string, message: string}>} qualityIssues
+ * @param {{ total: number, passed: number, failed: number, results?: Array }} [testResults]
+ * @returns {string} Markdown-formatted report
+ */
+function generateCapabilityReport(definition, securityFindings, qualityIssues, testResults) {
+  const lines = [];
+
+  const name = definition?.name || 'Unknown Workflow';
+  lines.push(`## 📋 Workflow Validation Report: ${name}`);
+  lines.push('');
+
+  // ── Capabilities ──
+  const { extractCapabilities } = require('./security-audit');
+  const caps = definition ? [...extractCapabilities(definition)] : [];
+
+  lines.push('### Capabilities');
+  if (caps.length === 0) {
+    lines.push('No special capabilities detected.');
+  } else {
+    for (const cap of caps) {
+      lines.push(`- ${CAP_ICONS[cap] || '•'} **${cap}**`);
+    }
+  }
+  lines.push('');
+
+  // ── Security Findings ──
+  lines.push('### Security Audit');
+  if (!securityFindings || securityFindings.length === 0) {
+    lines.push('✅ No security issues found.');
+  } else {
+    const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const f of securityFindings) {
+      counts[f.severity] = (counts[f.severity] || 0) + 1;
+    }
+    const summary = Object.entries(counts)
+      .filter(([, v]) => v > 0)
+      .map(([k, v]) => `${SEVERITY_ICONS[k]} ${v} ${k.toUpperCase()}`)
+      .join(' | ');
+    lines.push(summary);
+    lines.push('');
+    lines.push('| Severity | Finding | Step |');
+    lines.push('|----------|---------|------|');
+    for (const f of securityFindings) {
+      lines.push(`| ${SEVERITY_ICONS[f.severity]} ${f.severity.toUpperCase()} | ${f.message} | ${f.stepId || '—'} |`);
+    }
+  }
+  lines.push('');
+
+  // ── Quality ──
+  lines.push('### Quality Audit');
+  if (!qualityIssues || qualityIssues.length === 0) {
+    lines.push('✅ No quality issues found.');
+  } else {
+    const errorCount = qualityIssues.filter(i => i.level === 'error').length;
+    const warningCount = qualityIssues.filter(i => i.level === 'warning').length;
+    const suggestionCount = qualityIssues.filter(i => i.level === 'suggestion').length;
+
+    const parts = [];
+    if (errorCount) parts.push(`❌ ${errorCount} error(s)`);
+    if (warningCount) parts.push(`⚠️ ${warningCount} warning(s)`);
+    if (suggestionCount) parts.push(`💡 ${suggestionCount} suggestion(s)`);
+    lines.push(parts.join(' | '));
+    lines.push('');
+
+    for (const issue of qualityIssues) {
+      const icon = issue.level === 'error' ? '❌' : issue.level === 'warning' ? '⚠️' : '💡';
+      lines.push(`- ${icon} **[${issue.level.toUpperCase()}]** ${issue.message}`);
+    }
+  }
+  lines.push('');
+
+  // ── Test Results ──
+  lines.push('### Test Results');
+  if (!testResults) {
+    lines.push('⏭️ No test results available.');
+  } else if (testResults.total === 0) {
+    lines.push('⏭️ No test cases found.');
+  } else {
+    const status = testResults.failed === 0 ? '✅' : '❌';
+    lines.push(`${status} **${testResults.passed}/${testResults.total}** tests passed`);
+    if (testResults.results && testResults.results.length > 0) {
+      lines.push('');
+      for (const r of testResults.results) {
+        const icon = r.passed ? '✅' : '❌';
+        lines.push(`- ${icon} ${r.name || r.file}`);
+      }
+    }
+  }
+  lines.push('');
+
+  // ── Overall Summary ──
+  const criticalCount = (securityFindings || []).filter(f => f.severity === 'critical').length;
+  const highCount = (securityFindings || []).filter(f => f.severity === 'high').length;
+  const qualityErrors = (qualityIssues || []).filter(i => i.level === 'error').length;
+  const testsFailed = testResults ? testResults.failed : 0;
+
+  lines.push('### Summary');
+  if (criticalCount === 0 && highCount === 0 && qualityErrors === 0 && testsFailed === 0) {
+    lines.push('✅ **All checks passed.** This workflow is ready for review.');
+  } else {
+    const issues = [];
+    if (criticalCount) issues.push(`${criticalCount} critical security finding(s)`);
+    if (highCount) issues.push(`${highCount} high security finding(s)`);
+    if (qualityErrors) issues.push(`${qualityErrors} quality error(s)`);
+    if (testsFailed) issues.push(`${testsFailed} test failure(s)`);
+    lines.push(`⚠️ **Issues found:** ${issues.join(', ')}`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { generateCapabilityReport };

package/src/lib/chat.js

@@ -202,9 +202,15 @@ async function* chatTurn({ query, db, collection, llm, history, opts = {} }) {
   // 3. Generate response (streaming)
   let fullResponse = '';
   const stream = opts.stream !== false;
+  let llmUsage = { inputTokens: 0, outputTokens: 0 };
 
   try {
     for await (const chunk of llm.chat(messages, { stream })) {
+      // Check for __usage sentinel (yielded as final item from LLM providers)
+      if (typeof chunk === 'object' && chunk !== null && chunk.__usage) {
+        llmUsage = chunk.__usage;
+        continue;
+      }
       fullResponse += chunk;
       yield { type: 'chunk', data: chunk };
     }
@@ -240,7 +246,13 @@ async function* chatTurn({ query, db, collection, llm, history, opts = {} }) {
       metadata: {
         retrievalTimeMs,
         generationTimeMs,
-        tokens,
+        tokens: {
+          ...tokens,
+          llmInput: llmUsage.inputTokens,
+          llmOutput: llmUsage.outputTokens,
+        },
+        llmModel: llm.model,
+        llmProvider: llm.name,
         contextDocsUsed: docs.length,
       },
     },
@@ -284,11 +296,18 @@ async function* agentChatTurn({ query, llm, history, opts = {} }) {
   // Track messages for the tool-calling loop (mutable copy)
   const messages = [...initialMessages];
   const toolCallLog = [];
+  const totalLlmUsage = { inputTokens: 0, outputTokens: 0 };
 
   // 3. Agent loop
   for (let iteration = 0; iteration < maxIterations; iteration++) {
     const response = await llm.chatWithTools(messages, tools);
 
+    // Accumulate LLM usage from each chatWithTools call
+    if (response.usage) {
+      totalLlmUsage.inputTokens += response.usage.inputTokens || 0;
+      totalLlmUsage.outputTokens += response.usage.outputTokens || 0;
+    }
+
     // Text response: done
     if (response.type === 'text') {
       const fullResponse = response.content;
@@ -321,6 +340,12 @@ async function* agentChatTurn({ query, llm, history, opts = {} }) {
             iterationCount: iteration + 1,
             toolCallCount: toolCallLog.length,
             totalTimeMs,
+            tokens: {
+              llmInput: totalLlmUsage.inputTokens,
+              llmOutput: totalLlmUsage.outputTokens,
+            },
+            llmModel: llm.model,
+            llmProvider: llm.name,
           },
         },
       };
@@ -406,6 +431,12 @@ async function* agentChatTurn({ query, llm, history, opts = {} }) {
         toolCallCount: toolCallLog.length,
         totalTimeMs: Date.now() - start,
         maxIterationsReached: true,
+        tokens: {
+          llmInput: totalLlmUsage.inputTokens,
+          llmOutput: totalLlmUsage.outputTokens,
+        },
+        llmModel: llm.model,
+        llmProvider: llm.name,
       },
     },
   };

package/src/lib/config.js

@@ -18,6 +18,8 @@ const KEY_MAP = {
   'llm-api-key': 'llmApiKey',
   'llm-model': 'llmModel',
   'llm-base-url': 'llmBaseUrl',
+  'show-cost': 'show-cost',
+  'telemetry': 'telemetry',
 };
 
 // Keys whose values should be masked in output

package/src/lib/cost-display.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const { MODEL_CATALOG } = require('./catalog');
+const { getConfigValue } = require('./config');
+const ui = require('./ui');
+
+const COMPETITOR_PRICE = 0.13; // OpenAI text-embedding-3-large per 1M tokens
+const LARGE_PRICE = 0.12;     // voyage-4-large per 1M tokens
+
+/**
+ * Show a one-line cost summary after a CLI operation.
+ * Only displays when `show-cost` config is enabled.
+ * Respects --json and --quiet flags.
+ *
+ * @param {string} model - Model name used
+ * @param {number} tokens - Total tokens consumed
+ * @param {object} [opts] - Command options
+ * @param {boolean} [opts.json] - JSON output mode (suppress cost)
+ * @param {boolean} [opts.quiet] - Quiet mode (suppress cost)
+ */
+function showCostSummary(model, tokens, opts = {}) {
+  if (opts.json || opts.quiet) return;
+  if (!isEnabled()) return;
+  if (!tokens || tokens <= 0) return;
+
+  const entry = MODEL_CATALOG.find(m => m.name === model);
+  const price = entry?.pricePerMToken ?? LARGE_PRICE;
+  const cost = (tokens / 1_000_000) * price;
+  const largeCost = (tokens / 1_000_000) * LARGE_PRICE;
+
+  const costStr = formatCost(cost);
+  const tokStr = tokens.toLocaleString();
+
+  console.log();
+  console.log(ui.dim(`  💰 ${costStr} (${tokStr} tokens, ${model})`));
+
+  if (price < LARGE_PRICE) {
+    const savingsPercent = Math.round((1 - price / LARGE_PRICE) * 100);
+    const largeStr = formatCost(largeCost);
+    console.log(ui.dim(`     Symmetric (voyage-4-large): ${largeStr} — ${savingsPercent}% savings`));
+  }
+}
+
+/**
+ * Show a combined cost summary for operations with multiple API calls
+ * (e.g., query with embed + rerank).
+ *
+ * @param {Array<{model: string, tokens: number, label?: string}>} operations
+ * @param {object} [opts]
+ */
+function showCombinedCostSummary(operations, opts = {}) {
+  if (opts.json || opts.quiet) return;
+  if (!isEnabled()) return;
+
+  let totalCost = 0;
+  let totalLargeCost = 0;
+  let totalTokens = 0;
+
+  for (const op of operations) {
+    if (!op.tokens || op.tokens <= 0) continue;
+    const entry = MODEL_CATALOG.find(m => m.name === op.model);
+    const price = entry?.pricePerMToken ?? LARGE_PRICE;
+    totalCost += (op.tokens / 1_000_000) * price;
+    totalLargeCost += (op.tokens / 1_000_000) * LARGE_PRICE;
+    totalTokens += op.tokens;
+  }
+
+  if (totalTokens <= 0) return;
+
+  console.log();
+  console.log(ui.dim(`  💰 ${formatCost(totalCost)} total (${totalTokens.toLocaleString()} tokens)`));
+  for (const op of operations) {
+    if (!op.tokens || op.tokens <= 0) continue;
+    const entry = MODEL_CATALOG.find(m => m.name === op.model);
+    const price = entry?.pricePerMToken ?? LARGE_PRICE;
+    const cost = (op.tokens / 1_000_000) * price;
+    const label = op.label || op.model;
+    console.log(ui.dim(`     ${label}: ${formatCost(cost)} (${op.tokens.toLocaleString()} tokens)`));
+  }
+
+  if (totalCost < totalLargeCost) {
+    const savingsPercent = Math.round((1 - totalCost / totalLargeCost) * 100);
+    console.log(ui.dim(`     Symmetric (all voyage-4-large): ${formatCost(totalLargeCost)} — ${savingsPercent}% savings`));
+  }
+}
+
+/**
+ * Check if cost display is enabled via config.
+ * @returns {boolean}
+ */
+function isEnabled() {
+  const val = getConfigValue('show-cost');
+  return val === true || val === 'true';
+}
+
+/**
+ * Format a cost value for display.
+ * @param {number} cost
+ * @returns {string}
+ */
+function formatCost(cost) {
+  if (cost < 0.000001) return '$0.000000';
+  if (cost < 0.01) return `$${cost.toFixed(6)}`;
+  return `$${cost.toFixed(4)}`;
+}
+
+module.exports = { showCostSummary, showCombinedCostSummary, isEnabled, formatCost };

package/src/lib/explanations.js

@@ -589,9 +589,15 @@ const concepts = {
       ``,
       `${pc.bold('Validate it yourself:')} Use ${pc.cyan('vai benchmark space')} to embed identical text`,
       `with all Voyage 4 models and see the cross-model cosine similarities.`,
+      ``,
+      `${pc.bold('Interactive proof:')} Try the ${pc.cyan('Shared Space Explorer')} at`,
+      `${pc.cyan('vaicli.com/shared-space')} — embed text with all three models simultaneously`,
+      `and see 0.95+ cross-model similarity in a live 3×3 matrix, scatter plot, and`,
+      `cost comparison. Share your results directly to LinkedIn.`,
     ].join('\n'),
     links: [
       'https://blog.voyageai.com/2026/01/15/voyage-4-model-family/',
+      'https://vaicli.com/shared-space',
     ],
     tryIt: [
       'vai benchmark space',