voyageai-cli 1.30.3 → 1.30.6

package/README.md

@@ -512,6 +512,26 @@ echo "your-key" | vai config set api-key --stdin
 vai config set mongodb-uri "mongodb+srv://..."
 ```
 
+#### All Config Keys
+
+| CLI Key | Description | Example |
+|---------|-------------|---------|
+| `api-key` | Voyage AI API key | `vai config set api-key pa-...` |
+| `mongodb-uri` | MongoDB Atlas connection string | `vai config set mongodb-uri "mongodb+srv://..."` |
+| `base-url` | Override API endpoint (Atlas AI or Voyage) | `vai config set base-url https://ai.mongodb.com/v1` |
+| `default-model` | Default embedding model | `vai config set default-model voyage-3` |
+| `default-dimensions` | Default output dimensions | `vai config set default-dimensions 512` |
+| `default-db` | Default MongoDB database for workflows/commands | `vai config set default-db my_knowledge_base` |
+| `default-collection` | Default MongoDB collection for workflows/commands | `vai config set default-collection documents` |
+| `llm-provider` | LLM provider for chat/generate (`anthropic`, `openai`, `ollama`) | `vai config set llm-provider anthropic` |
+| `llm-api-key` | LLM provider API key | `vai config set llm-api-key sk-...` |
+| `llm-model` | LLM model override | `vai config set llm-model claude-sonnet-4-5-20250929` |
+| `llm-base-url` | LLM endpoint override (e.g. for Ollama) | `vai config set llm-base-url http://localhost:11434` |
+| `show-cost` | Show cost estimates after operations | `vai config set show-cost true` |
+| `telemetry` | Enable/disable anonymous usage telemetry | `vai config set telemetry false` |
+
+Config is stored in `~/.vai/config.json`. Use `vai config get` to see all values (secrets are masked) or `vai config get <key>` for a specific value. The desktop app's Settings → Database page also reads and writes this file.
+
 ### Shell Completions
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.30.3",
+  "version": "1.30.6",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"
@@ -34,7 +34,8 @@
     "url": "https://github.com/mrlynn/voyageai-cli/issues"
   },
   "scripts": {
-    "test": "node --test test/**/*.test.js"
+    "test": "node --test test/**/*.test.js",
+    "release": "./scripts/release.sh"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/commands/app.js

@@ -57,8 +57,8 @@ function registerApp(program) {
     .action(async (opts) => {
       // --version: print version and exit
       if (opts.version) {
-        const pkg = require(path.join(__dirname, '..', '..', 'package.json'));
-        console.log(`voyageai-cli v${pkg.version}`);
+        const { getVersion } = require('../lib/banner');
+        console.log(`voyageai-cli v${getVersion()}`);
         return;
       }
 

package/src/commands/bug.js

@@ -8,7 +8,8 @@ const { send: sendTelemetry } = require('../lib/telemetry');
 // Try to get package version safely
 function getVersion() {
   try {
-    return require('../../package.json').version;
+    const { getVersion: _getVersion } = require('../lib/banner');
+    return _getVersion();
   } catch {
     return 'unknown';
   }

package/src/commands/chat.js

@@ -735,8 +735,7 @@ async function cleanup(mongo) {
 
 function getVersion() {
   try {
-    const pkg = require('../../package.json');
-    return pkg.version;
+    return require('../lib/banner').getVersion();
   } catch {
     return '0.0.0';
   }

package/src/commands/eval.js

@@ -18,7 +18,7 @@ function saveResults(filePath, results) {
   const output = {
     ...results,
     savedAt: new Date().toISOString(),
-    vaiVersion: require('../../package.json').version,
+    vaiVersion: require('../lib/banner').getVersion(),
   };
   fs.writeFileSync(filePath, JSON.stringify(output, null, 2), 'utf8');
 }
@@ -945,7 +945,7 @@ function registerEvalCompare(evalCmd) {
             kValues,
             configs: results,
             comparedAt: new Date().toISOString(),
-            vaiVersion: require('../../package.json').version,
+            vaiVersion: require('../lib/banner').getVersion(),
           };
           fs.writeFileSync(opts.save, JSON.stringify(output, null, 2), 'utf8');
           if (verbose) {

package/src/commands/playground.js

@@ -465,9 +465,9 @@ function createPlaygroundServer() {
 
       // API: Version — return CLI package version
       if (req.method === 'GET' && req.url === '/api/version') {
-        const pkg = require('../../package.json');
+        const { getVersion } = require('../lib/banner');
         res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ version: pkg.version }));
+        res.end(JSON.stringify({ version: getVersion() }));
         return;
       }
 
@@ -541,6 +541,87 @@ function createPlaygroundServer() {
         return;
       }
 
+      // API: Settings — read/write ~/.vai/config.json
+      if (req.method === 'GET' && req.url === '/api/settings') {
+        const { loadConfig, KEY_MAP, SECRET_KEYS, maskSecret } = require('../lib/config');
+        const config = loadConfig();
+
+        // Build response: CLI key name → masked/raw value, for every known key
+        const reverseMap = {};
+        for (const [cliKey, internalKey] of Object.entries(KEY_MAP)) {
+          reverseMap[internalKey] = cliKey;
+        }
+
+        const settings = {};
+        for (const [internalKey, cliKey] of Object.entries(reverseMap)) {
+          const value = config[internalKey];
+          settings[cliKey] = {
+            value: value != null ? (SECRET_KEYS.has(internalKey) ? maskSecret(value) : value) : null,
+            isSet: value != null,
+            isSecret: SECRET_KEYS.has(internalKey),
+            internalKey,
+          };
+        }
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(settings));
+        return;
+      }
+
+      if (req.method === 'PUT' && req.url === '/api/settings') {
+        const { loadConfig, saveConfig, KEY_MAP, SECRET_KEYS } = require('../lib/config');
+        const body = await readBody(req);
+        let updates;
+        try {
+          updates = JSON.parse(body);
+        } catch {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Invalid JSON' }));
+          return;
+        }
+
+        const config = loadConfig();
+        const applied = [];
+
+        for (const [cliKey, value] of Object.entries(updates)) {
+          const internalKey = KEY_MAP[cliKey];
+          if (!internalKey) {
+            continue; // Skip unknown keys
+          }
+          // Don't overwrite secrets with masked values
+          if (SECRET_KEYS.has(internalKey) && typeof value === 'string' && value.includes('...')) {
+            continue;
+          }
+          if (value === null || value === '') {
+            delete config[internalKey];
+          } else {
+            config[internalKey] = value;
+          }
+          applied.push(cliKey);
+        }
+
+        saveConfig(config);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ applied, message: `Updated ${applied.length} setting(s)` }));
+        return;
+      }
+
+      // API: Settings reveal — return unmasked value for a specific secret key
+      if (req.method === 'GET' && req.url.startsWith('/api/settings/reveal/')) {
+        const { loadConfig, KEY_MAP, SECRET_KEYS } = require('../lib/config');
+        const cliKey = req.url.replace('/api/settings/reveal/', '');
+        const internalKey = KEY_MAP[cliKey];
+        if (!internalKey || !SECRET_KEYS.has(internalKey)) {
+          res.writeHead(404, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Not found or not a secret key' }));
+          return;
+        }
+        const config = loadConfig();
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ value: config[internalKey] || null }));
+        return;
+      }
+
       // API: Settings origins — where each config value comes from
       if (req.method === 'GET' && req.url === '/api/settings/origins') {
         const { resolveLLMConfig } = require('../lib/llm');
@@ -561,8 +642,8 @@ function createPlaygroundServer() {
           provider: resolveOrigin('VAI_LLM_PROVIDER', 'llmProvider', chatConf.provider),
           model: resolveOrigin('VAI_LLM_MODEL', 'llmModel', chatConf.model),
           llmApiKey: resolveOrigin('VAI_LLM_API_KEY', 'llmApiKey'),
-          db: proj.db ? 'project' : 'default',
-          collection: proj.collection ? 'project' : 'default',
+          db: resolveOrigin(null, 'defaultDb', proj.db),
+          collection: resolveOrigin(null, 'defaultCollection', proj.collection),
         };
 
         res.writeHead(200, { 'Content-Type': 'application/json' });

package/src/commands/workflow.js

@@ -529,6 +529,36 @@ function registerWorkflow(program) {
       }
     });
 
