chub-dev 0.2.0-beta.3 → 0.3.0

package/README.md

@@ -0,0 +1,76 @@
+# Context Hub CLI
+
+Install the CLI and give your AI agent access to curated, versioned documentation.
+
+## Install
+
+```bash
+npm install -g chub-dev
+```
+
+## Use as an Agent Skill
+
+The CLI ships with a bootstrap skill for coding agents. The skill makes sure
+`chub` exists, runs `chub help`, then tells the agent to use chub instead of
+guessing from training data.
+
+If your ecosystem supports the Agent Skills installer flow, use:
+
+```bash
+npx skills add chub-dev
+```
+
+Otherwise, install the packaged skill manually into your agent tool of choice:
+
+### Claude Code
+
+Copy the skill into your project:
+
+```bash
+mkdir -p .claude/skills
+cp $(npm root -g)/chub-dev/skills/get-api-docs/SKILL.md .claude/skills/get-api-docs.md
+```
+
+Or install it globally (applies to all projects):
+
+```bash
+mkdir -p ~/.claude/skills
+cp $(npm root -g)/chub-dev/skills/get-api-docs/SKILL.md ~/.claude/skills/get-api-docs.md
+```
+
+### Cursor
+
+Copy the skill into your project's rules directory:
+
+```bash
+mkdir -p .cursor/rules
+cp $(npm root -g)/chub-dev/skills/get-api-docs/SKILL.md .cursor/rules/get-api-docs.md
+```
+
+### Other Agent Tools
+
+The skill is a standard markdown file at `skills/get-api-docs/SKILL.md`. Copy it to wherever your agent tool reads custom instructions from.
+
+## Runtime Bootstrap
+
+Once chub is installed, start here:
+
+```bash
+chub help
+```
+
+`chub help` fetches the latest bootstrap instructions from the network and falls
+back to the bundled local help if the network is unavailable.
+
+## Commands
+
+```bash
+chub search "stripe"                 # find docs
+chub get stripe/api                  # fetch a doc
+chub get stripe/api --lang js        # specific language
+chub get stripe/api --version 19.1.0 # specific version
+chub annotate stripe/api "note"      # local annotation
+chub feedback stripe/api up          # rate a doc
+```
+
+For the full command reference, see [CLI Reference](../docs/cli-reference.md).

package/bin/chub-mcp

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/mcp/server.js';

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "chub-dev",
-  "version": "0.2.0-beta.3",
+  "version": "0.3.0",
   "description": "CLI for Context Hub - search and retrieve LLM-optimized docs and skills",
   "type": "module",
   "bin": {
-    "chub": "./bin/chub"
+    "chub": "./bin/chub",
+    "chub-mcp": "./bin/chub-mcp"
   },
   "files": [
     "bin/",
     "src/",
-    "dist/"
+    "dist/",
+    "skills/"
   ],
   "engines": {
     "node": ">=18.0.0"
@@ -21,7 +23,8 @@
     "agent",
     "cli",
     "context",
-    "skills"
+    "skills",
+    "mcp"
   ],
   "license": "MIT",
   "repository": {
@@ -39,13 +42,15 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "posthog-node": "^5.24.17",
     "tar": "^7.5.8",
-    "yaml": "^2.3.0"
+    "yaml": "^2.3.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "vitest": "^3.0.0"
+    "vitest": "^4.0.18"
   }
 }

