voyageai-cli 1.9.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"

package/src/cli.js

@@ -20,6 +20,7 @@ const { registerIngest } = require('./commands/ingest');
 const { registerCompletions } = require('./commands/completions');
 const { registerPlayground } = require('./commands/playground');
 const { registerBenchmark } = require('./commands/benchmark');
+const { registerAbout } = require('./commands/about');
 const { showBanner, showQuickStart, getVersion } = require('./lib/banner');
 
 const version = getVersion();
@@ -44,6 +45,7 @@ registerIngest(program);
 registerCompletions(program);
 registerPlayground(program);
 registerBenchmark(program);
+registerAbout(program);
 
 // Append disclaimer to all help output
 program.addHelpText('after', `

package/src/commands/about.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const pc = require('picocolors');
+
+/**
+ * Register the about command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerAbout(program) {
+  program
+    .command('about')
+    .description('About this tool and its author')
+    .option('--json', 'Machine-readable JSON output')
+    .action((opts) => {
+      if (opts.json) {
+        console.log(JSON.stringify({
+          tool: 'voyageai-cli',
+          binary: 'vai',
+          author: {
+            name: 'Michael Lynn',
+            role: 'Principal Staff Developer Advocate, MongoDB',
+            github: 'https://github.com/mrlynn',
+            website: 'https://mlynn.org',
+          },
+          links: {
+            npm: 'https://www.npmjs.com/package/voyageai-cli',
+            github: 'https://github.com/mrlynn/voyageai-cli',
+            docs: 'https://www.mongodb.com/docs/voyageai/',
+          },
+          disclaimer: 'Community tool — not an official MongoDB or Voyage AI product.',
+        }, null, 2));
+        return;
+      }
+
+      console.log('');
+      console.log(`  ${pc.bold(pc.cyan('voyageai-cli'))} ${pc.dim('(vai)')}`);
+      console.log(`  ${pc.dim('Voyage AI embeddings, reranking & Atlas Vector Search CLI')}`);
+      console.log('');
+
+      // Author
+      console.log(`  ${pc.bold('Author')}`);
+      console.log(`  Michael Lynn`);
+      console.log(`  ${pc.dim('Principal Staff Developer Advocate · MongoDB')}`);
+      console.log(`  ${pc.dim('25+ years enterprise infrastructure · 10+ years at MongoDB')}`);
+      console.log('');
+
+      // About
+      console.log(`  ${pc.bold('About This Project')}`);
+      console.log(`  A community-built CLI for working with Voyage AI embeddings,`);
+      console.log(`  reranking, and MongoDB Atlas Vector Search. Created to help`);
+      console.log(`  developers explore, benchmark, and integrate Voyage AI models`);
+      console.log(`  into their applications — right from the terminal.`);
+      console.log('');
+
+      // Features
+      console.log(`  ${pc.bold('What You Can Do')}`);
+      console.log(`  ${pc.cyan('vai embed')}        Generate vector embeddings for text`);
+      console.log(`  ${pc.cyan('vai similarity')}   Compare texts with cosine similarity`);
+      console.log(`  ${pc.cyan('vai rerank')}       Rerank documents against a query`);
+      console.log(`  ${pc.cyan('vai search')}       Vector search against Atlas collections`);
+      console.log(`  ${pc.cyan('vai store')}        Embed and store documents in Atlas`);
+      console.log(`  ${pc.cyan('vai benchmark')}    Compare model latency, ranking & costs`);
+      console.log(`  ${pc.cyan('vai explain')}      Learn about embeddings, vector search & more`);
+      console.log(`  ${pc.cyan('vai playground')}   Launch interactive web playground`);
+      console.log('');
+
+      // Links
+      console.log(`  ${pc.bold('Links')}`);
+      console.log(`  ${pc.dim('npm:')}     https://www.npmjs.com/package/voyageai-cli`);
+      console.log(`  ${pc.dim('GitHub:')}  https://github.com/mrlynn/voyageai-cli`);
+      console.log(`  ${pc.dim('Docs:')}    https://www.mongodb.com/docs/voyageai/`);
+      console.log(`  ${pc.dim('Author:')}  https://mlynn.org`);
+      console.log('');
+
+      // Disclaimer
+      console.log(`  ${pc.yellow('⚠ Community Tool Disclaimer')}`);
+      console.log(`  ${pc.dim('This tool is not an official product of MongoDB, Inc. or')}`);
+      console.log(`  ${pc.dim('Voyage AI. It is independently built and maintained by')}`);
+      console.log(`  ${pc.dim('Michael Lynn as a community resource. Not supported,')}`);
+      console.log(`  ${pc.dim('endorsed, or guaranteed by either company.')}`);
+      console.log('');
+    });
+}
+
+module.exports = { registerAbout };

