stellavault 0.7.1 → 0.7.3

package/README.md

@@ -232,9 +232,10 @@ node tests/stress.mjs 500     # Test with 500 synthetic documents
 ```
 
 Key optimizations:
+- **HNSW graph building** — sqlite-vec KNN for 200+ docs (O(n·K·log n) vs O(n²))
 - Pre-normalized vectors: cosine similarity → single dot product
 - Batched embedding loading (500/batch, prevents RAM overflow)
-- Upper-triangle graph building (50% fewer comparisons)
+- Upper-triangle brute-force for small vaults (< 200 docs)
 - O(n) K-Means centroid updates with typed arrays
 
 ---

package/dist/stellavault.js

@@ -645,33 +645,50 @@ async function buildGraphData(store, options = {}) {
   ]);
   const edges = [];
   const edgeCounts = /* @__PURE__ */ new Map();
-  const normalizedVecs = /* @__PURE__ */ new Map();
-  for (const doc of docs) {
-    const vec = embeddings.get(doc.id);
-    if (!vec)
-      continue;
-    normalizedVecs.set(doc.id, normalizeVector([...vec]));
-  }
-  const docIds = [...normalizedVecs.keys()];
-  const vecArray = docIds.map((id) => normalizedVecs.get(id));
-  const n = docIds.length;
-  const neighbors = Array.from({ length: n }, () => []);
-  for (let i = 0; i < n; i++) {
-    for (let j = i + 1; j < n; j++) {
-      const sim = dotProduct(vecArray[i], vecArray[j]);
-      if (sim >= edgeThreshold) {
-        neighbors[i].push({ peer: j, sim });
-        neighbors[j].push({ peer: i, sim });
+  const USE_HNSW_THRESHOLD = 200;
+  const docsWithVecs = docs.filter((d) => embeddings.has(d.id));
+  if (docsWithVecs.length > USE_HNSW_THRESHOLD) {
+    for (const doc of docsWithVecs) {
+      const vec = embeddings.get(doc.id);
+      const neighbors = await store.findDocumentNeighbors(vec, maxEdgesPerNode + 1);
+      for (const { documentId: targetId, similarity } of neighbors) {
+        if (targetId === doc.id)
+          continue;
+        if (similarity < edgeThreshold)
+          continue;
+        const edgeKey = [doc.id, targetId].sort().join(":");
+        if (!edgeCounts.has(edgeKey)) {
+          edges.push({ source: doc.id, target: targetId, weight: similarity });
+          edgeCounts.set(edgeKey, 1);
+        }
       }
     }
-  }
-  for (let i = 0; i < n; i++) {
-    neighbors[i].sort((a, b) => b.sim - a.sim);
-    for (const { peer: j, sim } of neighbors[i].slice(0, maxEdgesPerNode)) {
-      const edgeKey = i < j ? `${i}:${j}` : `${j}:${i}`;
-      if (!edgeCounts.has(edgeKey)) {
-        edges.push({ source: docIds[i], target: docIds[j], weight: sim });
-        edgeCounts.set(edgeKey, 1);
+  } else {
+    const normalizedVecs = /* @__PURE__ */ new Map();
+    for (const doc of docsWithVecs) {
+      normalizedVecs.set(doc.id, normalizeVector([...embeddings.get(doc.id)]));
+    }
+    const docIds = [...normalizedVecs.keys()];
+    const vecArray = docIds.map((id) => normalizedVecs.get(id));
+    const n = docIds.length;
+    const neighbors = Array.from({ length: n }, () => []);
+    for (let i = 0; i < n; i++) {
+      for (let j = i + 1; j < n; j++) {
+        const sim = dotProduct(vecArray[i], vecArray[j]);
+        if (sim >= edgeThreshold) {
+          neighbors[i].push({ peer: j, sim });
+          neighbors[j].push({ peer: i, sim });
+        }
+      }
+    }
+    for (let i = 0; i < n; i++) {
+      neighbors[i].sort((a, b) => b.sim - a.sim);
+      for (const { peer: j, sim } of neighbors[i].slice(0, maxEdgesPerNode)) {
+        const edgeKey = i < j ? `${i}:${j}` : `${j}:${i}`;
+        if (!edgeCounts.has(edgeKey)) {
+          edges.push({ source: docIds[i], target: docIds[j], weight: sim });
+          edgeCounts.set(edgeKey, 1);
+        }
       }
     }
   }
@@ -705,16 +722,16 @@ async function buildGraphData(store, options = {}) {
       nodeCount: folderCounts.get(i) ?? 0
     }));
   } else {
-    const docIds2 = docs.filter((d) => embeddings.has(d.id)).map((d) => d.id);
-    const vectors = docIds2.map((id) => embeddings.get(id));
-    const k = Math.min(Math.max(5, Math.round(Math.sqrt(docIds2.length / 5))), 10);
+    const docIds = docs.filter((d) => embeddings.has(d.id)).map((d) => d.id);
+    const vectors = docIds.map((id) => embeddings.get(id));
+    const k = Math.min(Math.max(5, Math.round(Math.sqrt(docIds.length / 5))), 10);
     const assignments = kMeans(vectors, k);
     const clusterDocInfos = /* @__PURE__ */ new Map();
-    for (let i = 0; i < docIds2.length; i++) {
+    for (let i = 0; i < docIds.length; i++) {
       const cId = assignments[i];
       if (!clusterDocInfos.has(cId))
         clusterDocInfos.set(cId, []);
-      const doc = docs.find((d) => d.id === docIds2[i]);
+      const doc = docs.find((d) => d.id === docIds[i]);
       if (doc)
         clusterDocInfos.get(cId).push({ id: doc.id, title: doc.title });
     }
@@ -735,8 +752,8 @@ async function buildGraphData(store, options = {}) {
       });
     }
     assignmentMap = /* @__PURE__ */ new Map();
-    for (let i = 0; i < docIds2.length; i++) {
-      assignmentMap.set(docIds2[i], assignments[i]);
+    for (let i = 0; i < docIds.length; i++) {
+      assignmentMap.set(docIds[i], assignments[i]);
     }
   }
   const connectionCounts = /* @__PURE__ */ new Map();
@@ -3258,6 +3275,21 @@ function createSqliteVecStore(dbPath, dimensions = 384) {
       }
       return result;
     },
+    async findDocumentNeighbors(embedding, limit) {
+      const rows = db.prepare(`
+        SELECT c.document_id, MIN(ce.distance) as distance
+        FROM chunk_embeddings ce
+        JOIN chunks c ON c.id = ce.chunk_id
+        WHERE ce.embedding MATCH ?
+        GROUP BY c.document_id
+        ORDER BY distance
+        LIMIT ?
+      `).all(float32Buffer(embedding), limit * 2);
+      return rows.slice(0, limit).map((r) => ({
+        documentId: r.document_id,
+        similarity: 1 / (1 + r.distance)
+      }));
+    },
     async close() {
       db.close();
     },
@@ -4746,7 +4778,7 @@ function createMcpServer(options) {
   const askTool = createAskTool(searchEngine, vaultPath);
   const generateDraftTool = createGenerateDraftTool(searchEngine, vaultPath);
   const agenticTools = embedder ? createAgenticGraphTools(store, embedder, vaultPath) : [];
-  const server = new Server({ name: "stellavault", version: "0.7.1" }, { capabilities: { tools: {} } });
+  const server = new Server({ name: "stellavault", version: "0.7.3" }, { capabilities: { tools: {} } });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
       searchToolDef,
@@ -5608,6 +5640,250 @@ ${content}`;
   return router;
 }
 
