voyageai-cli 1.29.0 → 1.30.0

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',

package/src/lib/llm.js

@@ -147,15 +147,24 @@ class AnthropicProvider {
       const json = await res.json();
       const text = json.content?.[0]?.text || '';
       yield text;
+      // Yield usage sentinel
+      const usage = json.usage || {};
+      yield { __usage: { inputTokens: usage.input_tokens || 0, outputTokens: usage.output_tokens || 0 } };
       return;
     }
 
-    yield* parseSSE(res.body, (event, data) => {
-      if (event === 'content_block_delta' && data.delta?.text) {
-        return data.delta.text;
+    // Manual SSE loop to capture usage from streaming events
+    const usage = { inputTokens: 0, outputTokens: 0 };
+    for await (const chunk of parseSSEWithMeta(res.body)) {
+      if (chunk.__event === 'message_start' && chunk.__data?.message?.usage) {
+        usage.inputTokens = chunk.__data.message.usage.input_tokens || 0;
+      } else if (chunk.__event === 'message_delta' && chunk.__data?.usage) {
+        usage.outputTokens = chunk.__data.usage.output_tokens || 0;
+      } else if (chunk.__event === 'content_block_delta' && chunk.__data?.delta?.text) {
+        yield chunk.__data.delta.text;
       }
-      return null;
-    });
+    }
+    yield { __usage: usage };
   }
 
   /**
@@ -163,7 +172,7 @@ class AnthropicProvider {
    * @param {Array} messages - Conversation messages
    * @param {Array} tools - Tool definitions in Anthropic format
    * @param {object} [options]
-   * @returns {Promise<{type: 'text'|'tool_calls', content?: string, calls?: Array, stopReason: string}>}
+   * @returns {Promise<{type: 'text'|'tool_calls', content?: string, calls?: Array, stopReason: string, usage: object}>}
    */
   async chatWithTools(messages, tools, options = {}) {
     const model = options.model || this.model;
@@ -200,6 +209,8 @@ class AnthropicProvider {
 
     const json = await res.json();
     const stopReason = json.stop_reason || 'end_turn';
+    const apiUsage = json.usage || {};
+    const usage = { inputTokens: apiUsage.input_tokens || 0, outputTokens: apiUsage.output_tokens || 0 };
 
     // Check for tool_use blocks
     const toolBlocks = (json.content || []).filter(b => b.type === 'tool_use');
@@ -212,6 +223,7 @@ class AnthropicProvider {
           arguments: b.input,
         })),
         stopReason,
+        usage,
         _raw: json.content,
       };
     }
@@ -222,6 +234,7 @@ class AnthropicProvider {
       type: 'text',
       content: textBlocks.map(b => b.text).join(''),
       stopReason,
+      usage,
     };
   }
 
@@ -324,6 +337,11 @@ class OpenAIProvider {
       messages,
     };
 