package/src/commands/benchmark.js

@@ -21,6 +21,8 @@ const SAMPLE_TEXTS = [
   'GraphQL provides a flexible query language that lets clients request exactly the data they need.',
 ];
 
+// If you're reading this, you're either benchmarking or procrastinating.
+// Either way, we respect the hustle.
 const SAMPLE_QUERY = 'How do I search for similar documents using embeddings?';
 
 const SAMPLE_RERANK_DOCS = [

package/src/commands/playground.js

@@ -90,6 +90,28 @@ function createPlaygroundServer() {
         return;
       }
 
+      // API: Concepts (from vai explain)
+      if (req.method === 'GET' && req.url === '/api/concepts') {
+        const { concepts } = require('../lib/explanations');
+        // Strip picocolors ANSI from content for web display
+        // eslint-disable-next-line no-control-regex
+        const ANSI_RE = /\x1b\[[0-9;]*m/g;
+        const stripped = {};
+        for (const [key, concept] of Object.entries(concepts)) {
+          stripped[key] = {
+            title: concept.title,
+            summary: concept.summary,
+            content: (typeof concept.content === 'string' ? concept.content : concept.content).replace(ANSI_RE, ''),
+            links: concept.links || [],
+            tryIt: concept.tryIt || [],
+            keyPoints: concept.keyPoints || [],
+          };
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ concepts: stripped }));
+        return;
+      }
+
       // API: Config
       if (req.method === 'GET' && req.url === '/api/config') {
         const key = process.env.VOYAGE_API_KEY || getConfigValue('apiKey');

package/src/commands/store.js

@@ -170,6 +170,8 @@ async function handleBatchStore(opts) {
 
     const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
     client = c;
+    // insertMany: because life's too short for one document at a time.
+    // This is the MongoDB equivalent of "I'll have what everyone's having."
     const result = await collection.insertMany(docs);
 
     if (spin) spin.stop();

package/src/lib/api.js

@@ -78,6 +78,8 @@ async function apiRequest(endpoint, body) {
       body: JSON.stringify(body),
     });
 
+    // 429: The API said "slow down monkey" — respect the rate limit
+    // like you'd respect a $merge that's already running on your replica set.
     if (response.status === 429 && attempt < MAX_RETRIES) {
       const retryAfter = response.headers.get('Retry-After');
       const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.pow(2, attempt) * 1000;

package/src/lib/catalog.js

@@ -22,6 +22,8 @@ function getDefaultDimensions() {
   return getConfigValue('defaultDimensions') || DEFAULT_DIMENSIONS;
 }
 
+// The model catalog: like a wine list (I don't drink :-P), except every choice
+// leads to vectors instead of regret.
 /** @type {Array<{name: string, type: string, context: string, dimensions: string, price: string, bestFor: string}>} */
 const MODEL_CATALOG = [
   { name: 'voyage-4-large', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/1M tokens', bestFor: 'Best quality, multilingual', shortFor: 'Best quality' },

package/src/lib/math.js

@@ -3,6 +3,11 @@
 /**
  * Compute cosine similarity between two vectors.
  * cosine_sim(a, b) = dot(a, b) / (||a|| * ||b||)
+ *
+ * Fun fact: this is basically asking "how much do these two vectors
+ * vibe?" — 1.0 means soulmates, 0.0 means strangers at a party,
+ * -1.0 means they're in a Twitter argument.
+ *
  * @param {number[]} a
  * @param {number[]} b
  * @returns {number} Similarity score in [-1, 1]

package/src/playground/index.html

@@ -680,6 +680,57 @@ select:focus { outline: none; border-color: var(--accent); }
   margin-top: 4px;
 }
 
+/* About page */
+.about-container { max-width: 680px; margin: 0 auto; }
+.about-header { display: flex; gap: 24px; align-items: center; margin-bottom: 24px; }
+.about-avatar {
+  width: 120px; height: 120px;
+  border-radius: 50%;
+  border: 3px solid var(--accent);
+  box-shadow: 0 0 20px var(--accent-glow);
+  flex-shrink: 0;
+}
+.about-name { font-size: 24px; font-weight: 700; color: var(--text); }
+.about-role { font-size: 14px; color: var(--accent); margin-top: 4px; }
+.about-links { display: flex; gap: 12px; margin-top: 8px; }
+.about-links a {
+  color: var(--text-dim);
+  font-size: 13px;
+  text-decoration: none;
+  transition: color 0.2s;
+}
+.about-links a:hover { color: var(--accent); }
+.about-section { margin-bottom: 24px; }
+.about-section-title {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--accent);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  margin-bottom: 8px;
+}
+.about-text { font-size: 14px; line-height: 1.8; color: var(--text); }
+.about-text a { color: var(--accent); text-decoration: none; }
+.about-text a:hover { text-decoration: underline; }
+.about-disclaimer {
+  background: rgba(255, 215, 61, 0.08);
+  border: 1px solid rgba(255, 215, 61, 0.2);
+  border-radius: var(--radius);
+  padding: 16px 20px;
+  margin-top: 24px;
+}
+.about-disclaimer-title {
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--warning);
+  margin-bottom: 6px;
+}
+.about-disclaimer-text {
+  font-size: 13px;
+  line-height: 1.7;
+  color: var(--text-dim);
+}
+
 @media (max-width: 768px) {
   .compare-grid, .search-results { grid-template-columns: 1fr; }
   .nav { padding: 0 12px; }
@@ -711,6 +762,7 @@ select:focus { outline: none; border-color: var(--accent); }
   <button class="tab-btn" data-tab="search">🔍 Search</button>
   <button class="tab-btn" data-tab="benchmark">⏱ Benchmark</button>
   <button class="tab-btn" data-tab="explore">📚 Explore</button>
+  <button class="tab-btn" data-tab="about">ℹ️ About</button>
 </div>
 
 <div class="main">
@@ -1001,8 +1053,78 @@ Reranking models rescore initial search results to improve relevance ordering.</
 
 </div>
 
+<!-- ========== ABOUT TAB ========== -->
+<div class="tab-panel" id="tab-about">
+  <div class="about-container">
+    <div class="card">
+      <div class="about-header">
+        <img src="https://avatars.githubusercontent.com/u/192552?v=4" alt="Michael Lynn" class="about-avatar">
+        <div>
+          <div class="about-name">Michael Lynn</div>
+          <div class="about-role">Principal Staff Developer Advocate · MongoDB</div>
+          <div class="about-links">
+            <a href="https://github.com/mrlynn" target="_blank" rel="noopener">🔗 GitHub</a>
+            <a href="https://mlynn.org" target="_blank" rel="noopener">🌐 mlynn.org</a>
+            <a href="https://www.npmjs.com/package/voyageai-cli" target="_blank" rel="noopener">📦 npm</a>
+          </div>
+        </div>
+      </div>
+
+      <div class="about-section">
+        <div class="about-section-title">About This Project</div>
+        <div class="about-text">
+          <strong>voyageai-cli</strong> (<code style="color:var(--accent);">vai</code>) is a community-built command-line tool for working with
+          <a href="https://www.mongodb.com/docs/voyageai/" target="_blank">Voyage AI</a> embeddings, reranking, and
+          <a href="https://www.mongodb.com/products/platform/atlas-vector-search" target="_blank">MongoDB Atlas Vector Search</a>.
+          It was created to make it easier for developers to explore, benchmark, and integrate
+          Voyage AI models into their applications — right from the terminal or this playground.
+        </div>
+      </div>
+
+      <div class="about-section">
+        <div class="about-section-title">About Michael</div>
+        <div class="about-text">
+          Michael Lynn is a Principal Staff Developer Advocate at MongoDB with 25+ years in enterprise
+          infrastructure and over a decade at MongoDB. He focuses on strategic developer relations,
+          creating educational content around Vector Search, AI enablement, and developer tooling.
+          He builds tools like this to help developers get hands-on with new technology faster.
+        </div>
+      </div>
+
+      <div class="about-section">
+        <div class="about-section-title">What You Can Do Here</div>
+        <div class="about-text">
+          <strong>⚡ Embed</strong> — Generate vector embeddings for any text<br>
+          <strong>⚖️ Compare</strong> — Measure cosine similarity between texts<br>
+          <strong>🔍 Search</strong> — Semantic search with optional reranking<br>
+          <strong>⏱ Benchmark</strong> — Compare model latency, ranking quality, and costs<br>
+          <strong>📚 Explore</strong> — Learn about embeddings, vector search, RAG, and more
+        </div>
+      </div>
+
+      <div class="about-disclaimer">
+        <div class="about-disclaimer-title">⚠️ Community Tool Disclaimer</div>
+        <div class="about-disclaimer-text">
+          This tool is <strong>not</strong> an official product of MongoDB, Inc. or Voyage AI.
+          It is independently built and maintained by Michael Lynn as a community resource.
+          It is not supported, endorsed, or guaranteed by either company. Use at your own discretion.
+          For official documentation, visit
+          <a href="https://www.mongodb.com/docs/voyageai/" target="_blank" style="color:var(--warning);">mongodb.com/docs/voyageai</a>.
+        </div>
+      </div>
+    </div>
+
+    <div style="text-align:center;margin-top:16px;font-size:12px;color:var(--text-muted);">
+      Made with ☕ and curiosity · <a href="https://github.com/mrlynn/voyageai-cli" target="_blank" style="color:var(--text-dim);">Source on GitHub</a>
+    </div>
+  </div>
+</div>
+
 <!-- ========== EXPLORE TAB ========== -->
 <div class="tab-panel" id="tab-explore">
+  <div style="margin-bottom:16px;">
+    <input type="text" id="exploreSearch" placeholder="🔍 Search concepts..." oninput="filterExplore()" style="max-width:400px;">
+  </div>
   <div class="explore-grid" id="exploreGrid"></div>
 </div>
 
@@ -1022,7 +1144,7 @@ let lastEmbedding = null;
 async function init() {
   setupTabs();
   await loadConfig();
-  await loadModels();
+  await Promise.all([loadModels(), loadConcepts()]);
   populateModelSelects();
   buildExploreCards();
 }
@@ -1393,103 +1515,102 @@ function createResultItem(rank, result, maxScore, movement) {
 }
 
 // ── Explore ──
-const exploreTopics = [
-  {
-    key: 'embeddings', icon: '🧮', title: 'Embeddings',
-    summary: 'Numerical representations that capture meaning',
-    content: 'Vector embeddings are arrays of floating-point numbers (typically 256–2048 dimensions) that capture the semantic meaning of text. When you embed text, a neural network reads the input and produces a fixed-size vector. Texts with similar meanings end up close together in this high-dimensional space, even if they share no words.\n\nHigher dimensions capture more nuance but cost more to store and search. Voyage 4 models default to 1024 dimensions but support 256–2048 via Matryoshka representation learning — you can truncate embeddings without retraining.',
-    tab: 'embed', prefill: () => { document.getElementById('embedInput').value = 'Artificial intelligence is transforming how we build software applications.'; }
-  },
-  {
-    key: 'reranking', icon: '🏆', title: 'Reranking',
-    summary: 'Second-stage precision with cross-attention',
-    content: 'Reranking re-scores candidate documents against a query using cross-attention — it reads the query and each document together, producing much more accurate relevance scores than embedding similarity alone.\n\nThe two-stage pattern: embedding search retrieves a broad set (high recall), then the reranker re-orders them (high precision). This adds ~50-200ms but dramatically improves result quality.',
-    tab: 'search', prefill: () => {
-      document.getElementById('searchQuery').value = 'How do I implement semantic search?';
-      document.getElementById('searchDocs').value = 'MongoDB Atlas provides vector search capabilities\nThe recipe calls for two cups of flour\nSemantic search uses embeddings to find meaning\nVector databases store high-dimensional data\nThe weather forecast predicts rain tomorrow';
-    }
-  },
-  {
-    key: 'vector-search', icon: '🔎', title: 'Vector Search',
-    summary: 'Finding documents by meaning, not keywords',
-    content: 'Vector search finds documents whose embeddings are closest to a query embedding. Instead of matching keywords, it matches meaning. MongoDB Atlas Vector Search uses $vectorSearch with HNSW (Hierarchical Navigable Small World) graph indexes for fast approximate nearest neighbor search.\n\nSimilarity functions: cosine (direction, ignoring magnitude — best default), dotProduct (magnitude-sensitive), euclidean (straight-line distance).',
-    tab: 'search', prefill: () => {}
-  },
-  {
-    key: 'rag', icon: '🤖', title: 'RAG',
-    summary: 'Retrieval-Augmented Generation',
-    content: 'RAG combines retrieval with LLM generation: instead of relying on the LLM\'s training data alone, you retrieve relevant context from your own data and include it in the prompt.\n\nThe pattern: 1) Embed your corpus and store vectors, 2) Embed the user\'s question and run vector search, 3) Pass retrieved documents + question to an LLM. Adding reranking between steps 2 and 3 dramatically improves answer quality.',
-    tab: 'search', prefill: () => {}
-  },
-  {
-    key: 'cosine', icon: '📐', title: 'Cosine Similarity',
-    summary: 'Measuring the angle between vectors',
-    content: 'Cosine similarity measures the angle between two vectors, ignoring magnitude. Vectors pointing the same direction score 1, perpendicular score 0, opposite score -1.\n\nFor text embeddings (which are typically normalized), cosine similarity and dot product give identical rankings. Cosine is preferred because it\'s intuitive: it measures how similar the direction (meaning) is, regardless of scale.',
-    tab: 'compare', prefill: () => {
-      document.getElementById('compareA').value = 'The database stores information efficiently';
-      document.getElementById('compareB').value = 'Data is saved in an optimized storage system';
-    }
-  },
-  {
-    key: 'two-stage', icon: '🎯', title: 'Two-Stage Retrieval',
-    summary: 'Embed → Search → Rerank for best results',
-    content: 'Two-stage retrieval combines a fast first stage (embedding search for recall) with a precise second stage (reranking for precision).\n\nStage 1: Embed query, run ANN search, retrieve top-100 candidates (fast, milliseconds). Stage 2: Feed query + candidates to a reranker with cross-attention, return top-5-10 (precise, ~100ms extra). This gives you both speed and accuracy.',
-    tab: 'search', prefill: () => {}
-  },
-  {
-    key: 'input-types', icon: '🏷️', title: 'Input Types',
-    summary: 'Query vs document — why it matters',
-    content: 'The input_type parameter tells the model whether text is a search query or a document being indexed. The model internally prepends different prompt prefixes for each, optimizing embeddings for asymmetric retrieval.\n\nAlways use input_type="query" for search queries and input_type="document" for corpus text. Omitting this parameter degrades retrieval accuracy.',
-    tab: 'embed', prefill: () => {
-      document.getElementById('embedInput').value = 'What is vector search and how does it work?';
-      document.getElementById('embedInputType').value = 'query';
-    }
-  },
-  {
-    key: 'models', icon: '🧠', title: 'Models',
-    summary: 'Choosing the right model for your task',
-    content: 'Voyage 4 Series: voyage-4-large (best quality, $0.12/1M tokens), voyage-4 (balanced, $0.06), voyage-4-lite (budget, $0.02). All share the same embedding space — you can mix models.\n\nDomain-specific: voyage-code-3 (code), voyage-finance-2 (financial), voyage-law-2 (legal). Rerankers: rerank-2.5 (best quality), rerank-2.5-lite (faster). Start with voyage-4 for general use.',
-    tab: 'embed', prefill: () => {}
-  },
-];
+// ── Explore: icons and tab mappings per concept ──
+const CONCEPT_META = {
+  embeddings:          { icon: '🧮', tab: 'embed' },
+  reranking:           { icon: '🏆', tab: 'search' },
+  'vector-search':     { icon: '🔎', tab: 'search' },
+  rag:                 { icon: '🤖', tab: 'search' },
+  'cosine-similarity': { icon: '📐', tab: 'compare' },
+  'two-stage-retrieval': { icon: '🎯', tab: 'search' },
+  'input-type':        { icon: '🏷️', tab: 'embed' },
+  models:              { icon: '🧠', tab: 'embed' },
+  'api-keys':          { icon: '🔑', tab: 'embed' },
+  'api-access':        { icon: '🌐', tab: 'embed' },
+  'batch-processing':  { icon: '📦', tab: 'embed' },
+  benchmarking:        { icon: '⏱', tab: 'benchmark' },
+};
+
+let exploreConcepts = {};
+
+async function loadConcepts() {
+  try {
+    const res = await fetch('/api/concepts');
+    const data = await res.json();
+    exploreConcepts = data.concepts || {};
+  } catch {
+    console.error('Failed to load concepts');
+  }
+}
+
+function escapeHtml(str) {
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
 
 function buildExploreCards() {
   const grid = document.getElementById('exploreGrid');
   grid.innerHTML = '';
-  exploreTopics.forEach(topic => {
+
+  for (const [key, concept] of Object.entries(exploreConcepts)) {
+    const meta = CONCEPT_META[key] || { icon: '📚', tab: 'embed' };
     const card = document.createElement('div');
     card.className = 'explore-card';
+    card.dataset.key = key;
+
+    // Build links HTML
+    let linksHtml = '';
+    if (concept.links && concept.links.length > 0) {
+      linksHtml = '<div style="margin-top:12px;"><strong style="color:var(--accent);font-size:12px;">LEARN MORE</strong><br>' +
+        concept.links.map(url => `<a href="${escapeHtml(url)}" target="_blank" rel="noopener" style="color:var(--accent);font-size:12px;word-break:break-all;">${escapeHtml(url)}</a>`).join('<br>') +
+        '</div>';
+    }
+
+    // Build try-it HTML
+    let tryItHtml = '';
+    if (concept.tryIt && concept.tryIt.length > 0) {
+      tryItHtml = '<div style="margin-top:12px;"><strong style="color:var(--accent);font-size:12px;">TRY IT</strong>' +
+        concept.tryIt.map(cmd => `<div style="font-family:var(--mono);font-size:12px;color:var(--text-dim);background:var(--bg);padding:4px 8px;border-radius:4px;margin-top:4px;">$ ${escapeHtml(cmd)}</div>`).join('') +
+        '</div>';
+    }
+
     card.innerHTML = `
-      <div class="explore-card-icon">${topic.icon}</div>
-      <div class="explore-card-title">${topic.title}</div>
-      <div class="explore-card-summary">${topic.summary}</div>
-      <div class="explore-card-content">${topic.content}</div>
+      <div class="explore-card-icon">${meta.icon}</div>
+      <div class="explore-card-title">${escapeHtml(concept.title)}</div>
+      <div class="explore-card-summary">${escapeHtml(concept.summary)}</div>
+      <div class="explore-card-content">${escapeHtml(concept.content)}${linksHtml}${tryItHtml}</div>
       <div class="explore-card-actions">
-        <button class="btn btn-small" onclick="tryTopic('${topic.key}')">Try it →</button>
+        <button class="btn btn-small" onclick="tryTopic('${escapeHtml(key)}')">Try it in playground →</button>
         <button class="btn btn-secondary btn-small" onclick="collapseTopic(this)">Collapse</button>
       </div>
     `;
     card.addEventListener('click', function(e) {
-      if (e.target.tagName === 'BUTTON') return;
+      if (e.target.tagName === 'BUTTON' || e.target.tagName === 'A') return;
       if (!this.classList.contains('expanded')) {
         this.classList.add('expanded');
       }
     });
     grid.appendChild(card);
-  });
+  }
 }
 
 window.tryTopic = function(key) {
-  const topic = exploreTopics.find(t => t.key === key);
-  if (!topic) return;
-  if (topic.prefill) topic.prefill();
-  switchTab(topic.tab);
+  const meta = CONCEPT_META[key];
+  if (meta) switchTab(meta.tab);
 };
 
 window.collapseTopic = function(btn) {
   btn.closest('.explore-card').classList.remove('expanded');
 };
 
+window.filterExplore = function() {
+  const q = document.getElementById('exploreSearch').value.toLowerCase().trim();
+  document.querySelectorAll('#exploreGrid .explore-card').forEach(card => {
+    if (!q) { card.style.display = ''; return; }
+    const text = card.textContent.toLowerCase();
+    card.style.display = text.includes(q) ? '' : 'none';
+  });
+};
+
 // ── Benchmark: Sub-panel switching ──
 document.querySelectorAll('.bench-panel-btn').forEach(btn => {
   btn.addEventListener('click', () => {

package/test/commands/about.test.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { Command } = require('commander');
+const { registerAbout } = require('../../src/commands/about');
+
+describe('about command', () => {
+  it('registers correctly on a program', () => {
+    const program = new Command();
+    registerAbout(program);
+    const aboutCmd = program.commands.find(c => c.name() === 'about');
+    assert.ok(aboutCmd, 'about command should be registered');
+  });
+
+  it('has --json option', () => {
+    const program = new Command();
+    registerAbout(program);
+    const aboutCmd = program.commands.find(c => c.name() === 'about');
+    const optionNames = aboutCmd.options.map(o => o.long);
+    assert.ok(optionNames.includes('--json'), 'should have --json option');
+  });
+});