+  // ── workflow integration-test ──
+  wfCmd
+    .command('integration-test')
+    .description('Run live integration tests against use-case domain datasets')
+    .option('--domain <slug>', 'Test only a specific domain (devdocs, healthcare, finance, legal)')
+    .option('--workflow <name>', 'Test only a specific workflow')
+    .option('--no-seed', 'Skip seeding (assumes data already exists)')
+    .option('--teardown', 'Drop test collections after running')
+    .option('--sample-docs <path>', 'Override base path for sample documents')
+    .option('--json', 'Output machine-readable JSON', false)
+    .action(async (opts) => {
+      // Delegate to the integration test runner
+      const { execFileSync } = require('child_process');
+      const runnerPath = path.join(__dirname, '../../test/integration/run.js');
+      const args = [];
+      if (opts.domain) args.push('--domain', opts.domain);
+      if (opts.workflow) args.push('--workflow', opts.workflow);
+      if (opts.seed === false) args.push('--no-seed');
+      if (opts.teardown) args.push('--teardown');
+      if (opts.sampleDocs) args.push('--sample-docs', opts.sampleDocs);
+      if (opts.json) args.push('--json');
+
+      try {
+        execFileSync(process.execPath, [runnerPath, ...args], { stdio: 'inherit' });
+      } catch (err) {
+        if (err.status) process.exit(err.status);
+        throw err;
+      }
+    });
+
   // ── workflow validate <file> ──
   wfCmd
     .command('validate <file>')

package/src/lib/banner.js

