@assistkick/create 1.31.0 → 1.33.0

package/templates/assistkick-product-system/packages/shared/db/migrations/meta/_journal.json

@@ -22,6 +22,13 @@
       "when": 1773918822690,
       "tag": "0002_noisy_maelstrom",
       "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1774032107925,
+      "tag": "0003_solid_manta",
+      "breakpoints": true
     }
   ]
 }

package/templates/assistkick-product-system/packages/shared/db/schema.ts

@@ -15,6 +15,7 @@ export const nodes = sqliteTable('nodes', {
   updatedAt: text('updated_at').notNull(),
   body: text('body'),
   projectId: text('project_id'),
+  embedding: text('embedding'),
 });
 
 // --- edges table ---

package/templates/assistkick-product-system/packages/shared/lib/constants.ts

@@ -19,6 +19,7 @@ export const NODE_TYPES = {
   flow: 'flow',
   assumption: 'asmp',
   open_question: 'oq',
+  note: 'note',
 };
 
 // Required sections per node type — completeness scoring checks these
@@ -36,6 +37,7 @@ export const REQUIRED_SECTIONS = {
   flow: ['Description', 'Steps', 'Actors'],
   assumption: ['Description', 'Confidence', 'Depends On'],
   open_question: ['Description', 'Blocking', 'Affects'],
+  note: [],
 };
 
 // Valid edge relation types
@@ -330,7 +332,17 @@ export const SCORING_RULES = {
       check: (_fm, sections) => (sections['Affects'] || '').trim().length > 0,
     },
   ],
+  note: [
+    {
+      weight: 1.0,
+      description: 'Notes always have full completeness',
+      check: () => true,
+    },
+  ],
 };
 
+// Node types that should be excluded from the kanban board
+export const KANBAN_EXCLUDED_TYPES = new Set(['note']);
+
 // Optional sections that any node can have
 export const COMMON_OPTIONAL_SECTIONS = ['Resolved Questions', 'Notes', 'Relations'];

package/templates/assistkick-product-system/packages/shared/lib/embedding_service.test.ts

@@ -0,0 +1,75 @@
+import {describe, it} from 'node:test';
+import assert from 'node:assert/strict';
+import {buildEmbeddingText, cosineSimilarity, embed} from './embedding_service.js';
+
+describe('cosineSimilarity', () => {
+  it('returns 1.0 for identical vectors', () => {
+    const v = [0.1, 0.2, 0.3, 0.4];
+    const sim = cosineSimilarity(v, v);
+    assert.ok(Math.abs(sim - 1.0) < 0.0001, `Expected ~1.0, got ${sim}`);
+  });
+
+  it('returns 0.0 for orthogonal vectors', () => {
+    const a = [1, 0, 0];
+    const b = [0, 1, 0];
+    const sim = cosineSimilarity(a, b);
+    assert.ok(Math.abs(sim) < 0.0001, `Expected ~0.0, got ${sim}`);
+  });
+
+  it('returns -1.0 for opposite vectors', () => {
+    const a = [1, 0, 0];
+    const b = [-1, 0, 0];
+    const sim = cosineSimilarity(a, b);
+    assert.ok(Math.abs(sim - (-1.0)) < 0.0001, `Expected ~-1.0, got ${sim}`);
+  });
+});
+
+describe('buildEmbeddingText', () => {
+  it('returns just the name when no body', () => {
+    assert.equal(buildEmbeddingText('My Note', null), 'My Note');
+    assert.equal(buildEmbeddingText('My Note'), 'My Note');
+  });
+
+  it('combines name and body', () => {
+    const text = buildEmbeddingText('Auth Flow', '## Description\nHandles login');
+    assert.ok(text.includes('Auth Flow'));
+    assert.ok(text.includes('Handles login'));
+  });
+
+  it('strips section headers from body', () => {
+    const text = buildEmbeddingText('Test', '## Description\nSome content\n## Notes\nMore content');
+    assert.ok(!text.includes('## Description'));
+    assert.ok(!text.includes('## Notes'));
+    assert.ok(text.includes('Some content'));
+    assert.ok(text.includes('More content'));
+  });
+
+  it('truncates long body to 500 chars', () => {
+    const longBody = 'a'.repeat(1000);
+    const text = buildEmbeddingText('Name', longBody);
+    // name + newline + 500 chars
+    assert.ok(text.length <= 'Name'.length + 1 + 500);
+  });
+});
+
+describe('embed', () => {
+  it('returns a 384-dimensional vector', async () => {
+    const vector = await embed('JWT tokens expire after 24 hours');
+    assert.equal(vector.length, 384);
+    assert.equal(typeof vector[0], 'number');
+  });
+
+  it('produces similar vectors for related concepts', async () => {
+    const jwtVector = await embed('JWT tokens expire after 24 hours');
+    const authVector = await embed('authentication session duration');
+    const cookingVector = await embed('baking chocolate chip cookies');
+
+    const relatedSim = cosineSimilarity(jwtVector, authVector);
+    const unrelatedSim = cosineSimilarity(jwtVector, cookingVector);
+
+    assert.ok(relatedSim > unrelatedSim,
+      `Related similarity (${relatedSim}) should be > unrelated (${unrelatedSim})`);
+    assert.ok(relatedSim > 0.3,
+      `Related concepts should have similarity > 0.3, got ${relatedSim}`);
+  });
+});