+    // Request usage data in streaming mode
+    if (stream) {
+      body.stream_options = { include_usage: true };
+    }
+
     const res = await fetch(`${this.baseUrl}/v1/chat/completions`, {
       method: 'POST',
       headers: {
@@ -342,14 +360,25 @@ class OpenAIProvider {
       const json = await res.json();
       const text = json.choices?.[0]?.message?.content || '';
       yield text;
+      const apiUsage = json.usage || {};
+      yield { __usage: { inputTokens: apiUsage.prompt_tokens || 0, outputTokens: apiUsage.completion_tokens || 0 } };
       return;
     }
 
-    yield* parseSSE(res.body, (_event, data) => {
-      if (data === '[DONE]') return null;
-      const content = data.choices?.[0]?.delta?.content;
-      return content || null;
-    });
+    // Manual SSE loop to capture usage from final streaming chunk
+    const usage = { inputTokens: 0, outputTokens: 0 };
+    for await (const chunk of parseSSEWithMeta(res.body)) {
+      const data = chunk.__data;
+      if (data === '[DONE]') continue;
+      // Final chunk with usage stats (stream_options: include_usage)
+      if (data?.usage) {
+        usage.inputTokens = data.usage.prompt_tokens || 0;
+        usage.outputTokens = data.usage.completion_tokens || 0;
+      }
+      const content = data?.choices?.[0]?.delta?.content;
+      if (content) yield content;
+    }
+    yield { __usage: usage };
   }
 
   /**
@@ -357,7 +386,7 @@ class OpenAIProvider {
    * @param {Array} messages - Conversation messages
    * @param {Array} tools - Tool definitions in OpenAI format
    * @param {object} [options]
-   * @returns {Promise<{type: 'text'|'tool_calls', content?: string, calls?: Array, stopReason: string}>}
+   * @returns {Promise<{type: 'text'|'tool_calls', content?: string, calls?: Array, stopReason: string, usage: object}>}
    */
   async chatWithTools(messages, tools, options = {}) {
     const model = options.model || this.model;
@@ -389,6 +418,8 @@ class OpenAIProvider {
     const choice = json.choices?.[0] || {};
     const msg = choice.message || {};
     const stopReason = choice.finish_reason || 'stop';
+    const apiUsage = json.usage || {};
+    const usage = { inputTokens: apiUsage.prompt_tokens || 0, outputTokens: apiUsage.completion_tokens || 0 };
 
     if (msg.tool_calls && msg.tool_calls.length > 0) {
       return {
@@ -401,6 +432,7 @@ class OpenAIProvider {
             : tc.function.arguments,
         })),
         stopReason,
+        usage,
         _raw: msg,
       };
     }
@@ -409,6 +441,7 @@ class OpenAIProvider {
       type: 'text',
       content: msg.content || '',
       stopReason,
+      usage,
     };
   }
 
@@ -502,14 +535,25 @@ class OllamaProvider {
       const json = await res.json();
       const text = json.choices?.[0]?.message?.content || '';
       yield text;
+      // Ollama may not return usage, default to 0
+      const apiUsage = json.usage || {};
+      yield { __usage: { inputTokens: apiUsage.prompt_tokens || 0, outputTokens: apiUsage.completion_tokens || 0 } };
       return;
     }
 
-    yield* parseSSE(res.body, (_event, data) => {
-      if (data === '[DONE]') return null;
-      const content = data.choices?.[0]?.delta?.content;
-      return content || null;
-    });
+    // Manual SSE loop (Ollama may not support stream_options)
+    const usage = { inputTokens: 0, outputTokens: 0 };
+    for await (const chunk of parseSSEWithMeta(res.body)) {
+      const data = chunk.__data;
+      if (data === '[DONE]') continue;
+      if (data?.usage) {
+        usage.inputTokens = data.usage.prompt_tokens || 0;
+        usage.outputTokens = data.usage.completion_tokens || 0;
+      }
+      const content = data?.choices?.[0]?.delta?.content;
+      if (content) yield content;
+    }
+    yield { __usage: usage };
   }
 
   /**
@@ -517,7 +561,7 @@ class OllamaProvider {
    * @param {Array} messages - Conversation messages
    * @param {Array} tools - Tool definitions in OpenAI format
    * @param {object} [options]
-   * @returns {Promise<{type: 'text'|'tool_calls', content?: string, calls?: Array, stopReason: string}>}
+   * @returns {Promise<{type: 'text'|'tool_calls', content?: string, calls?: Array, stopReason: string, usage: object}>}
    */
   async chatWithTools(messages, tools, options = {}) {
     const model = options.model || this.model;
@@ -544,6 +588,9 @@ class OllamaProvider {
     const choice = json.choices?.[0] || {};
     const msg = choice.message || {};
     const stopReason = choice.finish_reason || 'stop';
+    // Ollama may not return usage, default to 0
+    const apiUsage = json.usage || {};
+    const usage = { inputTokens: apiUsage.prompt_tokens || 0, outputTokens: apiUsage.completion_tokens || 0 };
 
     if (msg.tool_calls && msg.tool_calls.length > 0) {
       return {
@@ -556,6 +603,7 @@ class OllamaProvider {
             : tc.function.arguments,
         })),
         stopReason,
+        usage,
         _raw: msg,
       };
     }
@@ -564,6 +612,7 @@ class OllamaProvider {
       type: 'text',
       content: msg.content || '',
       stopReason,
+      usage,
     };
   }
 