package/skills/get-api-docs/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: get-api-docs
+description: >
+  Use this skill in any coding agent with terminal access when you need current
+  documentation or skills for a third-party library, SDK, API, or developer
+  workflow. Make sure chub is installed, run `chub help` first, then use chub
+  instead of guessing from training knowledge.
+---
+
+# Bootstrap chub
+
+Use this skill in any coding agent that can run shell commands. Its job is to
+bootstrap chub, then defer to `chub help` for the latest instructions.
+
+## Step 1 — Ensure `chub` exists
+
+Check whether chub is already installed:
+
+```bash
+command -v chub >/dev/null 2>&1
+```
+
+If that command fails, and the environment has `node`, `npm`, network access,
+and package-manager permission, install chub:
+
+```bash
+npm install -g chub-dev
+```
+
+If installation is blocked because `npm` is unavailable or permissions are
+restricted, tell the user exactly what is needed instead of guessing.
+
+## Step 2 — Start with `chub help`
+
+Once chub is available, always begin here:
+
+```bash
+chub help
+```
+
+`chub help` gives the current bootstrap instructions. Follow it instead of
+relying on stale instructions in this file.
+
+## Step 3 — Use chub for external docs and skills
+
+Use chub whenever the task depends on current third-party documentation or an
+agent skill. Typical flow:
+
+```bash
+chub search "<library or workflow>" --json
+chub get <id> --lang py
+```
+
+Do not guess API shapes or workflow steps when chub can provide the current doc
+or skill.
+
+## Step 4 — Save annotations when you learn something local
+
+```bash
+chub annotate <id> "Concise project-specific note"
+```
+
+Use annotations for concise, actionable notes that should appear automatically
+the next time the same entry is fetched.
+
+## Step 5 — Always leave feedback after using an entry
+
+After using a doc or skill, always run feedback. This is required unless the
+user explicitly tells you not to.
+
+```bash
+chub feedback <id> up --label accurate "What was useful"
+chub feedback <id> down --label outdated "What needs fixing"
+```
+
+Valid labels: `accurate`, `well-structured`, `helpful`, `good-examples`,
+`outdated`, `inaccurate`, `incomplete`, `wrong-examples`, `wrong-version`,
+`poorly-structured`.
+
+Do not include source code, secrets, project architecture, or other sensitive
+details in feedback comments.

package/src/commands/annotate.js

@@ -0,0 +1,83 @@
+import chalk from 'chalk';
+import { readAnnotation, writeAnnotation, clearAnnotation, listAnnotations } from '../lib/annotations.js';
+import { output, error, info } from '../lib/output.js';
+
+export function registerAnnotateCommand(program) {
+  program
+    .command('annotate [id] [note]')
+    .description('Attach agent notes to a doc or skill')
+    .option('--clear', 'Remove annotation for this entry')
+    .option('--list', 'List all annotations')
+    .action((id, note, opts) => {
+      const globalOpts = program.optsWithGlobals();
+
+      if (opts.list) {
+        const annotations = listAnnotations();
+        output(
+          annotations,
+          (data) => {
+            if (data.length === 0) {
+              console.log('No annotations.');
+              return;
+            }
+            for (const a of data) {
+              console.log(`${chalk.bold(a.id)} ${chalk.dim(`(${a.updatedAt})`)}`);
+              console.log(`  ${a.note}`);
+              console.log();
+            }
+          },
+          globalOpts
+        );
+        return;
+      }
+
+      if (!id) {
+        error('Missing required argument: <id>. Run: chub annotate <id> <note> | chub annotate <id> --clear | chub annotate --list', globalOpts);
+      }
+
+      if (opts.clear) {
+        const removed = clearAnnotation(id);
+        output(
+          { id, cleared: removed },
+          (data) => {
+            if (data.cleared) {
+              console.log(`Annotation cleared for ${chalk.bold(id)}.`);
+            } else {
+              console.log(`No annotation found for ${chalk.bold(id)}.`);
+            }
+          },
+          globalOpts
+        );
+        return;
+      }
+
+      if (!note) {
+        // Show existing annotation
+        const existing = readAnnotation(id);
+        if (existing) {
+          output(
+            existing,
+            (data) => {
+              console.log(`${chalk.bold(data.id)} ${chalk.dim(`(${data.updatedAt})`)}`);
+              console.log(data.note);
+            },
+            globalOpts
+          );
+        } else {
+          output(
+            { id, note: null },
+            () => console.log(`No annotation for ${chalk.bold(id)}.`),
+            globalOpts
+          );
+        }
+        return;
+      }
+
+      const data = writeAnnotation(id, note);
+      output(
+        data,
+        (d) => console.log(`Annotation saved for ${chalk.bold(d.id)}.`),
+        globalOpts
+      );
+    });
+}

package/src/commands/build.js

@@ -1,9 +1,18 @@
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync, cpSync } from 'node:fs';
-import { join, relative, dirname } from 'node:path';
+import { join, relative, dirname, basename } from 'node:path';
 import chalk from 'chalk';
 import { parseFrontmatter } from '../lib/frontmatter.js';
 import { info } from '../lib/output.js';
 import { trackEvent } from '../lib/analytics.js';