package/templates/assistkick-product-system/packages/shared/lib/embedding_service.ts

@@ -0,0 +1,100 @@
+/**
+ * Embedding service — computes sentence embeddings locally using
+ * @huggingface/transformers with the all-MiniLM-L6-v2 ONNX model.
+ *
+ * Lazy-loads the model on first use (~1-2s). Subsequent calls are fast (~5-20ms).
+ * Embeddings are 384-dimensional Float32 vectors.
+ */
+
+import {eq, isNull} from 'drizzle-orm';
+
+const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
+
+let _pipeline: any = null;
+
+/**
+ * Get or create the feature-extraction pipeline (lazy singleton).
+ */
+const getPipeline = async () => {
+  if (_pipeline) return _pipeline;
+  const { pipeline } = await import('@huggingface/transformers');
+  _pipeline = await pipeline('feature-extraction', MODEL_NAME, {
+    dtype: 'fp32',
+  });
+  return _pipeline;
+};
+
+/**
+ * Compute a 384-dim embedding for the given text.
+ * Returns a plain number array suitable for JSON serialization.
+ */
+export const embed = async (text: string): Promise<number[]> => {
+  const pipe = await getPipeline();
+  const output = await pipe(text, { pooling: 'mean', normalize: true });
+  const data = output.tolist()[0] as number[];
+  return data;
+};
+
+/**
+ * Compute cosine similarity between two embedding vectors.
+ */
+export const cosineSimilarity = (a: number[], b: number[]): number => {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+};
+
+/**
+ * Build the text to embed for a node.
+ * For notes: just the name (one-liner).
+ * For other nodes: name + body content (truncated to ~500 chars for embedding quality).
+ */
+export const buildEmbeddingText = (name: string, body?: string | null): string => {
+  if (!body) return name;
+  const cleaned = body.replace(/^##\s+.+$/gm, '').replace(/\n{2,}/g, '\n').trim();
+  const truncated = cleaned.slice(0, 500);
+  return `${name}\n${truncated}`;
+};
+
+/**
+ * Compute and store the embedding for a node in the database.
+ */
+export const embedAndStore = async (nodeId: string, name: string, body?: string | null): Promise<void> => {
+  const { getDb } = await import('./db.js');
+  const { nodes } = await import('../db/schema.js');
+  const db = getDb();
+  const text = buildEmbeddingText(name, body);
+  const vector = await embed(text);
+  await db.update(nodes).set({ embedding: JSON.stringify(vector) }).where(eq(nodes.id, nodeId));
+};
+
+/**
+ * Backfill embeddings for all nodes that don't have one yet.
+ * Returns the number of nodes embedded.
+ */
+export const backfillEmbeddings = async (log?: (msg: string) => void): Promise<number> => {
+  const { getDb } = await import('./db.js');
+  const { nodes } = await import('../db/schema.js');
+  const db = getDb();
+
+  const rows = await db.select({ id: nodes.id, name: nodes.name, body: nodes.body })
+    .from(nodes)
+    .where(isNull(nodes.embedding));
+
+  let count = 0;
+  for (const row of rows) {
+    const text = buildEmbeddingText(row.name, row.body);
+    const vector = await embed(text);
+    await db.update(nodes).set({ embedding: JSON.stringify(vector) }).where(eq(nodes.id, row.id));
+    count++;
+    if (log) log(`  Embedded ${row.id} (${row.name})`);
+  }
+
+  return count;
+};

package/templates/assistkick-product-system/packages/shared/lib/relevance_search.ts

@@ -1,14 +1,17 @@
 /**
- * Graph-aware relevance search with ranking.
+ * Graph-aware relevance search with ranking and optional vector similarity.
  *
  * Algorithm:
  *   1. Direct matches — keyword substring in node name or body
- *   2. Graph expansion — 1-hop neighbors of each direct match via edges
- *   3. Rank by edge type weight — strong architectural signals score higher
- *   4. Deduplicate — keep highest relevance per node
- *   5. Cold start fallback — if zero direct matches, return top-5 most-connected per type
+ *   2. Vector similarity — semantic matches via embeddings (if available)
+ *   3. Graph expansion — 1-hop neighbors of each direct match via edges
+ *   4. Rank by combined score — direct > vector > graph neighbors
+ *   5. Deduplicate — keep highest relevance per node
+ *   6. Cold start fallback — if zero matches, return top-5 most-connected per type
  */
 
+import {cosineSimilarity} from './embedding_service.js';
+
 /** Edge types that carry strong architectural signal. */
 const STRONG_EDGES = new Set([
   'depends_on',
@@ -17,31 +20,13 @@ const STRONG_EDGES = new Set([
   'contains',
 ]);
 
-/**
- * @typedef {Object} RankedResult
- * @property {string} id
- * @property {string} name
- * @property {string} type
- * @property {string} status
- * @property {number} completeness
- * @property {number} open_questions_count
- * @property {string} relevance - 'direct' | 'via <sourceId> → <edgeType>' description
- * @property {number} _score - internal sort score (higher = more relevant)
- */
+/** Minimum cosine similarity to include a vector match. */
+const VECTOR_THRESHOLD = 0.25;
 
-/**
- * Run a relevance-ranked search over the graph.
- *
- * @param {string} keyword - search term (case-insensitive substring match)
- * @param {Array} allNodes - full node list from readGraph().nodes
- * @param {Array} allEdges - full edge list from readGraph().edges
- * @param {Function} getBody - async (nodeId) => string|null — fetches body content
- * @returns {Promise<RankedResult[]>} ranked results, direct first then neighbors
- */
-export const relevanceSearch = async (keyword, allNodes, allEdges, getBody) => {
+export const relevanceSearch = async (keyword, allNodes, allEdges, getBody, getEmbedding?) => {
   const q = keyword.toLowerCase();
 
-  // --- Step 1: direct matches ---
+  // --- Step 1: direct keyword matches ---
   const directMatches = [];
   for (const n of allNodes) {
     if (n.name.toLowerCase().includes(q)) {
@@ -54,14 +39,8 @@ export const relevanceSearch = async (keyword, allNodes, allEdges, getBody) => {
     }
   }
 
-  // --- Cold start fallback ---
-  if (directMatches.length === 0) {
-    return coldStartFallback(allNodes, allEdges);
-  }
-
   // Build a map for quick lookup
   const nodeMap = new Map(allNodes.map(n => [n.id, n]));
-  const directIds = new Set(directMatches.map(n => n.id));
 
   // Results keyed by node id → best RankedResult
   const resultsMap = new Map();
@@ -71,14 +50,47 @@ export const relevanceSearch = async (keyword, allNodes, allEdges, getBody) => {
     resultsMap.set(n.id, toResult(n, 'direct', 100));
   }
 
-  // --- Step 2: 1-hop graph expansion ---
-  for (const match of directMatches) {
-    const neighbors = getNeighbors(match.id, allEdges);
+  // --- Step 2: vector similarity matches ---
+  if (getEmbedding) {
+    try {
+      const { embed } = await import('./embedding_service.js');
+      const queryVector = await embed(keyword);
+
+      for (const n of allNodes) {
+        const nodeVector = await getEmbedding(n.id);
+        if (!nodeVector) continue;
+
+        const similarity = cosineSimilarity(queryVector, nodeVector);
+        if (similarity >= VECTOR_THRESHOLD) {
+          // Vector score: 0-80 range (below direct match's 100, above graph expansion's 50)
+          const score = Math.round(similarity * 80);
+          const label = `semantic (${(similarity * 100).toFixed(0)}%)`;
+
+          const existing = resultsMap.get(n.id);
+          if (!existing || existing._score < score) {
+            resultsMap.set(n.id, toResult(n, label, score));
+          }
+        }
+      }
+    } catch {
+      // Vector search unavailable — continue with keyword-only results
+    }
+  }
+
+  // --- Cold start fallback ---
+  if (resultsMap.size === 0) {
+    return coldStartFallback(allNodes, allEdges);
+  }
+
+  // --- Step 3: 1-hop graph expansion from direct + vector matches ---
+  const matchedIds = [...resultsMap.keys()];
+  for (const matchId of matchedIds) {
+    const neighbors = getNeighbors(matchId, allEdges);
     for (const { nodeId, edgeType, direction } of neighbors) {
       if (!nodeMap.has(nodeId)) continue;
       const isStrong = STRONG_EDGES.has(edgeType);
       const score = isStrong ? 50 : 20;
-      const label = `via ${match.id} ${direction} ${edgeType}`;
+      const label = `via ${matchId} ${direction} ${edgeType}`;
 
       const existing = resultsMap.get(nodeId);
       if (!existing || existing._score < score) {
@@ -87,7 +99,7 @@ export const relevanceSearch = async (keyword, allNodes, allEdges, getBody) => {
     }
   }
 
-  // --- Step 3: sort by score descending, then by id for stability ---
+  // --- Step 4: sort by score descending, then by id for stability ---
   const results = [...resultsMap.values()];
   results.sort((a, b) => b._score - a._score || a.id.localeCompare(b.id));
 

package/templates/assistkick-product-system/packages/shared/package.json

@@ -13,6 +13,7 @@
     "db:assign-project": "npx tsx scripts/assign-project.ts --"
   },
   "dependencies": {
+    "@huggingface/transformers": "^3.8.1",
     "@libsql/client": "^0.17.0",
     "chalk": "^5.3.0",
     "commander": "^11.0.0",

package/templates/assistkick-product-system/packages/shared/tools/add_node.ts

@@ -9,12 +9,13 @@ import { program } from 'commander';
 import chalk from 'chalk';
 import { randomBytes } from 'node:crypto';
 import { eq } from 'drizzle-orm';
-import { NODE_TYPES, VALID_FEATURE_KINDS } from '../lib/constants.js';
+import { NODE_TYPES, VALID_FEATURE_KINDS, KANBAN_EXCLUDED_TYPES } from '../lib/constants.js';
 import { getDb } from '../lib/db.js';
 import { nodes, projects } from '../db/schema.js';
 import { deriveMetadata, templateSections } from '../lib/markdown.js';
 import { assertValidType, assertUniqueName } from '../lib/validator.js';
 import { saveKanbanEntry } from '../lib/kanban.js';
+import { embedAndStore } from '../lib/embedding_service.js';
 
 program
   .requiredOption('--type <type>', 'Node type (e.g., feature, component, decision)')
@@ -97,12 +98,19 @@ const opts = program.opts();
       projectId: opts.projectId,
     });
 
-    // Auto-add features to the kanban backlog
-    if (opts.type === 'feature') {
+    // Auto-add features to the kanban backlog (skip excluded types like notes)
+    if (opts.type === 'feature' && !KANBAN_EXCLUDED_TYPES.has(opts.type)) {
       await saveKanbanEntry(id, { column: 'backlog', rejection_count: 0, notes: [], reviews: [] }, opts.projectId);
       console.log(chalk.green(`✓ Added ${id} to kanban backlog`));
     }
 
+    // Compute and store embedding
+    try {
+      await embedAndStore(id, opts.name, body);
+    } catch (embErr: any) {
+      console.log(chalk.yellow(`⚠ Embedding skipped: ${embErr.message}`));
+    }
+
     console.log(chalk.green(`✓ Created ${opts.type} node: ${id}`));
     console.log(JSON.stringify({ id, type: opts.type, name: opts.name }));
   } catch (err) {

package/templates/assistkick-product-system/packages/shared/tools/delete_note.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * delete_note — Removes a note node and all its edges from the knowledge graph.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { eq, or } from 'drizzle-orm';
+import { getDb } from '../lib/db.js';
+import { nodes, edges } from '../db/schema.js';
+
+program
+  .argument('<id>', 'Note node ID to delete (e.g. note_a1b2c3d4)')
+  .requiredOption('--project-id <id>', 'Project ID')
+  .parse();
+
+const [id] = program.args;
+
+(async () => {
+  try {
+    const db = getDb();
+
+    // Verify node exists and is a note
+    const rows = await db.select({ id: nodes.id, type: nodes.type, name: nodes.name })
+      .from(nodes)
+      .where(eq(nodes.id, id));
+
+    if (!rows[0]) {
+      throw new Error(`Node not found: ${id}`);
+    }
+    if (rows[0].type !== 'note') {
+      throw new Error(`Node ${id} is a ${rows[0].type}, not a note. Use remove_node for non-note nodes.`);
+    }
+
+    const noteName = rows[0].name;
+
+    // Delete edges and node in a transaction
+    await db.transaction(async (tx) => {
+      await tx.delete(edges).where(or(eq(edges.fromId, id), eq(edges.toId, id)));
+      await tx.delete(nodes).where(eq(nodes.id, id));
+    });
+
+    console.log(chalk.green(`✓ Deleted note: ${id}`));
+    console.log(JSON.stringify({ id, name: noteName, deleted: true }));
+  } catch (err: any) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

package/templates/assistkick-product-system/packages/shared/tools/save_note.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+/**
+ * save_note — Creates a lightweight note node in the knowledge graph.
+ * Notes are one-liner memories stored as the node name, with optional tags
+ * and edges to related nodes.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { randomBytes } from 'node:crypto';
+import { getDb } from '../lib/db.js';
+import { nodes, edges } from '../db/schema.js';
+import { embedAndStore } from '../lib/embedding_service.js';
+import { assertNodeExists } from '../lib/validator.js';
+
+program
+  .requiredOption('--project-id <id>', 'Project ID')
+  .requiredOption('--content <text>', 'The note content (one-liner)')
+  .option('--tags <tags>', 'Comma-separated tags (e.g. "auth,security")')
+  .option('--relates-to <nodeIds>', 'Comma-separated node IDs to create relates_to edges')
+  .parse();
+
+const opts = program.opts();
+
+(async () => {
+  try {
+    const id = `note_${randomBytes(4).toString('hex')}`;
+    const now = new Date().toISOString();
+
+    // Build body from tags if provided
+    let body = '';
+    if (opts.tags) {
+      body = `## Tags\n${opts.tags.split(',').map((t: string) => t.trim()).join(', ')}\n`;
+    }
+
+    // Insert the note node
+    const db = getDb();
+    await db.insert(nodes).values({
+      id,
+      type: 'note',
+      name: opts.content,
+      status: 'defined',
+      priority: 'low',
+      completeness: 1.0,
+      openQuestionsCount: 0,
+      kind: null,
+      featureType: null,
+      createdAt: now,
+      updatedAt: now,
+      body: body || null,
+      projectId: opts.projectId,
+    });
+
+    // Create edges to related nodes
+    if (opts.relatesTo) {
+      const relatedIds = opts.relatesTo.split(',').map((s: string) => s.trim());
+      for (const targetId of relatedIds) {
+        await assertNodeExists(targetId);
+        await db.insert(edges).values({
+          fromId: id,
+          relation: 'relates_to',
+          toId: targetId,
+          projectId: opts.projectId,
+        });
+        console.log(chalk.gray(`  + edge: ${id} --relates_to--> ${targetId}`));
+      }
+    }
+
+    // Compute and store embedding
+    await embedAndStore(id, opts.content, body || null);
+
+    console.log(chalk.green(`✓ Saved note: ${id}`));
+    console.log(JSON.stringify({ id, type: 'note', content: opts.content }));
+  } catch (err: any) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

package/templates/assistkick-product-system/packages/shared/tools/search_nodes.ts

@@ -43,8 +43,13 @@ const opts = program.opts();
         const rows = await db.select({ body: nodes.body }).from(nodes).where(eq(nodes.id, nodeId));
         return rows[0]?.body ?? null;
       };
+      const getEmbedding = async (nodeId) => {
+        const rows = await db.select({ embedding: nodes.embedding }).from(nodes).where(eq(nodes.id, nodeId));
+        const raw = rows[0]?.embedding;
+        return raw ? JSON.parse(raw) : null;
+      };
 
-      results = await relevanceSearch(opts.query, graph.nodes, graph.edges, getBody);
+      results = await relevanceSearch(opts.query, graph.nodes, graph.edges, getBody, getEmbedding);
     } else {
       // No keyword — return all nodes without relevance (backward compat)
       results = graph.nodes.map(n => ({

package/templates/assistkick-product-system/packages/shared/tools/search_notes.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+
+/**
+ * search_notes — Semantic vector search across all graph nodes.
+ *
+ * Embeds the query using the same model, then computes cosine similarity
+ * against all nodes with embeddings. Returns results ranked by relevance.
+ * Works across all node types, not just notes.
+ */
+
+import { program } from 'commander';
+import chalk from 'chalk';
+import { eq } from 'drizzle-orm';
+import { getDb } from '../lib/db.js';
+import { nodes } from '../db/schema.js';
+import { embed, cosineSimilarity } from '../lib/embedding_service.js';
+
+program
+  .requiredOption('--project-id <id>', 'Project ID')
+  .requiredOption('--query <text>', 'Search query (semantic search)')
+  .option('--type <type>', 'Filter by node type (e.g. "note", "feature")')
+  .option('--limit <n>', 'Max results to return', '10')
+  .option('--threshold <n>', 'Minimum similarity score (0-1)', '0.25')
+  .parse();
+
+const opts = program.opts();
+
+(async () => {
+  try {
+    const db = getDb();
+    const limit = parseInt(opts.limit, 10);
+    const threshold = parseFloat(opts.threshold);
+
+    // Load all nodes with embeddings for this project
+    const allNodes = await db.select({
+      id: nodes.id,
+      name: nodes.name,
+      type: nodes.type,
+      status: nodes.status,
+      completeness: nodes.completeness,
+      openQuestionsCount: nodes.openQuestionsCount,
+      embedding: nodes.embedding,
+    }).from(nodes).where(eq(nodes.projectId, opts.projectId));
+
+    // Embed the query
+    const queryVector = await embed(opts.query);
+
+    // Score each node
+    const scored: Array<{
+      id: string;
+      name: string;
+      type: string;
+      status: string;
+      completeness: number;
+      open_questions_count: number;
+      similarity: number;
+    }> = [];
+
+    for (const node of allNodes) {
+      if (!node.embedding) continue;
+      if (opts.type && node.type !== opts.type) continue;
+
+      const nodeVector = JSON.parse(node.embedding) as number[];
+      const similarity = cosineSimilarity(queryVector, nodeVector);
+
+      if (similarity >= threshold) {
+        scored.push({
+          id: node.id,
+          name: node.name,
+          type: node.type,
+          status: node.status,
+          completeness: node.completeness,
+          open_questions_count: node.openQuestionsCount,
+          similarity: Math.round(similarity * 1000) / 1000,
+        });
+      }
+    }
+
+    // Sort by similarity descending
+    scored.sort((a, b) => b.similarity - a.similarity);
+    const results = scored.slice(0, limit);
+
+    if (results.length === 0) {
+      console.log(chalk.yellow('No matching nodes found above threshold.'));
+    } else {
+      console.log(chalk.cyan(`Found ${results.length} result(s):\n`));
+      for (const r of results) {
+        const simBar = chalk.green('█'.repeat(Math.round(r.similarity * 10)));
+        const simPad = chalk.gray('░'.repeat(10 - Math.round(r.similarity * 10)));
+        console.log(`  ${chalk.bold(r.id)} ${r.name} [${r.type}] ${simBar}${simPad} ${(r.similarity * 100).toFixed(1)}%`);
+      }
+    }
+
+    console.log('\n' + JSON.stringify(results));
+  } catch (err: any) {
+    console.error(chalk.red(`Error: ${err.message}`));
+    process.exit(1);
+  }
+})();