+// packages/core/dist/api/routes/profile-card.js
+init_graph_data();
+import { Router as Router4 } from "express";
+function createProfileCardRouter(opts) {
+  const { store, graphCaches, GRAPH_CACHE_TTL } = opts;
+  const router = Router4();
+  router.get("/profile-card", async (_req, res) => {
+    try {
+      const mode = String(_req.query.mode ?? "") === "folder" ? "folder" : "semantic";
+      const cached = graphCaches.get(mode);
+      if (!cached || Date.now() - cached.cachedAt > GRAPH_CACHE_TTL) {
+        const data = await buildGraphData(store, { mode });
+        graphCaches.set(mode, { data, generatedAt: (/* @__PURE__ */ new Date()).toISOString(), cachedAt: Date.now() });
+      }
+      const graphData = graphCaches.get(mode).data;
+      const topics = await store.getTopics();
+      const stats = await store.getStats();
+      const top6 = [...graphData.clusters].sort((a, b) => b.nodeCount - a.nodeCount).slice(0, 6);
+      const maxCount = Math.max(1, ...top6.map((c) => c.nodeCount));
+      const W = 800, H = 420;
+      const radarCx = 200, radarCy = 220, radarR = 100;
+      const radarPoints = top6.map((c, i) => {
+        const angle = Math.PI * 2 * i / top6.length - Math.PI / 2;
+        const r = radarR * (c.nodeCount / maxCount);
+        return {
+          x: radarCx + r * Math.cos(angle),
+          y: radarCy + r * Math.sin(angle),
+          lx: radarCx + (radarR + 20) * Math.cos(angle),
+          ly: radarCy + (radarR + 20) * Math.sin(angle),
+          label: c.label.split(",")[0].trim().slice(0, 12),
+          color: c.color
+        };
+      });
+      const radarPath = radarPoints.map((p, i) => `${i === 0 ? "M" : "L"}${p.x},${p.y}`).join(" ") + "Z";
+      const gridPaths = [0.33, 0.66, 1].map((s) => top6.map((_, i) => {
+        const a = Math.PI * 2 * i / top6.length - Math.PI / 2;
+        return `${i === 0 ? "M" : "L"}${radarCx + radarR * s * Math.cos(a)},${radarCy + radarR * s * Math.sin(a)}`;
+      }).join(" ") + "Z");
+      const tags20 = topics.slice(0, 20);
+      const maxTag = Math.max(1, ...tags20.map((t2) => t2.count));
+      const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+      const tagEls = tags20.map((t2, i) => {
+        const sz = 10 + 14 * (t2.count / maxTag);
+        const x = 480 + Math.floor(i / 2) % 5 * 60;
+        const y = 140 + i % 2 * 30 + Math.floor(i / 10) * 70;
+        const op = 0.5 + 0.5 * (t2.count / maxTag);
+        return `<text x="${x}" y="${y}" font-size="${sz}" fill="#88aaff" opacity="${op}" font-family="monospace">#${esc(t2.topic)}</text>`;
+      }).join("\n    ");
+      const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#0d1028"/><stop offset="100%" stop-color="#050510"/>
+    </linearGradient>
+    <linearGradient id="rf" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#6366f1" stop-opacity="0.3"/><stop offset="100%" stop-color="#06b6d4" stop-opacity="0.15"/>
+    </linearGradient>
+  </defs>
+  <rect width="${W}" height="${H}" rx="16" fill="url(#bg)"/>
+  <rect width="${W}" height="${H}" rx="16" fill="none" stroke="#6366f140"/>
+  <text x="30" y="40" font-size="20" font-weight="700" fill="#c0c0f0" font-family="system-ui">\u{1F9E0} Knowledge Universe</text>
+  <text x="30" y="65" font-size="13" fill="#556" font-family="monospace">${stats.documentCount} docs \xB7 ${graphData.clusters.length} clusters \xB7 ${graphData.edges.length} connections</text>
+  <line x1="30" y1="80" x2="${W - 30}" y2="80" stroke="#6366f120"/>
+  <text x="${radarCx}" y="105" font-size="11" fill="#667" text-anchor="middle" font-family="system-ui">KNOWLEDGE DISTRIBUTION</text>
+  ${gridPaths.map((p) => `<path d="${p}" fill="none" stroke="#6366f115" stroke-width="0.5"/>`).join("\n  ")}
+  ${radarPoints.map((p) => `<line x1="${radarCx}" y1="${radarCy}" x2="${p.lx}" y2="${p.ly}" stroke="#6366f110" stroke-width="0.5"/>`).join("\n  ")}
+  <path d="${radarPath}" fill="url(#rf)" stroke="#818cf8" stroke-width="1.5"/>
+  ${radarPoints.map((p) => `<circle cx="${p.x}" cy="${p.y}" r="3" fill="${p.color}"/><text x="${p.lx}" y="${p.ly + 4}" font-size="9" fill="#889" text-anchor="middle" font-family="monospace">${esc(p.label)}</text>`).join("\n  ")}
+  <text x="580" y="105" font-size="11" fill="#667" text-anchor="middle" font-family="system-ui">TOP TOPICS</text>
+  <rect x="440" y="115" width="320" height="240" rx="8" fill="#6366f108"/>
+    ${tagEls}
+  <text x="${W / 2}" y="${H - 15}" font-size="10" fill="#334" text-anchor="middle" font-family="monospace">Generated by Stellavault</text>
+</svg>`;
+      res.setHeader("Content-Type", "image/svg+xml");
+      res.send(svg);
+    } catch (err) {
+      console.error(err);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  });
+  return router;
+}
+
+// packages/core/dist/api/routes/health.js
+import { Router as Router5 } from "express";
+function createHealthRouter(opts) {
+  const { store, vaultName, decayEngine } = opts;
+  const router = Router5();
+  router.get("/health", async (_req, res) => {
+    try {
+      const stats = await store.getStats();
+      const docs = await store.getAllDocuments();
+      let decaySummary = { totalDocuments: 0, criticalCount: 0, decayingCount: 0, averageR: 1, topDecaying: [] };
+      if (decayEngine) {
+        const report = await decayEngine.computeAll();
+        decaySummary = {
+          totalDocuments: report.totalDocuments ?? docs.length,
+          criticalCount: report.criticalCount ?? 0,
+          decayingCount: report.decayingCount ?? 0,
+          averageR: report.averageR ?? 1,
+          topDecaying: (report.topDecaying ?? []).slice(0, 5)
+        };
+      }
+      let gapSummary = { gapCount: 0, isolatedCount: 0 };
+      try {
+        const { detectKnowledgeGaps: detectKnowledgeGaps2 } = await Promise.resolve().then(() => (init_gap_detector(), gap_detector_exports));
+        const gapReport = await detectKnowledgeGaps2(store);
+        gapSummary = {
+          gapCount: gapReport.gaps?.length ?? 0,
+          isolatedCount: gapReport.isolatedNodes?.length ?? 0
+        };
+      } catch (e) {
+        console.error("[health] Gap detection failed:", e instanceof Error ? e.message : e);
+      }
+      let dupCount = 0;
+      try {
+        const { detectDuplicates: detectDuplicates2 } = await Promise.resolve().then(() => (init_duplicate_detector(), duplicate_detector_exports));
+        const pairs = await detectDuplicates2(store, 0.88, 50);
+        dupCount = pairs.length;
+      } catch (e) {
+        console.error("[health] Duplicate detection failed:", e instanceof Error ? e.message : e);
+      }
+      const sourceDist = /* @__PURE__ */ new Map();
+      const typeDist = /* @__PURE__ */ new Map();
+      for (const doc of docs) {
+        const s = doc.source ?? "local";
+        const t2 = doc.type ?? "note";
+        sourceDist.set(s, (sourceDist.get(s) ?? 0) + 1);
+        typeDist.set(t2, (typeDist.get(t2) ?? 0) + 1);
+      }
+      const monthlyGrowth = /* @__PURE__ */ new Map();
+      for (const doc of docs) {
+        const month = doc.lastModified?.slice(0, 7) ?? "unknown";
+        monthlyGrowth.set(month, (monthlyGrowth.get(month) ?? 0) + 1);
+      }
+      res.json({
+        stats: { ...stats, vaultName },
+        decay: decaySummary,
+        gaps: gapSummary,
+        duplicates: { count: dupCount },
+        distribution: {
+          source: Object.fromEntries(sourceDist),
+          type: Object.fromEntries(typeDist)
+        },
+        growth: Object.fromEntries([...monthlyGrowth.entries()].sort((a, b) => a[0].localeCompare(b[0])))
+      });
+    } catch (err) {
+      console.error(err);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  });
+  return router;
+}
+
+// packages/core/dist/api/routes/analytics.js
+init_graph_data();
+import { Router as Router6 } from "express";
+function createAnalyticsRouter(opts) {
+  const { store, vaultName, decayEngine, graphCaches, GRAPH_CACHE_TTL } = opts;
+  const router = Router6();
+  router.get("/profile", async (_req, res) => {
+    try {
+      const stats = await store.getStats();
+      const topics = await store.getTopics();
+      const docs = await store.getAllDocuments();
+      let decaySummary = { averageR: 1, criticalCount: 0, healthScore: 100 };
+      if (decayEngine) {
+        const report = await decayEngine.computeAll();
+        const avgR = report.averageR ?? 1;
+        decaySummary = { averageR: avgR, criticalCount: report.criticalCount ?? 0, healthScore: Math.round(avgR * 100) };
+      }
+      const sourceDist = {};
+      const typeDist = {};
+      for (const doc of docs) {
+        sourceDist[doc.source ?? "local"] = (sourceDist[doc.source ?? "local"] ?? 0) + 1;
+        typeDist[doc.type ?? "note"] = (typeDist[doc.type ?? "note"] ?? 0) + 1;
+      }
+      const monthlyActivity = {};
+      for (const doc of docs) {
+        const month = doc.lastModified?.slice(0, 7);
+        if (month)
+          monthlyActivity[month] = (monthlyActivity[month] ?? 0) + 1;
+      }
+      res.json({
+        name: vaultName || "Knowledge Vault",
+        stats: { documents: stats.documentCount, chunks: stats.chunkCount, topics: topics.length },
+        healthScore: decaySummary.healthScore,
+        topTopics: topics.slice(0, 15).map((t2) => ({ name: t2.topic, count: t2.count })),
+        distribution: { source: sourceDist, type: typeDist },
+        activity: Object.fromEntries(Object.entries(monthlyActivity).sort((a, b) => a[0].localeCompare(b[0])).slice(-12)),
+        generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch (err) {
+      console.error(err);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  });
+  router.get("/embed", async (req, res) => {
+    try {
+      const mode = req.query.mode === "folder" ? "folder" : "semantic";
+      const maxNodes = Math.min(parseInt(String(req.query.max ?? "200"), 10), 500);
+      const cached = graphCaches.get(mode);
+      if (!cached || Date.now() - cached.cachedAt > GRAPH_CACHE_TTL) {
+        const data = await buildGraphData(store, { mode });
+        graphCaches.set(mode, { data, generatedAt: (/* @__PURE__ */ new Date()).toISOString(), cachedAt: Date.now() });
+      }
+      const { nodes, edges, clusters } = graphCaches.get(mode).data;
+      const connCount = /* @__PURE__ */ new Map();
+      for (const e of edges) {
+        connCount.set(e.source, (connCount.get(e.source) ?? 0) + 1);
+        connCount.set(e.target, (connCount.get(e.target) ?? 0) + 1);
+      }
+      const sortedNodes = [...nodes].sort((a, b) => (connCount.get(b.id) ?? 0) - (connCount.get(a.id) ?? 0));
+      const selectedNodes = sortedNodes.slice(0, maxNodes);
+      const selectedIds = new Set(selectedNodes.map((n) => n.id));
+      const selectedEdges = edges.filter((e) => selectedIds.has(e.source) && selectedIds.has(e.target));
+      const embedNodes = selectedNodes.map((n, i) => {
+        const angle = i / selectedNodes.length * Math.PI * 2;
+        const r = 100 + n.clusterId * 15;
+        return {
+          id: n.id,
+          label: n.label,
+          clusterId: n.clusterId,
+          size: n.size,
+          position: [
+            r * Math.cos(angle) + (Math.random() - 0.5) * 60,
+            (Math.random() - 0.5) * 200,
+            r * Math.sin(angle) + (Math.random() - 0.5) * 60
+          ]
+        };
+      });
+      res.json({
+        nodes: embedNodes,
+        edges: selectedEdges,
+        stats: { nodeCount: embedNodes.length, edgeCount: selectedEdges.length, clusterCount: clusters.length, totalNodes: nodes.length },
+        title: vaultName || "Knowledge Graph"
+      });
+    } catch (err) {
+      console.error(err);
+      res.status(500).json({ error: "Internal server error" });
+    }
+  });
+  return router;
+}
+
 // packages/core/dist/api/server.js
 function createApiServer(options) {
   const { store, searchEngine, port = 3333, vaultName = "", vaultPath = "", decayEngine, graphUiPath } = options;
@@ -5808,79 +6084,7 @@ function createApiServer(options) {
       res.status(500).json({ error: "Internal server error" });
     }
   });
-  app.get("/api/profile-card", async (_req, res) => {
-    try {
-      const mode = String(_req.query.mode ?? "") === "folder" ? "folder" : "semantic";
-      const cachedProfile = graphCaches.get(mode);
-      if (!cachedProfile || Date.now() - cachedProfile.cachedAt > GRAPH_CACHE_TTL) {
-        const data = await buildGraphData(store, { mode });
-        graphCaches.set(mode, { data, generatedAt: (/* @__PURE__ */ new Date()).toISOString(), cachedAt: Date.now() });
-      }
-      const graphData = graphCaches.get(mode).data;
-      const topics = await store.getTopics();
-      const stats = await store.getStats();
-      const top6 = [...graphData.clusters].sort((a, b) => b.nodeCount - a.nodeCount).slice(0, 6);
-      const maxCount = Math.max(1, ...top6.map((c) => c.nodeCount));
-      const W = 800, H = 420;
-      const radarCx = 200, radarCy = 220, radarR = 100;
-      const radarPoints = top6.map((c, i) => {
-        const angle = Math.PI * 2 * i / top6.length - Math.PI / 2;
-        const r = radarR * (c.nodeCount / maxCount);
-        return {
-          x: radarCx + r * Math.cos(angle),
-          y: radarCy + r * Math.sin(angle),
-          lx: radarCx + (radarR + 20) * Math.cos(angle),
-          ly: radarCy + (radarR + 20) * Math.sin(angle),
-          label: c.label.split(",")[0].trim().slice(0, 12),
-          color: c.color
-        };
-      });
-      const radarPath = radarPoints.map((p, i) => `${i === 0 ? "M" : "L"}${p.x},${p.y}`).join(" ") + "Z";
-      const gridPaths = [0.33, 0.66, 1].map((s) => top6.map((_, i) => {
-        const a = Math.PI * 2 * i / top6.length - Math.PI / 2;
-        return `${i === 0 ? "M" : "L"}${radarCx + radarR * s * Math.cos(a)},${radarCy + radarR * s * Math.sin(a)}`;
-      }).join(" ") + "Z");
-      const tags20 = topics.slice(0, 20);
-      const maxTag = Math.max(1, ...tags20.map((t2) => t2.count));
-      const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-      const tagEls = tags20.map((t2, i) => {
-        const sz = 10 + 14 * (t2.count / maxTag);
-        const x = 480 + Math.floor(i / 2) % 5 * 60;
-        const y = 140 + i % 2 * 30 + Math.floor(i / 10) * 70;
-        const op = 0.5 + 0.5 * (t2.count / maxTag);
-        return `<text x="${x}" y="${y}" font-size="${sz}" fill="#88aaff" opacity="${op}" font-family="monospace">#${esc(t2.topic)}</text>`;
-      }).join("\n    ");
-      const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}">
-  <defs>
-    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
-      <stop offset="0%" stop-color="#0d1028"/><stop offset="100%" stop-color="#050510"/>
-    </linearGradient>
-    <linearGradient id="rf" x1="0%" y1="0%" x2="100%" y2="100%">
-      <stop offset="0%" stop-color="#6366f1" stop-opacity="0.3"/><stop offset="100%" stop-color="#06b6d4" stop-opacity="0.15"/>
-    </linearGradient>
-  </defs>
-  <rect width="${W}" height="${H}" rx="16" fill="url(#bg)"/>
-  <rect width="${W}" height="${H}" rx="16" fill="none" stroke="#6366f140"/>
-  <text x="30" y="40" font-size="20" font-weight="700" fill="#c0c0f0" font-family="system-ui">\u{1F9E0} Knowledge Universe</text>
-  <text x="30" y="65" font-size="13" fill="#556" font-family="monospace">${stats.documentCount} docs \xB7 ${graphData.clusters.length} clusters \xB7 ${graphData.edges.length} connections</text>
-  <line x1="30" y1="80" x2="${W - 30}" y2="80" stroke="#6366f120"/>
-  <text x="${radarCx}" y="105" font-size="11" fill="#667" text-anchor="middle" font-family="system-ui">KNOWLEDGE DISTRIBUTION</text>
-  ${gridPaths.map((p) => `<path d="${p}" fill="none" stroke="#6366f115" stroke-width="0.5"/>`).join("\n  ")}
-  ${radarPoints.map((p) => `<line x1="${radarCx}" y1="${radarCy}" x2="${p.lx}" y2="${p.ly}" stroke="#6366f110" stroke-width="0.5"/>`).join("\n  ")}
-  <path d="${radarPath}" fill="url(#rf)" stroke="#818cf8" stroke-width="1.5"/>
-  ${radarPoints.map((p) => `<circle cx="${p.x}" cy="${p.y}" r="3" fill="${p.color}"/><text x="${p.lx}" y="${p.ly + 4}" font-size="9" fill="#889" text-anchor="middle" font-family="monospace">${esc(p.label)}</text>`).join("\n  ")}
-  <text x="580" y="105" font-size="11" fill="#667" text-anchor="middle" font-family="system-ui">TOP TOPICS</text>
-  <rect x="440" y="115" width="320" height="240" rx="8" fill="#6366f108"/>
-    ${tagEls}
-  <text x="${W / 2}" y="${H - 15}" font-size="10" fill="#334" text-anchor="middle" font-family="monospace">Generated by Stellavault</text>
-</svg>`;
-      res.setHeader("Content-Type", "image/svg+xml");
-      res.send(svg);
-    } catch (err) {
-      console.error(err);
-      res.status(500).json({ error: "Internal server error" });
-    }
-  });
+  app.use("/api", createProfileCardRouter({ store, graphCaches, GRAPH_CACHE_TTL }));
   app.get("/api/stats", async (_req, res) => {
     try {
       const stats = await store.getStats();
@@ -6076,162 +6280,8 @@ function createApiServer(options) {
     }
   });
   app.use("/api", createKnowledgeRouter({ store, searchEngine, vaultPath, requireAuth }));
-  app.get("/api/health", async (_req, res) => {
-    try {
-      const stats = await store.getStats();
-      const docs = await store.getAllDocuments();
-      let decaySummary = { totalDocuments: 0, criticalCount: 0, decayingCount: 0, averageR: 1, topDecaying: [] };
-      if (decayEngine) {
-        const report = await decayEngine.computeAll();
-        decaySummary = {
-          totalDocuments: report.totalDocuments ?? docs.length,
-          criticalCount: report.criticalCount ?? 0,
-          decayingCount: report.decayingCount ?? 0,
-          averageR: report.averageR ?? 1,
-          topDecaying: (report.topDecaying ?? []).slice(0, 5)
-        };
-      }
-      let gapSummary = { gapCount: 0, isolatedCount: 0 };
-      try {
-        const { detectKnowledgeGaps: detectKnowledgeGaps2 } = await Promise.resolve().then(() => (init_gap_detector(), gap_detector_exports));
-        const gapReport = await detectKnowledgeGaps2(store);
-        gapSummary = {
-          gapCount: gapReport.gaps?.length ?? 0,
-          isolatedCount: gapReport.isolatedNodes?.length ?? 0
-        };
-      } catch (e) {
-        console.error("[health] Gap detection failed:", e instanceof Error ? e.message : e);
-      }
-      let dupCount = 0;
-      try {
-        const { detectDuplicates: detectDuplicates2 } = await Promise.resolve().then(() => (init_duplicate_detector(), duplicate_detector_exports));
-        const pairs = await detectDuplicates2(store, 0.88, 50);
-        dupCount = pairs.length;
-      } catch (e) {
-        console.error("[health] Duplicate detection failed:", e instanceof Error ? e.message : e);
-      }
-      const sourceDist = /* @__PURE__ */ new Map();
-      const typeDist = /* @__PURE__ */ new Map();
-      for (const doc of docs) {
-        const s = doc.source ?? "local";
-        const t2 = doc.type ?? "note";
-        sourceDist.set(s, (sourceDist.get(s) ?? 0) + 1);
-        typeDist.set(t2, (typeDist.get(t2) ?? 0) + 1);
-      }
-      const monthlyGrowth = /* @__PURE__ */ new Map();
-      for (const doc of docs) {
-        const month = doc.lastModified?.slice(0, 7) ?? "unknown";
-        monthlyGrowth.set(month, (monthlyGrowth.get(month) ?? 0) + 1);
-      }
-      res.json({
-        stats: { ...stats, vaultName },
-        decay: decaySummary,
-        gaps: gapSummary,
-        duplicates: { count: dupCount },
-        distribution: {
-          source: Object.fromEntries(sourceDist),
-          type: Object.fromEntries(typeDist)
-        },
-        growth: Object.fromEntries([...monthlyGrowth.entries()].sort((a, b) => a[0].localeCompare(b[0])))
-      });
-    } catch (err) {
-      console.error(err);
-      res.status(500).json({ error: "Internal server error" });
-    }
-  });
-  app.get("/api/profile", async (_req, res) => {
-    try {
-      const stats = await store.getStats();
-      const topics = await store.getTopics();
-      const docs = await store.getAllDocuments();
-      let decaySummary = { averageR: 1, criticalCount: 0, healthScore: 100 };
-      if (decayEngine) {
-        const report = await decayEngine.computeAll();
-        const avgR = report.averageR ?? 1;
-        decaySummary = {
-          averageR: avgR,
-          criticalCount: report.criticalCount ?? 0,
-          healthScore: Math.round(avgR * 100)
-        };
-      }
-      const sourceDist = {};
-      const typeDist = {};
-      for (const doc of docs) {
-        const s = doc.source ?? "local";
-        const t2 = doc.type ?? "note";
-        sourceDist[s] = (sourceDist[s] ?? 0) + 1;
-        typeDist[t2] = (typeDist[t2] ?? 0) + 1;
-      }
-      const monthlyActivity = {};
-      for (const doc of docs) {
-        const month = doc.lastModified?.slice(0, 7);
-        if (month)
-          monthlyActivity[month] = (monthlyActivity[month] ?? 0) + 1;
-      }
-      res.json({
-        name: vaultName || "Knowledge Vault",
-        stats: {
-          documents: stats.documentCount,
-          chunks: stats.chunkCount,
-          topics: topics.length
-        },
-        healthScore: decaySummary.healthScore,
-        topTopics: topics.slice(0, 15).map((t2) => ({ name: t2.topic, count: t2.count })),
-        distribution: { source: sourceDist, type: typeDist },
-        activity: Object.fromEntries(Object.entries(monthlyActivity).sort((a, b) => a[0].localeCompare(b[0])).slice(-12)),
-        generatedAt: (/* @__PURE__ */ new Date()).toISOString()
-      });
-    } catch (err) {
-      console.error(err);
-      res.status(500).json({ error: "Internal server error" });
-    }
-  });
-  app.get("/api/embed", async (req, res) => {
-    try {
-      const mode = req.query.mode === "folder" ? "folder" : "semantic";
-      const maxNodes = Math.min(parseInt(String(req.query.max ?? "200"), 10), 500);
-      const cachedConstellation = graphCaches.get(mode);
-      if (!cachedConstellation || Date.now() - cachedConstellation.cachedAt > GRAPH_CACHE_TTL) {
-        const data = await buildGraphData(store, { mode });
-        graphCaches.set(mode, { data, generatedAt: (/* @__PURE__ */ new Date()).toISOString(), cachedAt: Date.now() });
-      }
-      const cached = graphCaches.get(mode);
-      const { nodes, edges, clusters } = cached.data;
-      const connCount = /* @__PURE__ */ new Map();
-      for (const e of edges) {
-        connCount.set(e.source, (connCount.get(e.source) ?? 0) + 1);
-        connCount.set(e.target, (connCount.get(e.target) ?? 0) + 1);
-      }
-      const sortedNodes = [...nodes].sort((a, b) => (connCount.get(b.id) ?? 0) - (connCount.get(a.id) ?? 0));
-      const selectedNodes = sortedNodes.slice(0, maxNodes);
-      const selectedIds = new Set(selectedNodes.map((n) => n.id));
-      const selectedEdges = edges.filter((e) => selectedIds.has(e.source) && selectedIds.has(e.target));
-      const embedNodes = selectedNodes.map((n, i) => {
-        const angle = i / selectedNodes.length * Math.PI * 2;
-        const r = 100 + n.clusterId * 15;
-        return {
-          id: n.id,
-          label: n.label,
-          clusterId: n.clusterId,
-          size: n.size,
-          position: [
-            r * Math.cos(angle) + (Math.random() - 0.5) * 60,
-            (Math.random() - 0.5) * 200,
-            r * Math.sin(angle) + (Math.random() - 0.5) * 60
-          ]
-        };
-      });
-      res.json({
-        nodes: embedNodes,
-        edges: selectedEdges,
-        stats: { nodeCount: embedNodes.length, edgeCount: selectedEdges.length, clusterCount: clusters.length, totalNodes: nodes.length },
-        title: vaultName || "Knowledge Graph"
-      });
-    } catch (err) {
-      console.error(err);
-      res.status(500).json({ error: "Internal server error" });
-    }
-  });
+  app.use("/api", createHealthRouter({ store, vaultName, decayEngine }));
+  app.use("/api", createAnalyticsRouter({ store, vaultName, decayEngine, graphCaches, GRAPH_CACHE_TTL }));
   let syncState = {
     running: false,
     startedAt: "",
@@ -6884,6 +6934,7 @@ var CREDITS_FILE = join19(homedir11(), ".stellavault", "federation", "credits.js
 
 // packages/core/dist/index.js
 init_retry();
+init_math();
 init_indexer();
 function createKnowledgeHub(config) {
   const embedder = createLocalEmbedder(config.embedding.localModel);
@@ -9629,7 +9680,7 @@ if (nodeVersion < 20) {
   process.exit(1);
 }
 var program = new Command();
-var SV_VERSION = true ? "0.7.1" : "0.0.0-dev";
+var SV_VERSION = true ? "0.7.3" : "0.0.0-dev";
 program.name("stellavault").description("Stellavault \u2014 Self-compiling knowledge base for your Obsidian vault").version(SV_VERSION).option("--json", "Output in JSON format (for scripting)").option("--quiet", "Suppress non-essential output");
 program.command("init").description("Interactive setup wizard \u2014 get started in 3 minutes").action(initCommand);
 program.command("doctor").description("Diagnose setup issues (config, vault, DB, model, Node version)").action(doctorCommand);
@@ -9679,4 +9730,33 @@ pack.command("export <name>").description("Export a pack as a .sv-pack file").op
 pack.command("import <file>").description("Import a .sv-pack file into your vector DB").action(packImportCommand);
 pack.command("list").description("List installed packs").action(packListCommand);
 pack.command("info <name>").description("Show pack details").action(packInfoCommand);
+program.command("completion").description("Output shell completion script (bash/zsh/fish)").option("--shell <type>", "Shell type: bash, zsh, fish", "bash").action((opts) => {
+  const commands = program.commands.map((c) => c.name()).filter((n) => n !== "completion");
+  const name = "stellavault";
+  if (opts.shell === "zsh") {
+    console.log(`#compdef ${name} sv
+_${name}() {
+  local -a commands
+  commands=(
+${commands.map((c) => `    '${c}:${program.commands.find((cmd) => cmd.name() === c)?.description() ?? ""}'`).join("\n")}
+  )
+  _describe 'command' commands
+}
+compdef _${name} ${name} sv`);
+  } else if (opts.shell === "fish") {
+    console.log(commands.map((c) => {
+      const desc = program.commands.find((cmd) => cmd.name() === c)?.description() ?? "";
+      return `complete -c ${name} -n "__fish_use_subcommand" -a "${c}" -d "${desc}"`;
+    }).join("\n"));
+  } else {
+    console.log(`_${name}_completions() {
+  local commands="${commands.join(" ")}"
+  COMPREPLY=($(compgen -W "$commands" -- "\${COMP_WORDS[COMP_CWORD]}"))
+}
+complete -F _${name}_completions ${name} sv`);
+  }
+  console.error(`
+# Add to your shell profile:
+#   eval "$(stellavault completion --shell ${opts.shell})"`);
+});
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stellavault",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Drop anything. It compiles itself into knowledge. Claude remembers everything you know. Local-first MCP server, vault files never modified.",
   "repository": {
     "type": "git",