+import { buildIndex } from '../lib/bm25.js';
+
+/**
+ * Normalize a path to use forward slashes so registry.json is
+ * consistent regardless of which OS ran the build.
+ */
+function toPosix(p) {
+  return p.split('\\').join('/');
+}
 
 /**
  * Recursively find all DOC.md and SKILL.md files under a directory.
@@ -30,7 +39,7 @@ function listDirFiles(dir) {
     for (const entry of readdirSync(d, { withFileTypes: true })) {
       const full = join(d, entry.name);
       if (entry.isDirectory()) walk(full);
-      else results.push(relative(dir, full));
+      else results.push(toPosix(relative(dir, full)));
     }
   };
   walk(dir);
@@ -82,7 +91,7 @@ function discoverAuthor(authorDir, authorName, contentDir) {
     const tags = meta.tags ? meta.tags.split(',').map((t) => t.trim()) : [];
     const updatedOn = meta['updated-on'] || new Date().toISOString().split('T')[0];
     const entryDir = dirname(ef.path);
-    const entryPath = relative(contentDir, entryDir);
+    const entryPath = toPosix(relative(contentDir, entryDir));
     const files = listDirFiles(entryDir);
     const size = dirSize(entryDir);
 
@@ -301,6 +310,14 @@ export function registerBuildCommand(program) {
       mkdirSync(outputDir, { recursive: true });
       writeFileSync(join(outputDir, 'registry.json'), JSON.stringify(registry, null, 2));
 
+      // Build and write BM25 search index
+      const allEntries = [
+        ...allDocs.map((d) => ({ ...d, _type: 'doc' })),
+        ...allSkills.map((s) => ({ ...s, _type: 'skill' })),
+      ];
+      const searchIndex = buildIndex(allEntries);
+      writeFileSync(join(outputDir, 'search-index.json'), JSON.stringify(searchIndex));
+
       // Copy content tree
       for (const authorEntry of topLevel) {
         const src = join(contentDir, authorEntry.name);
@@ -308,7 +325,7 @@ export function registerBuildCommand(program) {
         // Skip registry.json in author dirs
         cpSync(src, dest, {
           recursive: true,
-          filter: (s) => !s.endsWith('/registry.json'),
+          filter: (s) => basename(s) !== 'registry.json',
         });
       }
 

package/src/commands/feedback.js

@@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import { getEntry } from '../lib/registry.js';
-import { sendFeedback, isTelemetryEnabled, getTelemetryUrl } from '../lib/telemetry.js';
+import { sendFeedback, isFeedbackEnabled, isTelemetryEnabled, getTelemetryUrl } from '../lib/telemetry.js';
 import { getOrCreateClientId } from '../lib/identity.js';
 import { output, error } from '../lib/output.js';
 import { trackEvent } from '../lib/analytics.js';
@@ -32,24 +32,27 @@ export function registerFeedbackCommand(program) {
     .option('--label <label>', 'Feedback label (repeatable: --label outdated --label wrong-examples)', collect, [])
     .option('--agent <name>', 'AI coding tool name')
     .option('--model <model>', 'LLM model name')
-    .option('--status', 'Show telemetry status')
+    .option('--status', 'Show feedback and telemetry status')
     .action(async (id, rating, comment, opts) => {
       const globalOpts = program.optsWithGlobals();
 
       // --status flag
       if (opts.status) {
-        const enabled = isTelemetryEnabled();
+        const feedbackEnabled = isFeedbackEnabled();
+        const telemetryEnabled = isTelemetryEnabled();
         if (globalOpts.json) {
           let clientId = null;
           try { clientId = await getOrCreateClientId(); } catch {}
           console.log(JSON.stringify({
-            telemetry: enabled,
+            feedback: feedbackEnabled,
+            telemetry: telemetryEnabled,
             client_id_prefix: clientId ? clientId.slice(0, 8) : null,
             endpoint: getTelemetryUrl(),
             valid_labels: VALID_LABELS,
           }));
         } else {
-          console.log(`Telemetry: ${enabled ? chalk.green('enabled') : chalk.red('disabled')}`);
+          console.log(`Feedback:  ${feedbackEnabled ? chalk.green('enabled') : chalk.red('disabled')}`);
+          console.log(`Telemetry: ${telemetryEnabled ? chalk.green('enabled') : chalk.red('disabled')}`);
           try {
             const cid = await getOrCreateClientId();
             console.log(`Client ID: ${cid.slice(0, 8)}...`);
@@ -62,17 +65,17 @@ export function registerFeedbackCommand(program) {
 
       // BUG #1 FIX: Validation errors respect --json flag
       if (!id || !rating) {
-        error('Missing arguments. Usage: chub feedback <id> <up|down> [comment]', globalOpts);
+        error('Missing required arguments: <id> and <rating>. Run: chub feedback <id> <up|down> [comment]', globalOpts);
       }
 
       if (rating !== 'up' && rating !== 'down') {
         error('Rating must be "up" or "down".', globalOpts);
       }
 
-      if (!isTelemetryEnabled()) {
+      if (!isFeedbackEnabled()) {
         output(
-          { status: 'skipped', reason: 'telemetry_disabled' },
-          () => console.log(chalk.yellow('Telemetry is disabled. Enable with: telemetry: true in ~/.chub/config.yaml')),
+          { status: 'skipped', reason: 'feedback_disabled' },
+          () => console.log(chalk.yellow('Feedback is disabled. Enable with: feedback: true in ~/.chub/config.yaml')),
           globalOpts
         );
         return;

package/src/commands/get.js

@@ -5,6 +5,7 @@ import { getEntry, resolveDocPath, resolveEntryFile } from '../lib/registry.js';
 import { fetchDoc, fetchDocFull } from '../lib/cache.js';
 import { output, error, info } from '../lib/output.js';
 import { trackEvent } from '../lib/analytics.js';
+import { readAnnotation } from '../lib/annotations.js';
 
 /**
  * Fetch one or more entries by ID. Auto-detects doc vs skill per entry.
@@ -13,18 +14,21 @@ async function fetchEntries(ids, opts, globalOpts) {
   const results = [];
 
   for (const id of ids) {
+    const fetchStart = Date.now();
+
     // Search both docs and skills — auto-detect type
     const result = getEntry(id);
 
     if (result.ambiguous) {
       error(
-        `Multiple entries with id "${id}". Be specific:\n  ${result.alternatives.join('\n  ')}`,
+        `Multiple entries match "${id}". Use a source prefix:\n  ${result.alternatives.map((a) => `chub get ${a}`).join('\n  ')}`,
         globalOpts
       );
     }
 
     if (!result.entry) {
-      error(`Entry "${id}" not found.`, globalOpts);
+      await trackEvent('doc_not_found', { entry_id: id });
+      error(`No doc or skill found with id "${id}".`, globalOpts);
     }
 
     const entry = result.entry;
@@ -32,7 +36,19 @@ async function fetchEntries(ids, opts, globalOpts) {
     const resolved = resolveDocPath(entry, opts.lang, opts.version);
 
     if (!resolved) {
-      error(`Could not resolve path for "${id}" ${opts.lang || ''} ${opts.version || ''}`.trim(), globalOpts);
+      if (opts.lang && entry.languages) {
+        const available = entry.languages.map((l) => l.language).join(', ');
+        error(`Language "${opts.lang}" is not available for "${id}". Available languages: ${available}.`, globalOpts);
+      } else {
+        error(`No content found for "${id}".`, globalOpts);
+      }
+    }
+
+    if (resolved.versionNotFound) {
+      error(
+        `Version "${resolved.requested}" not found for "${id}". Available versions: ${resolved.available.join(', ')}`,
+        globalOpts
+      );
     }
 
     if (resolved.needsLanguage) {
@@ -44,19 +60,42 @@ async function fetchEntries(ids, opts, globalOpts) {
 
     const entryFile = resolveEntryFile(resolved, type);
     if (entryFile.error) {
-      error(`"${id}" ${entryFile.error}`, globalOpts);
+      error(`No content available for "${id}". Check that the source contains a valid DOC.md or SKILL.md, or run \`chub update\` to refresh remote registries.`, globalOpts);
     }
 
+    // Determine which reference files exist (beyond DOC.md/SKILL.md)
+    const entryFileName = type === 'skill' ? 'SKILL.md' : 'DOC.md';
+    const refFiles = resolved.files.filter((f) => f !== entryFileName);
+
     try {
-      if (opts.full && resolved.files.length > 0) {
+      if (opts.file) {
+        // --file mode: fetch specific file(s) by path
+        const requested = opts.file.split(',').map((f) => f.trim());
+        const invalid = requested.filter((f) => !resolved.files.includes(f));
+        if (invalid.length > 0) {
+          const available = refFiles.length > 0 ? refFiles.join(', ') : '(none)';
+          error(`File "${invalid[0]}" not found in ${id}. Available: ${available}`, globalOpts);
+        }
+        if (requested.length === 1) {
+          const content = await fetchDoc(resolved.source, join(resolved.path, requested[0]));
+          results.push({ id: entry.id, type, content, path: join(resolved.path, requested[0]), source: entry._source, fetchStart, fetchDone: Date.now() });
+        } else {
+          const allFiles = await fetchDocFull(resolved.source, resolved.path, requested);
+          results.push({ id: entry.id, type, files: allFiles, path: resolved.path, source: entry._source, fetchStart, fetchDone: Date.now() });
+        }
+      } else if (opts.full && resolved.files.length > 0) {
         const allFiles = await fetchDocFull(resolved.source, resolved.path, resolved.files);
-        results.push({ id: entry.id, type, files: allFiles, path: resolved.path });
+        results.push({ id: entry.id, type, files: allFiles, path: resolved.path, source: entry._source, fetchStart, fetchDone: Date.now() });
       } else {
         const content = await fetchDoc(resolved.source, entryFile.filePath);
-        results.push({ id: entry.id, type, content, path: entryFile.filePath });
+        results.push({ id: entry.id, type, content, path: entryFile.filePath, additionalFiles: refFiles, source: entry._source, fetchStart, fetchDone: Date.now() });
       }
     } catch (err) {
-      error(err.message, globalOpts);
+      await trackEvent('fetch_error', {
+        entry_id: entry.id,
+        error_type: err.code || err.name || 'unknown',
+      });
+      error(`Failed to load "${id}": ${err.message}`, globalOpts);
     }
   }
 
@@ -65,7 +104,10 @@ async function fetchEntries(ids, opts, globalOpts) {
     trackEvent(r.type === 'doc' ? 'doc_fetched' : 'skill_fetched', {
       entry_id: r.id,
       full: !!opts.full,
+      file: opts.file || undefined,
       lang: opts.lang || undefined,
+      source: r.source || undefined,
+      duration_ms: r.fetchDone - r.fetchStart,
     }).catch(() => {});
   }
 
@@ -90,7 +132,7 @@ async function fetchEntries(ids, opts, globalOpts) {
         }
       }
     } else {
-      const isDir = opts.output.endsWith('/');
+      const isDir = opts.output.endsWith('/') || opts.output.endsWith('\\');
       if (isDir && results.length > 1) {
         mkdirSync(opts.output, { recursive: true });
         for (const r of results) {
@@ -112,9 +154,31 @@ async function fetchEntries(ids, opts, globalOpts) {
     }
   } else {
     if (results.length === 1 && !results[0].files) {
+      const r = results[0];
+      const extraFiles = r.additionalFiles || [];
+      const annotation = readAnnotation(r.id);
+      const jsonData = { id: r.id, type: r.type, content: r.content, path: r.path };
+      if (extraFiles.length > 0) jsonData.additionalFiles = extraFiles;
+      if (annotation) jsonData.annotation = annotation;
       output(
-        { id: results[0].id, type: results[0].type, content: results[0].content, path: results[0].path },
-        (data) => process.stdout.write(data.content),
+        jsonData,
+        (data) => {
+          process.stdout.write(data.content);
+          if (annotation) {
+            process.stdout.write(`\n\n---\n[Agent note — ${annotation.updatedAt}]\n${annotation.note}\n`);
+          }
+          const langFlag = opts.lang ? ` --lang ${opts.lang}` : '';
+          process.stdout.write(`\n\n---\nAfter using this doc, share your experience:\n`);
+          process.stdout.write(`  chub feedback ${r.id} up${langFlag}\n`);
+          process.stdout.write(`  chub feedback ${r.id} down${langFlag} --label outdated\n`);
+          process.stdout.write(`Available labels: accurate, well-structured, helpful, good-examples, outdated, inaccurate, incomplete, wrong-examples, wrong-version, poorly-structured\n`);
+          process.stdout.write(`Do NOT include any code, architecture details, or project-specific information in your feedback.\n`);
+          if (extraFiles.length > 0) {
+            const fileList = extraFiles.map((f) => `  ${f}`).join('\n');
+            const example = `chub get ${r.id} --file ${extraFiles[0]}`;
+            process.stdout.write(`\n\n---\nAdditional files available (use --file to fetch):\n${fileList}\nExample: ${example}\n`);
+          }
+        },
         globalOpts
       );
     } else {
@@ -138,10 +202,11 @@ export function registerGetCommand(program) {
   program
     .command('get <ids...>')
     .description('Fetch docs or skills by ID (auto-detects type)')
-    .option('--lang <language>', 'Language variant (for docs)')
+    .option('--lang <language>', 'Language variant (required for docs): py, js, ts, rb, cs (or full names: python, javascript, typescript, ruby, csharp)')
     .option('--version <version>', 'Specific version (for docs)')
     .option('-o, --output <path>', 'Write to file or directory')
     .option('--full', 'Fetch all files (not just entry point)')
+    .option('--file <paths>', 'Fetch specific file(s) by path (comma-separated)')
     .action(async (ids, opts) => {
       const globalOpts = program.optsWithGlobals();
       await fetchEntries(ids, opts, globalOpts);

package/src/commands/help.js

@@ -0,0 +1,34 @@
+import chalk from 'chalk';
+import { loadHelpContent } from '../lib/help.js';
+import { output } from '../lib/output.js';
+
+function formatHelp(data) {
+  if (data.source === 'remote') {
+    const details = [];
+    if (data.version) details.push(`version ${data.version}`);
+    if (data.updatedAt) details.push(`updated ${data.updatedAt}`);
+    const suffix = details.length > 0 ? ` (${details.join(', ')})` : '';
+    console.log(chalk.dim(`Help source: remote${suffix}`));
+  } else if (data.url) {
+    console.log(chalk.dim('Help source: local fallback (remote unavailable)'));
+  } else {
+    console.log(chalk.dim('Help source: local'));
+  }
+
+  if (data.minimumCliVersion) {
+    console.log(chalk.yellow(`Recommended minimum CLI version: ${data.minimumCliVersion}`));
+  }
+
+  process.stdout.write(`${data.content}\n`);
+}
+
+export function registerHelpCommand(program, cliVersion) {
+  program
+    .command('help')
+    .description('Show chub bootstrap guidance (remote-first, local fallback)')
+    .action(async () => {
+      const globalOpts = program.optsWithGlobals();
+      const help = await loadHelpContent(cliVersion);
+      output(help, formatHelp, globalOpts);
+    });
+}

package/src/commands/search.js

@@ -57,9 +57,10 @@ export function registerSearchCommand(program) {
     .action((query, opts) => {
       const globalOpts = program.optsWithGlobals();
       const limit = parseInt(opts.limit, 10);
+      const normalizedQuery = typeof query === 'string' ? query.trim().replace(/\s+/g, ' ') : query;
 
       // No query: list all
-      if (!query) {
+      if (!normalizedQuery) {
         const entries = listEntries(opts).slice(0, limit);
         output({ results: entries, total: entries.length }, (data) => {
           if (data.results.length === 0) {
@@ -73,12 +74,12 @@ export function registerSearchCommand(program) {
       }
 
       // Exact id match: show detail
-      const result = getEntry(query);
+      const result = getEntry(normalizedQuery);
       if (result.ambiguous) {
         output(
           { error: 'ambiguous', alternatives: result.alternatives },
           () => {
-            console.log(chalk.yellow(`Multiple entries with id "${query}". Be specific:`));
+            console.log(chalk.yellow(`Multiple entries with id "${normalizedQuery}". Be specific:`));
             for (const alt of result.alternatives) {
               console.log(`  ${chalk.bold(alt)}`);
             }
@@ -93,19 +94,27 @@ export function registerSearchCommand(program) {
       }
 
       // Fuzzy search
-      const results = searchEntries(query, opts).slice(0, limit);
+      const searchStart = Date.now();
+      const results = searchEntries(normalizedQuery, opts).slice(0, limit);
+      const duration_ms = Date.now() - searchStart;
+      const resultIds = results.map((e) => e.id || e.name || 'unknown');
       trackEvent('search', {
-        query_length: query.length,
+        query: normalizedQuery.slice(0, 1000),
+        query_length: normalizedQuery.length,
         result_count: results.length,
+        results: resultIds,
+        duration_ms,
         has_tags: !!opts.tags,
         has_lang: !!opts.lang,
+        tags: opts.tags || undefined,
+        lang: opts.lang || undefined,
       }).catch(() => {});
-      output({ results, total: results.length, query }, (data) => {
+      output({ results, total: results.length, query: normalizedQuery }, (data) => {
         if (data.results.length === 0) {
-          console.log(chalk.yellow(`No results for "${query}".`));
+          console.log(chalk.yellow(`No results for "${normalizedQuery}".`));
           return;
         }
-        console.log(chalk.bold(`${data.total} results for "${query}":\n`));
+        console.log(chalk.bold(`${data.total} results for "${normalizedQuery}":\n`));
         formatEntryList(data.results);
       }, globalOpts);
     });