@@ -7,8 +7,19 @@ const pc = require('picocolors');
  * @returns {string}
  */
 function getVersion() {
-  const pkg = require('../../package.json');
-  return pkg.version || '0.0.0';
+  const path = require('path');
+  // Walk up from this file to find package.json — works both in dev and packaged Electron
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    try {
+      const pkg = require(path.join(dir, 'package.json'));
+      if (pkg.version) return pkg.version;
+    } catch (_) { /* keep looking */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return '0.0.0';
 }
 
 /**

package/src/lib/codegen.js

@@ -322,7 +322,6 @@ function buildContext(project, options = {}) {
     // Metadata
     generatedAt: new Date().toISOString(),
     vaiVersion: getCliVersion(),
-    vaiVersion: require('../../package.json').version,
   };
 
   return context;

package/src/lib/config.js

@@ -18,7 +18,9 @@ const KEY_MAP = {
   'llm-api-key': 'llmApiKey',
   'llm-model': 'llmModel',
   'llm-base-url': 'llmBaseUrl',
-  'show-cost': 'show-cost',
+  'default-db': 'defaultDb',
+  'default-collection': 'defaultCollection',
+  'show-cost': 'showCost',
   'telemetry': 'telemetry',
 };
 

package/src/lib/cost-display.js

@@ -89,7 +89,7 @@ function showCombinedCostSummary(operations, opts = {}) {
  * @returns {boolean}
  */
 function isEnabled() {
-  const val = getConfigValue('show-cost');
+  const val = getConfigValue('showCost') || getConfigValue('show-cost');
   return val === true || val === 'true';
 }
 

package/src/lib/export/formats/json-export.js

@@ -1,7 +1,7 @@
 'use strict';
 
-const path = require('path');
-const pkg = require(path.resolve(__dirname, '..', '..', '..', '..', 'package.json'));
+const { getVersion } = require('../../../lib/banner');
+const pkg = { version: getVersion() };
 
 /**
  * Render normalized data as JSON.

package/src/lib/integration-test-runner.js

@@ -0,0 +1,459 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { executeWorkflow } = require('./workflow');
+
+/**
+ * Domain-to-workflow mapping. Each entry defines which workflows are compatible
+ * with a given use-case domain, and how to map domain data into workflow inputs.
+ */
+const WORKFLOW_DOMAIN_MAP = {
+  'rag-chat': {
+    inputMapper: (domain, query) => ({
+      question: query.query,
+      collection: domain.collectionName,
+      collection2: '',
+      limit: 10,
+      min_score: 0.3,
+      system_prompt: 'You are a helpful assistant. Answer based on provided context. Cite sources.',
+      chat_history: '',
+    }),
+    assertions: ['noErrors', 'stepsCompleted', 'nonEmptyOutput'],
+  },
+  'search-with-fallback': {
+    inputMapper: (domain, query) => ({
+      query: query.query,
+      primary_collection: domain.collectionName,
+      fallback_collection: domain.collectionName, // same collection for testing
+    }),
+    assertions: ['noErrors', 'stepsCompleted'],
+  },
+  'research-and-summarize': {
+    inputMapper: (domain, query) => ({
+      question: query.query,
+      limit: 5,
+    }),
+    assertions: ['noErrors', 'stepsCompleted'],
+  },
+  'multi-collection-search': {
+    inputMapper: (domain, query) => ({
+      query: query.query,
+      collection1: domain.collectionName,
+      collection2: domain.collectionName,
+      limit: 5,
+    }),
+    assertions: ['noErrors', 'stepsCompleted'],
+  },
+  'consistency-check': {
+    inputMapper: (domain, _query) => ({
+      topic: domain.title,
+      collection1: domain.collectionName,
+      collection2: domain.collectionName,
+    }),
+    assertions: ['noErrors'],
+  },
+  'cost-analysis': {
+    inputMapper: (domain, _query) => ({
+      docs: 100,
+      queries: 500,
+      months: 1,
+    }),
+    assertions: ['noErrors', 'stepsCompleted'],
+  },
+  'smart-ingest': {
+    inputMapper: (domain, _query, sampleDocPath) => {
+      // Use first sample doc content if available
+      let text = 'This is a test document for integration testing.';
+      if (sampleDocPath) {
+        const docs = fs.readdirSync(sampleDocPath).filter(f => f.endsWith('.md'));
+        if (docs.length > 0) {
+          text = fs.readFileSync(path.join(sampleDocPath, docs[0]), 'utf8').slice(0, 2000);
+        }
+      }
+      return {
+        text,
+        source: 'integration-test',
+        threshold: 0.95,
+      };
+    },
+    assertions: ['noErrors'],
+  },
+};
+
+/**
+ * Load a use-case domain dataset.
+ *
+ * @param {string} domainDataPath - Path to the use-case .ts/.json data file or parsed object
+ * @returns {object} Parsed domain data with sampleDocs, exampleQueries, etc.
+ */
+function loadDomainData(domainData) {
+  if (typeof domainData === 'object') return domainData;
+  const raw = fs.readFileSync(domainData, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Seed a test collection by ingesting sample documents.
+ *
+ * @param {object} options
+ * @param {string} options.sampleDocsPath - Path to folder of sample .md files
+ * @param {string} options.dbName - Target database
+ * @param {string} options.collectionName - Target collection
+ * @param {string} [options.model] - Voyage model to use
+ * @returns {Promise<{ docCount: number, collection: string }>}
+ */
+async function seedCollection({ sampleDocsPath, dbName, collectionName, model }) {
+  const { connectAndClose } = require('./mongo');
+
+  // Check if collection already has documents (skip re-seeding)
+  const existingCount = await connectAndClose(dbName, collectionName, async (col) => {
+    return col.countDocuments();
+  });
+
+  if (existingCount > 0) {
+    return { docCount: existingCount, collection: collectionName, seeded: false };
+  }
+
+  // Read all .md files from sample docs
+  const files = fs.readdirSync(sampleDocsPath).filter(f => f.endsWith('.md'));
+  if (files.length === 0) {
+    throw new Error(`No .md files found in ${sampleDocsPath}`);
+  }
+
+  const documents = files.map(f => ({
+    text: fs.readFileSync(path.join(sampleDocsPath, f), 'utf8'),
+    source: f,
+    metadata: { filename: f },
+  }));
+
+  // Chunk and embed
+  const { chunk } = require('./chunker');
+  const { generateEmbeddings } = require('./api');
+
+  const allChunks = [];
+  for (const doc of documents) {
+    const chunks = chunk(doc.text, { strategy: 'recursive', chunkSize: 512, chunkOverlap: 50 });
+    for (const c of chunks) {
+      allChunks.push({
+        text: c.text || c,
+        source: doc.source,
+        metadata: doc.metadata,
+      });
+    }
+  }
+
+  // Embed in batches
+  const batchSize = 128;
+  const allEmbeddings = [];
+  for (let i = 0; i < allChunks.length; i += batchSize) {
+    const batch = allChunks.slice(i, i + batchSize);
+    const texts = batch.map(c => c.text);
+    const resp = await generateEmbeddings(texts, {
+      model: model || 'voyage-3-lite',
+      inputType: 'document',
+    });
+    allEmbeddings.push(...resp.data.map(d => d.embedding));
+  }
+
+  // Insert into MongoDB
+  const docsToInsert = allChunks.map((c, i) => ({
+    text: c.text,
+    source: c.source,
+    metadata: c.metadata,
+    embedding: allEmbeddings[i],
+  }));
+
+  await connectAndClose(dbName, collectionName, async (col) => {
+    await col.insertMany(docsToInsert);
+
+    // Create vector search index if it doesn't exist
+    try {
+      const indexes = await col.listSearchIndexes().toArray();
+      const hasIndex = indexes.some(idx => idx.name === 'vector_index');
+      if (!hasIndex) {
+        await col.createSearchIndex({
+          name: 'vector_index',
+          type: 'vectorSearch',
+          definition: {
+            fields: [{
+              type: 'vector',
+              path: 'embedding',
+              numDimensions: allEmbeddings[0].length,
+              similarity: 'cosine',
+            }],
+          },
+        });
+      }
+    } catch {
+      // May not be available on non-Atlas deployments
+    }
+  });
+
+  return { docCount: docsToInsert.length, collection: collectionName, seeded: true };
+}
+
+/**
+ * Check if a vector search index exists and is ready.
+ * Optionally waits for it to become ready.
+ *
+ * @param {string} dbName
+ * @param {string} collectionName
+ * @param {object} [options]
+ * @param {string} [options.indexName='vector_index']
+ * @param {boolean} [options.wait=false] - Wait for index to become ready
+ * @param {number} [options.timeoutMs=120000] - Max wait time
+ * @param {function} [options.onProgress] - Progress callback
+ * @returns {Promise<boolean>}
+ */
+async function checkVectorIndex(dbName, collectionName, options = {}) {
+  const { indexName = 'vector_index', wait = false, timeoutMs = 120000, onProgress = () => {} } = options;
+  const { getMongoCollection } = require('./mongo');
+
+  const deadline = Date.now() + timeoutMs;
+
+  while (true) {
+    const { client, collection } = await getMongoCollection(dbName, collectionName);
+    try {
+      const indexes = await collection.listSearchIndexes().toArray();
+      const idx = indexes.find(i => i.name === indexName);
+      if (idx && idx.status === 'READY') return true;
+      if (!wait || Date.now() >= deadline) return false;
+      const status = idx ? idx.status : 'NOT_FOUND';
+      onProgress({ phase: 'index', message: `Index status: ${status}, waiting...` });
+    } catch {
+      if (!wait || Date.now() >= deadline) return false;
+    } finally {
+      await client.close();
+    }
+    // Wait 5 seconds before checking again
+    await new Promise(r => setTimeout(r, 5000));
+  }
+}
+
+/**
+ * Run integration tests for a domain against compatible workflows.
+ *
+ * @param {object} options
+ * @param {object} options.domain - Domain data (from use-case data files)
+ * @param {string} options.sampleDocsPath - Path to sample doc files
+ * @param {string} options.workflowsDir - Path to workflow JSON definitions
+ * @param {string[]} [options.workflows] - Specific workflow names to test (default: all compatible)
+ * @param {boolean} [options.seed] - Whether to seed data first (default: true)
+ * @param {boolean} [options.teardown] - Whether to drop test collections after (default: false)
+ * @param {function} [options.onProgress] - Progress callback
+ * @returns {Promise<IntegrationTestResults>}
+ */
+async function runIntegrationTests(options) {
+  const {
+    domain,
+    sampleDocsPath,
+    workflowsDir,
+    workflows: requestedWorkflows,
+    seed = true,
+    teardown = false,
+    onProgress = () => {},
+  } = options;
+
+  const testCollectionName = `vai_test_${domain.slug || domain.collectionName}`;
+  const testDomain = { ...domain, collectionName: testCollectionName };
+  const results = {
+    domain: domain.slug || domain.title,
+    collection: testCollectionName,
+    seed: null,
+    indexReady: false,
+    workflows: [],
+    summary: { total: 0, passed: 0, failed: 0, skipped: 0 },
+  };
+
+  // Step 1: Seed
+  if (seed && sampleDocsPath) {
+    onProgress({ phase: 'seed', message: `Seeding ${testCollectionName}...` });
+    try {
+      results.seed = await seedCollection({
+        sampleDocsPath,
+        dbName: domain.dbName || 'vai_integration_test',
+        collectionName: testCollectionName,
+        model: domain.voyageModel,
+      });
+      onProgress({ phase: 'seed', message: `Seeded ${results.seed.docCount} chunks` });
+    } catch (err) {
+      results.seed = { error: err.message };
+      onProgress({ phase: 'seed', message: `Seed failed: ${err.message}` });
+      // Can't continue without data for most workflows
+    }
+  }
+
+  // Step 2: Check vector index (wait up to 2 minutes for it to become ready)
+  onProgress({ phase: 'index', message: 'Checking vector search index...' });
+  results.indexReady = await checkVectorIndex(
+    domain.dbName || 'vai_integration_test',
+    testCollectionName,
+    { wait: true, timeoutMs: 120000, onProgress }
+  );
+  if (!results.indexReady) {
+    onProgress({ phase: 'index', message: 'WARNING: Vector index not ready — query-based workflows may fail' });
+  } else {
+    onProgress({ phase: 'index', message: 'Vector index ready' });
+  }
+
+  // Step 3: Run workflows
+  const availableWorkflows = fs.readdirSync(workflowsDir)
+    .filter(f => f.endsWith('.json'))
+    .map(f => f.replace('.json', ''));
+
+  const workflowsToTest = requestedWorkflows
+    ? requestedWorkflows.filter(w => availableWorkflows.includes(w) && WORKFLOW_DOMAIN_MAP[w])
+    : availableWorkflows.filter(w => WORKFLOW_DOMAIN_MAP[w]);
+
+  const queries = domain.exampleQueries || [];
+  if (queries.length === 0) {
+    queries.push({ query: domain.title, explanation: 'Fallback query from domain title' });
+  }
+
+  for (const wfName of workflowsToTest) {
+    const mapping = WORKFLOW_DOMAIN_MAP[wfName];
+    if (!mapping) {
+      results.workflows.push({ name: wfName, status: 'skipped', reason: 'No domain mapping' });
+      results.summary.skipped++;
+      results.summary.total++;
+      continue;
+    }
+
+    const wfPath = path.join(workflowsDir, `${wfName}.json`);
+    const definition = JSON.parse(fs.readFileSync(wfPath, 'utf8'));
+
+    // Test with first example query
+    const testQuery = queries[0];
+    const inputs = mapping.inputMapper(testDomain, testQuery, sampleDocsPath);
+
+    onProgress({ phase: 'workflow', message: `Running ${wfName} with query: "${testQuery.query}"` });
+
+    const wfResult = {
+      name: wfName,
+      query: testQuery.query,
+      inputs,
+      status: 'passed',
+      steps: [],
+      assertions: [],
+      errors: [],
+      durationMs: 0,
+    };
+
+    const start = Date.now();
+    try {
+      // Inject db and embedding model into workflow defaults so query/rerank
+      // steps use the same model the documents were embedded with
+      const testDefinition = {
+        ...definition,
+        defaults: {
+          ...(definition.defaults || {}),
+          db: domain.dbName || 'vai_integration_test',
+          model: domain.voyageModel,
+        },
+      };
+      const result = await executeWorkflow(testDefinition, {
+        inputs,
+        db: domain.dbName || 'vai_integration_test',
+      });
+      wfResult.durationMs = Date.now() - start;
+      wfResult.steps = (result.steps || []).map(s => ({
+        id: s.id,
+        tool: s.tool,
+        skipped: s.skipped || false,
+        error: s.error || null,
+        durationMs: s.durationMs,
+      }));
+
+      // Run assertions
+      if (mapping.assertions.includes('noErrors')) {
+        const errorSteps = (result.steps || []).filter(s => s.error);
+        if (errorSteps.length > 0) {
+          wfResult.assertions.push({
+            pass: false,
+            name: 'noErrors',
+            message: `${errorSteps.length} step(s) errored: ${errorSteps.map(s => `${s.id}: ${s.error}`).join('; ')}`,
+          });
+          wfResult.status = 'failed';
+        } else {
+          wfResult.assertions.push({ pass: true, name: 'noErrors', message: 'All steps error-free' });
+        }
+      }
+
+      if (mapping.assertions.includes('stepsCompleted')) {
+        const completedSteps = (result.steps || []).filter(s => !s.skipped && !s.error);
+        if (completedSteps.length === 0) {
+          wfResult.assertions.push({ pass: false, name: 'stepsCompleted', message: 'No steps completed' });
+          wfResult.status = 'failed';
+        } else {
+          wfResult.assertions.push({ pass: true, name: 'stepsCompleted', message: `${completedSteps.length} steps completed` });
+        }
+      }
+
+      if (mapping.assertions.includes('nonEmptyOutput')) {
+        const output = result.output || {};
+        const hasContent = Object.values(output).some(v =>
+          v && (typeof v === 'string' ? v.length > 0 : Array.isArray(v) ? v.length > 0 : true)
+        );
+        if (!hasContent) {
+          wfResult.assertions.push({ pass: false, name: 'nonEmptyOutput', message: 'Output is empty' });
+          wfResult.status = 'failed';
+        } else {
+          wfResult.assertions.push({ pass: true, name: 'nonEmptyOutput', message: 'Output has content' });
+        }
+      }
+
+      // Check expected sources if the query has sampleResults
+      if (testQuery.sampleResults && testQuery.sampleResults.length > 0 && result.output) {
+        const outputStr = JSON.stringify(result.output).toLowerCase();
+        const expectedSource = testQuery.sampleResults[0].source.toLowerCase();
+        const baseName = expectedSource.replace('.md', '');
+        const found = outputStr.includes(expectedSource) || outputStr.includes(baseName);
+        wfResult.assertions.push({
+          pass: found,
+          name: 'expectedSource',
+          message: found
+            ? `Found expected source: ${testQuery.sampleResults[0].source}`
+            : `Expected source "${testQuery.sampleResults[0].source}" not found in output (sources: ${
+                (result.output.sources || []).map(s => s.source || s.filename || 'unknown').join(', ') || 'none'
+              })`,
+        });
+        // Source matching is a soft signal — don't fail the whole test, just warn
+        if (!found) wfResult.assertions[wfResult.assertions.length - 1].warn = true;
+      }
+
+    } catch (err) {
+      wfResult.durationMs = Date.now() - start;
+      wfResult.status = 'failed';
+      wfResult.errors.push(err.message);
+    }
+
+    results.workflows.push(wfResult);
+    results.summary.total++;
+    if (wfResult.status === 'passed') results.summary.passed++;
+    else if (wfResult.status === 'failed') results.summary.failed++;
+    else results.summary.skipped++;
+  }
+
+  // Step 4: Teardown
+  if (teardown) {
+    onProgress({ phase: 'teardown', message: `Dropping ${testCollectionName}...` });
+    try {
+      const { connectAndClose } = require('./mongo');
+      await connectAndClose(domain.dbName || 'vai_integration_test', testCollectionName, async (col) => {
+        await col.drop();
+      });
+    } catch (err) {
+      onProgress({ phase: 'teardown', message: `Teardown failed: ${err.message}` });
+    }
+  }
+
+  return results;
+}
+
+module.exports = {
+  WORKFLOW_DOMAIN_MAP,
+  seedCollection,
+  checkVectorIndex,
+  runIntegrationTests,
+};

package/src/lib/workflow-registry.js

@@ -149,7 +149,8 @@ function validatePackage(packagePath, pkg) {
 
     if (pkg.vai.minVaiVersion) {
       try {
-        const { version: currentVersion } = require('../../package.json');
+        const { getVersion } = require('./banner');
+        const currentVersion = getVersion();
         if (compareVersions(pkg.vai.minVaiVersion, currentVersion) > 0) {
           warnings.push(`Requires vai >= ${pkg.vai.minVaiVersion} (you have ${currentVersion})`);
         }

package/src/lib/workflow.js

@@ -1161,6 +1161,19 @@ async function executeHttp(inputs) {
   };
 }
 
+/**
+ * Resolve db and collection from inputs → defaults → project → vai config.
+ */
+function resolveDbAndCollection(inputs, defaults) {
+  const { loadProject } = require('./project');
+  const { getConfigValue } = require('./config');
+  const { config: proj } = loadProject();
+  return {
+    db: inputs.db || defaults.db || proj.db || process.env.VAI_DEFAULT_DB || getConfigValue('defaultDb'),
+    collection: inputs.collection || defaults.collection || proj.collection || process.env.VAI_DEFAULT_COLLECTION || getConfigValue('defaultCollection'),
+  };
+}
+
 /**
  * Execute a MongoDB aggregation pipeline step.
  *
@@ -1170,11 +1183,8 @@ async function executeHttp(inputs) {
  */
 async function executeAggregate(inputs, defaults) {
   const { getMongoCollection } = require('./mongo');
-  const { loadProject } = require('./project');
-  const { config: proj } = loadProject();
 
-  const db = inputs.db || defaults.db || proj.db;
-  const collection = inputs.collection || defaults.collection || proj.collection;
+  const { db, collection } = resolveDbAndCollection(inputs, defaults);
   const pipeline = inputs.pipeline;
   const allowWrites = inputs.allowWrites || false;
 
@@ -1217,11 +1227,8 @@ async function executeAggregate(inputs, defaults) {
 async function executeQuery(inputs, defaults) {
   const { generateEmbeddings, apiRequest } = require('./api');
   const { getMongoCollection } = require('./mongo');
-  const { loadProject } = require('./project');
-  const { config: proj } = loadProject();
 
-  const db = inputs.db || defaults.db || proj.db;
-  const collection = inputs.collection || defaults.collection || proj.collection;
+  const { db, collection } = resolveDbAndCollection(inputs, defaults);
   const model = inputs.model || defaults.model;
   const query = inputs.query;
   const limit = inputs.limit || 10;
@@ -1381,11 +1388,8 @@ async function executeIngest(inputs, defaults) {
   const { generateEmbeddings } = require('./api');
   const { getMongoCollection } = require('./mongo');
   const { chunk } = require('./chunker');
-  const { loadProject } = require('./project');
-  const { config: proj } = loadProject();
 
-  const db = inputs.db || defaults.db || proj.db;
-  const collection = inputs.collection || defaults.collection || proj.collection;
+  const { db, collection } = resolveDbAndCollection(inputs, defaults);
   const text = inputs.text;
   const source = inputs.source || 'workflow-ingest';
   const model = inputs.model || defaults.model;
@@ -1464,10 +1468,8 @@ async function executeIngest(inputs, defaults) {
  */
 async function executeCollections(inputs, defaults) {
   const { introspectCollections } = require('./workflow-utils');
-  const { loadProject } = require('./project');
-  const { config: proj } = loadProject();
 
-  const db = inputs.db || defaults.db || proj.db;
+  const { db } = resolveDbAndCollection(inputs, defaults);
   if (!db) throw new Error('collections: database not specified');
 
   const collections = await introspectCollections(db);

package/src/mcp/server.js

@@ -12,7 +12,8 @@ const { registerWorkspaceTools } = require('./tools/workspace');
 const { registerCodeSearchTools } = require('./tools/code-search');
 const { registerAuthoringTools } = require('./tools/authoring');
 
-const VERSION = require('../../package.json').version;
+const { getVersion } = require('../lib/banner');
+const VERSION = getVersion();
 
 /**
  * Create and configure the MCP server with all tools registered.

package/src/mcp/tools/management.js

@@ -11,7 +11,8 @@ const { introspectCollections } = require('../../lib/workflow-utils');
  */
 async function handleVaiCollections(input) {
   const { config: proj } = loadProject();
-  const dbName = input.db || proj.db;
+  const { getConfigValue } = require('../../lib/config');
+  const dbName = input.db || proj.db || process.env.VAI_DEFAULT_DB || getConfigValue('defaultDb');
   if (!dbName) throw new Error('No database specified. Pass db parameter or configure via vai init.');
 
   const collections = await introspectCollections(dbName);

package/src/playground/index.html

@@ -7915,6 +7915,10 @@ Reranking models rescore initial search results to improve relevance ordering.</
         <svg width="16" height="16" viewBox="0 0 24 24"><use href="#lg-config"/></svg>
         <span>General</span>
       </button>
+      <button class="settings-nav-item" data-settings-section="database">
+        <svg width="16" height="16" viewBox="0 0 24 24"><use href="#lg-database"/></svg>
+        <span>Database</span>
+      </button>
       <button class="settings-nav-item" data-settings-section="appearance">
         <svg width="16" height="16" viewBox="0 0 24 24"><use href="#lg-palette"/></svg>
         <span>Appearance</span>
@@ -8018,6 +8022,47 @@ Reranking models rescore initial search results to improve relevance ordering.</
         </div>
       </div>
 
+      <!-- ── Database ── -->
+      <div class="settings-panel" id="settings-database">
+        <div class="settings-panel-header">
+          <h3 class="settings-panel-title">Database</h3>
+          <p class="settings-panel-subtitle">MongoDB Atlas connection and default targets</p>
+        </div>
+        <div class="settings-section">
+          <div class="settings-row">
+            <div class="settings-label">
+              <span class="settings-label-text">MongoDB URI <span class="settings-origin" data-origin-key="mongodbUri"></span></span>
+              <span class="settings-label-hint">Connection string for MongoDB Atlas · <a href="https://cloud.mongodb.com" target="_blank" class="settings-key-link"><svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="vertical-align:-1px;margin-right:2px;"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"/><polyline points="15 3 21 3 21 9"/><line x1="10" y1="14" x2="21" y2="3"/></svg>Atlas Console</a></span>
+            </div>
+            <div class="settings-control" style="min-width:260px;">
+              <div class="settings-api-field">
+                <input type="password" id="settingsMongoUri" placeholder="mongodb+srv://user:pass@cluster.mongodb.net/" autocomplete="off" spellcheck="false">
+                <button type="button" id="settingsMongoUriToggle" title="Show/hide"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0"/><circle cx="12" cy="12" r="3"/></svg></button>
+                <button type="button" id="settingsMongoUriSave" class="save-btn" title="Save">Save</button>
+              </div>
+            </div>
+          </div>
+          <div class="settings-row">
+            <div class="settings-label">
+              <span class="settings-label-text">Default Database <span class="settings-origin" data-origin-key="db"></span></span>
+              <span class="settings-label-hint">Used by workflows and commands when no database is specified</span>
+            </div>
+            <div class="settings-control">
+              <input type="text" class="settings-input" id="settingsDefaultDb" placeholder="e.g. my_knowledge_base">
+            </div>
+          </div>
+          <div class="settings-row">
+            <div class="settings-label">
+              <span class="settings-label-text">Default Collection <span class="settings-origin" data-origin-key="collection"></span></span>
+              <span class="settings-label-hint">Used by workflows and commands when no collection is specified</span>
+            </div>
+            <div class="settings-control">
+              <input type="text" class="settings-input" id="settingsDefaultCollection" placeholder="e.g. documents">
+            </div>
+          </div>
+        </div>
+      </div>
+
       <!-- ── Appearance ── -->
       <div class="settings-panel" id="settings-appearance">
         <div class="settings-panel-header">
@@ -11845,6 +11890,100 @@ function initSettings() {
     });
   }
 
+  // ── Database settings (read/write ~/.vai/config.json via /api/settings) ──
+  const dbSettingsFields = {
+    'settingsMongoUri': 'mongodb-uri',
+    'settingsDefaultDb': 'default-db',
+    'settingsDefaultCollection': 'default-collection',
+  };
+
+  // Load current values from ~/.vai/config.json
+  fetch('/api/settings').then(r => r.json()).then(settings => {
+    for (const [elemId, cliKey] of Object.entries(dbSettingsFields)) {
+      const el = document.getElementById(elemId);
+      if (el && settings[cliKey] && settings[cliKey].isSet) {
+        // Don't populate masked secret values into editable fields
+        if (settings[cliKey].isSecret) {
+          el.value = settings[cliKey].value || '';
+          el.dataset.isMasked = 'true';
+        } else {
+          el.value = settings[cliKey].value || '';
+        }
+      }
+    }
+  }).catch(() => {});
+
+  // Save non-secret fields on change (default-db, default-collection)
+  ['settingsDefaultDb', 'settingsDefaultCollection'].forEach(elemId => {
+    const el = document.getElementById(elemId);
+    if (el) {
+      let debounce;
+      el.addEventListener('input', () => {
+        clearTimeout(debounce);
+        debounce = setTimeout(() => {
+          const cliKey = dbSettingsFields[elemId];
+          fetch('/api/settings', {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ [cliKey]: el.value || null }),
+          }).then(() => flashSaved()).catch(() => {});
+        }, 600);
+      });
+    }
+  });
+
+  // MongoDB URI — save button (secret field, same pattern as API key)
+  const mongoUriInput = document.getElementById('settingsMongoUri');
+  const mongoUriToggle = document.getElementById('settingsMongoUriToggle');
+  const mongoUriSave = document.getElementById('settingsMongoUriSave');
+  if (mongoUriInput && mongoUriSave) {
+    let mongoUriVisible = false;
+    if (mongoUriToggle) {
+      mongoUriToggle.addEventListener('click', async () => {
+        if (!mongoUriVisible) {
+          // Fetch the real unmasked value
+          try {
+            const resp = await fetch('/api/settings/reveal/mongodb-uri');
+            const data = await resp.json();
+            if (data.value) {
+              mongoUriInput.value = data.value;
+              delete mongoUriInput.dataset.isMasked;
+            }
+          } catch {}
+          mongoUriInput.type = 'text';
+          mongoUriVisible = true;
+        } else {
+          mongoUriInput.type = 'password';
+          mongoUriVisible = false;
+        }
+      });
+    }
+    mongoUriSave.addEventListener('click', () => {
+      // Don't save masked values back
+      if (mongoUriInput.dataset.isMasked === 'true') return;
+      const val = mongoUriInput.value.trim();
+      fetch('/api/settings', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ 'mongodb-uri': val || null }),
+      }).then(() => {
+        flashSaved();
+        if (val) {
+          mongoUriInput.value = '';
+          mongoUriInput.type = 'password';
+          mongoUriVisible = false;
+          mongoUriInput.placeholder = val.slice(0, 20) + '...';
+        }
+      }).catch(() => {});
+    });
+    mongoUriInput.addEventListener('input', () => {
+      delete mongoUriInput.dataset.isMasked;
+    });
+    mongoUriInput.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') mongoUriSave.click();
+    });
+  }
+
   // Set up settings sub-navigation
   setupSettingsNav();