@@ -622,6 +671,64 @@ class OllamaProvider {
 // SSE Stream Parser
 // ============================================
 
+/**
+ * Parse a Server-Sent Events stream, yielding raw event+data pairs.
+ * Unlike parseSSE, this preserves event types and full data objects
+ * so callers can extract both content and metadata (e.g. usage stats).
+ *
+ * @param {ReadableStream} body - Response body stream
+ * @yields {{ __event: string|null, __data: object|string }} Parsed SSE events
+ */
+async function* parseSSEWithMeta(body) {
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let currentEvent = null;
+
+  for await (const chunk of body) {
+    buffer += decoder.decode(chunk, { stream: true });
+
+    const lines = buffer.split('\n');
+    buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      if (line.startsWith('event: ')) {
+        currentEvent = line.slice(7).trim();
+        continue;
+      }
+
+      if (line.startsWith('data: ')) {
+        const rawData = line.slice(6);
+
+        if (rawData === '[DONE]') {
+          yield { __event: currentEvent, __data: '[DONE]' };
+          return;
+        }
+
+        let parsed;
+        try {
+          parsed = JSON.parse(rawData);
+        } catch {
+          continue;
+        }
+
+        yield { __event: currentEvent, __data: parsed };
+        currentEvent = null;
+      }
+    }
+  }
+
+  // Process remaining buffer
+  if (buffer.trim() && buffer.startsWith('data: ')) {
+    const rawData = buffer.slice(6);
+    if (rawData !== '[DONE]') {
+      try {
+        const parsed = JSON.parse(rawData);
+        yield { __event: currentEvent, __data: parsed };
+      } catch { /* skip */ }
+    }
+  }
+}
+
 /**
  * Parse a Server-Sent Events stream.
  * @param {ReadableStream} body - Response body stream

package/src/lib/quality-audit.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CATEGORIES = ['retrieval', 'analysis', 'ingestion', 'domain-specific', 'utility', 'integration'];
+
+/**
+ * Run quality audit on a workflow definition and its package.
+ * @param {object} definition - Parsed workflow JSON
+ * @param {object} pkg - Parsed package.json
+ * @param {string} [packagePath] - Path to the package directory
+ * @returns {Array<{level: string, message: string}>}
+ */
+function qualityAudit(definition, pkg, packagePath) {
+  const issues = [];
+
+  // Package metadata checks
+  if (!pkg.description || pkg.description.length < 20) {
+    issues.push({ level: 'error', message: 'Package description too short (min 20 chars)' });
+  }
+  if (!pkg.author) {
+    issues.push({ level: 'error', message: 'Package must have an author' });
+  }
+  if (!pkg.license) {
+    issues.push({ level: 'warning', message: 'No license specified' });
+  }
+  if (!pkg.vai?.category || !CATEGORIES.includes(pkg.vai.category)) {
+    issues.push({ level: 'error', message: 'Invalid or missing vai.category' });
+  }
+
+  // README checks
+  if (packagePath) {
+    const readmePath = path.join(packagePath, 'README.md');
+    if (!fs.existsSync(readmePath)) {
+      issues.push({ level: 'error', message: 'Missing README.md' });
+    } else {
+      const readme = fs.readFileSync(readmePath, 'utf8');
+      if (readme.length < 200) {
+        issues.push({ level: 'warning', message: 'README is very short (< 200 chars)' });
+      }
+      if (!readme.includes('## Usage') && !readme.includes('## Install')) {
+        issues.push({ level: 'warning', message: 'README should include Usage or Install section' });
+      }
+      if (readme.includes('TODO')) {
+        issues.push({ level: 'warning', message: 'README contains TODO placeholders' });
+      }
+    }
+  }
+
+  // Workflow definition quality
+  if (definition && Array.isArray(definition.steps)) {
+    if (definition.steps.length === 1) {
+      issues.push({ level: 'suggestion', message: 'Single-step workflows may not warrant a package — consider documenting as a CLI example instead' });
+    }
+  }
+
+  // Branding
+  if (!definition?.branding?.icon) {
+    issues.push({ level: 'suggestion', message: 'Consider adding branding.icon for store display' });
+  }
+
+  // Naming — should be descriptive, not generic
+  if (definition?.name && /^(test|my|workflow|demo|example)/i.test(definition.name)) {
+    issues.push({ level: 'warning', message: `Workflow name "${definition.name}" is too generic` });
+  }
+
+  return issues;
+}
+
+module.exports = { qualityAudit, CATEGORIES };