clawvault 1.7.0 → 1.8.0

package/bin/clawvault.js

@@ -1186,5 +1186,34 @@ program
     }
   });
 
+// === DASHBOARD ===
+program
+  .command('dashboard')
+  .description('Run local vault graph dashboard')
+  .option('-p, --port <port>', 'Dashboard port', '3377')
+  .option('-v, --vault <path>', 'Vault path')
+  .action(async (options) => {
+    try {
+      const parsedPort = Number.parseInt(options.port, 10);
+      if (Number.isNaN(parsedPort)) {
+        console.error(chalk.red(`Error: Invalid port: ${options.port}`));
+        process.exit(1);
+      }
+
+      const vaultPath = options.vault
+        ? path.resolve(options.vault)
+        : resolveVaultPath(undefined);
+
+      const { startDashboard } = await import('../dashboard/server.js');
+      await startDashboard({
+        port: parsedPort,
+        vaultPath
+      });
+    } catch (err) {
+      console.error(chalk.red(`Error: ${err.message}`));
+      process.exit(1);
+    }
+  });
+
 // Parse and run
 program.parse();

package/dashboard/lib/vault-parser.js

@@ -0,0 +1,252 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import matter from 'gray-matter';
+
+export const WIKI_LINK_REGEX = /\[\[([^\]|]+)(\|[^\]]+)?\]\]/g;
+
+const MARKDOWN_EXT = '.md';
+const IGNORED_DIRECTORIES = new Set([
+  '.git',
+  '.obsidian',
+  '.trash',
+  'node_modules'
+]);
+
+/**
+ * Build a graph from markdown notes in a vault.
+ * @param {string} vaultPath
+ * @param {{ includeDangling?: boolean }} [options]
+ */
+export async function buildVaultGraph(vaultPath, options = {}) {
+  const includeDangling = options.includeDangling !== false;
+  const root = path.resolve(vaultPath);
+  const markdownFiles = await collectMarkdownFiles(root);
+
+  const nodesById = new Map();
+  const edges = [];
+  const edgeSet = new Set();
+
+  for (const absoluteFilePath of markdownFiles) {
+    const raw = await fs.readFile(absoluteFilePath, 'utf8');
+    const parsed = matter(raw);
+    const relativePath = path.relative(root, absoluteFilePath);
+    const id = toNodeId(relativePath);
+    const frontmatter = parsed.data ?? {};
+
+    nodesById.set(id, {
+      id,
+      title: normalizeString(frontmatter.title) || toDisplayTitle(id),
+      category: normalizeString(frontmatter.category) || inferCategory(id),
+      tags: normalizeTags(frontmatter.tags),
+      path: toPosixPath(relativePath),
+      missing: false,
+      _outboundTargets: extractWikiLinks(parsed.content)
+    });
+  }
+
+  const idsByLowercase = new Map();
+  const idsByBaseName = new Map();
+  for (const id of nodesById.keys()) {
+    idsByLowercase.set(id.toLowerCase(), id);
+    const baseName = path.posix.basename(id).toLowerCase();
+    const existing = idsByBaseName.get(baseName) ?? new Set();
+    existing.add(id);
+    idsByBaseName.set(baseName, existing);
+  }
+
+  for (const node of nodesById.values()) {
+    for (const rawTarget of node._outboundTargets) {
+      const targetId = resolveTargetId(rawTarget, {
+        idsByLowercase,
+        idsByBaseName,
+        includeDangling
+      });
+
+      if (!targetId) {
+        continue;
+      }
+
+      if (!nodesById.has(targetId) && includeDangling) {
+        nodesById.set(targetId, {
+          id: targetId,
+          title: toDisplayTitle(targetId),
+          category: 'unresolved',
+          tags: [],
+          path: null,
+          missing: true,
+          _outboundTargets: []
+        });
+      }
+
+      const edgeKey = `${node.id}=>${targetId}`;
+      if (edgeSet.has(edgeKey)) {
+        continue;
+      }
+      edgeSet.add(edgeKey);
+      edges.push({ source: node.id, target: targetId });
+    }
+  }
+
+  const degreeByNodeId = new Map();
+  for (const edge of edges) {
+    degreeByNodeId.set(edge.source, (degreeByNodeId.get(edge.source) ?? 0) + 1);
+    degreeByNodeId.set(edge.target, (degreeByNodeId.get(edge.target) ?? 0) + 1);
+  }
+
+  const nodes = Array.from(nodesById.values())
+    .map(({ _outboundTargets, ...node }) => ({
+      ...node,
+      degree: degreeByNodeId.get(node.id) ?? 0
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  edges.sort((a, b) => {
+    const sourceSort = a.source.localeCompare(b.source);
+    return sourceSort !== 0 ? sourceSort : a.target.localeCompare(b.target);
+  });
+
+  return {
+    nodes,
+    edges,
+    stats: {
+      generatedAt: new Date().toISOString(),
+      nodeCount: nodes.length,
+      edgeCount: edges.length,
+      fileCount: markdownFiles.length
+    }
+  };
+}
+
+async function collectMarkdownFiles(root) {
+  const pending = [root];
+  const files = [];
+
+  while (pending.length > 0) {
+    const currentDir = pending.pop();
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const absolutePath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (!IGNORED_DIRECTORIES.has(entry.name)) {
+          pending.push(absolutePath);
+        }
+        continue;
+      }
+
+      if (entry.isFile() && entry.name.toLowerCase().endsWith(MARKDOWN_EXT)) {
+        files.push(absolutePath);
+      }
+    }
+  }
+
+  return files;
+}
+
+function extractWikiLinks(markdown) {
+  const links = [];
+  const regex = new RegExp(WIKI_LINK_REGEX.source, 'g');
+  let match = regex.exec(markdown);
+
+  while (match) {
+    const rawTarget = match[1]?.trim();
+    if (rawTarget) {
+      links.push(rawTarget);
+    }
+    match = regex.exec(markdown);
+  }
+
+  return links;
+}
+
+function resolveTargetId(target, context) {
+  const normalized = normalizeWikiTarget(target);
+  if (!normalized) {
+    return null;
+  }
+
+  const lower = normalized.toLowerCase();
+  const exact = context.idsByLowercase.get(lower);
+  if (exact) {
+    return exact;
+  }
+
+  if (!normalized.includes('/')) {
+    const maybeMatches = context.idsByBaseName.get(lower);
+    if (maybeMatches?.size === 1) {
+      return Array.from(maybeMatches)[0];
+    }
+  }
+
+  return context.includeDangling ? normalized : null;
+}
+
+function normalizeWikiTarget(target) {
+  let value = normalizeString(target);
+  if (!value) {
+    return null;
+  }
+
+  const hashIndex = value.indexOf('#');
+  if (hashIndex >= 0) {
+    value = value.slice(0, hashIndex);
+  }
+
+  const caretIndex = value.indexOf('^');
+  if (caretIndex >= 0) {
+    value = value.slice(0, caretIndex);
+  }
+
+  value = value.replace(/\\/g, '/');
+  value = value.replace(/^\.\//, '');
+  value = value.replace(/^\/+/, '');
+  value = value.replace(/\/+/g, '/');
+
+  if (value.toLowerCase().endsWith(MARKDOWN_EXT)) {
+    value = value.slice(0, -MARKDOWN_EXT.length);
+  }
+
+  return normalizeString(value);
+}
+
+function toNodeId(relativePath) {
+  const normalized = toPosixPath(relativePath);
+  return normalized.toLowerCase().endsWith(MARKDOWN_EXT)
+    ? normalized.slice(0, -MARKDOWN_EXT.length)
+    : normalized;
+}
+
+function inferCategory(id) {
+  const category = id.split('/')[0];
+  return normalizeString(category) || 'root';
+}
+
+function normalizeTags(tags) {
+  if (Array.isArray(tags)) {
+    return tags.map(normalizeString).filter(Boolean);
+  }
+  if (typeof tags === 'string') {
+    return tags
+      .split(',')
+      .map((tag) => normalizeString(tag))
+      .filter(Boolean);
+  }
+  return [];
+}
+
+function normalizeString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function toDisplayTitle(id) {
+  const base = path.posix.basename(id);
+  return base
+    .replace(/[-_]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join('/');
+}

package/dashboard/lib/vault-parser.test.js

@@ -0,0 +1,74 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { buildVaultGraph } from './vault-parser.js';
+
+function makeTempVault() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'clawvault-dashboard-'));
+}
+
+function writeVaultFile(root, relativePath, content) {
+  const fullPath = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content, 'utf8');
+}
+
+describe('buildVaultGraph', () => {
+  it('builds nodes and edges from markdown wiki-links', async () => {
+    const vaultPath = makeTempVault();
+    try {
+      writeVaultFile(
+        vaultPath,
+        'decisions/use-clawvault.md',
+        `---
+title: Use ClawVault
+tags: [architecture, memory]
+---
+Linked to [[projects/clawvault|ClawVault Project]] and [[missing-note]].
+`
+      );
+      writeVaultFile(vaultPath, 'projects/clawvault.md', '# ClawVault');
+
+      const graph = await buildVaultGraph(vaultPath);
+      const decisionNode = graph.nodes.find((node) => node.id === 'decisions/use-clawvault');
+      const unresolvedNode = graph.nodes.find((node) => node.id === 'missing-note');
+
+      expect(decisionNode).toMatchObject({
+        title: 'Use ClawVault',
+        category: 'decisions',
+        tags: ['architecture', 'memory']
+      });
+      expect(graph.edges).toEqual(
+        expect.arrayContaining([
+          { source: 'decisions/use-clawvault', target: 'projects/clawvault' },
+          { source: 'decisions/use-clawvault', target: 'missing-note' }
+        ])
+      );
+      expect(unresolvedNode).toMatchObject({
+        missing: true,
+        category: 'unresolved'
+      });
+    } finally {
+      fs.rmSync(vaultPath, { recursive: true, force: true });
+    }
+  });
+
+  it('resolves basename links when there is a unique match', async () => {
+    const vaultPath = makeTempVault();
+    try {
+      writeVaultFile(vaultPath, 'research/notes.md', 'See [[clawvault]].');
+      writeVaultFile(vaultPath, 'projects/clawvault.md', '# ClawVault');
+
+      const graph = await buildVaultGraph(vaultPath);
+
+      expect(graph.edges).toEqual(
+        expect.arrayContaining([
+          { source: 'research/notes', target: 'projects/clawvault' }
+        ])
+      );
+    } finally {
+      fs.rmSync(vaultPath, { recursive: true, force: true });
+    }
+  });
+});

package/dashboard/public/graph.js

@@ -0,0 +1,376 @@
+const CATEGORY_COLORS = {
+  decisions: '#f26430',
+  lessons: '#4ecdc4',
+  people: '#ff6b6b',
+  projects: '#95e1d3',
+  commitments: '#f9d56e',
+  research: '#a8e6cf',
+  inbox: '#888888',
+  root: '#666666',
+  default: '#aaaaaa'
+};
+
+const HIGHLIGHT_NODE_COLOR = '#ffffff';
+const HIGHLIGHT_LINK_COLOR = '#f3f4f6';
+const DIMMED_NODE_COLOR = '#324055';
+const DIMMED_LINK_COLOR = 'rgba(130, 145, 170, 0.2)';
+
+const state = {
+  searchTerm: '',
+  category: 'all',
+  nodes: [],
+  links: [],
+  stats: null,
+  nodeById: new Map(),
+  neighborsByNodeId: new Map(),
+  linksByNodeId: new Map(),
+  hoveredNode: null,
+  selectedNode: null,
+  highlightedNodeIds: new Set(),
+  highlightedLinks: new Set()
+};
+
+const graphElement = document.querySelector('#graph');
+const detailsElement = document.querySelector('#node-details');
+const statsElement = document.querySelector('#stats');
+const searchElement = document.querySelector('#search');
+const categoryFilterElement = document.querySelector('#category-filter');
+const refreshButtonElement = document.querySelector('#refresh');
+
+if (typeof window.ForceGraph !== 'function') {
+  statsElement.textContent = 'ForceGraph failed to load.';
+  throw new Error('force-graph library unavailable');
+}
+
+const graph = window
+  .ForceGraph()(graphElement)
+  .backgroundColor('#0c1117')
+  .nodeId('id')
+  .linkSource('source')
+  .linkTarget('target')
+  .nodeRelSize(5)
+  .nodeVal((node) => 1 + Math.sqrt((node.degree ?? 0) + 1))
+  .nodeLabel((node) => `${node.title}\n${node.id}`)
+  .nodeColor((node) => getNodeColor(node))
+  .linkColor((link) => getLinkColor(link))
+  .linkWidth((link) => (state.highlightedLinks.has(link) ? 2.6 : 1))
+  .linkDirectionalParticles((link) => (state.highlightedLinks.has(link) ? 2 : 0))
+  .linkDirectionalParticleWidth(2)
+  .cooldownTicks(120)
+  .onNodeHover((node) => {
+    state.hoveredNode = node ?? null;
+    syncHighlights();
+  })
+  .onNodeClick((node) => {
+    state.selectedNode = node;
+    syncHighlights();
+    renderDetails(node);
+  })
+  .onBackgroundClick(() => {
+    state.selectedNode = null;
+    syncHighlights();
+    renderEmptyDetails();
+  });
+
+resizeGraphToContainer();
+
+window.addEventListener('resize', () => {
+  resizeGraphToContainer();
+});
+
+function resizeGraphToContainer() {
+  graph.width(graphElement.clientWidth);
+  graph.height(graphElement.clientHeight);
+}
+
+searchElement.addEventListener('input', (event) => {
+  state.searchTerm = String(event.target.value ?? '').trim().toLowerCase();
+  applyFilters();
+});
+
+categoryFilterElement.addEventListener('change', (event) => {
+  state.category = String(event.target.value ?? 'all');
+  applyFilters();
+});
+
+refreshButtonElement.addEventListener('click', async () => {
+  await loadGraphData({ refresh: true });
+});
+
+detailsElement.addEventListener('click', (event) => {
+  const target = event.target;
+  if (!(target instanceof HTMLElement)) {
+    return;
+  }
+
+  const linkedNodeId = target.dataset.nodeId;
+  if (!linkedNodeId) {
+    return;
+  }
+
+  event.preventDefault();
+  const linkedNode = state.nodeById.get(linkedNodeId);
+  if (!linkedNode) {
+    return;
+  }
+
+  state.selectedNode = linkedNode;
+  syncHighlights();
+  renderDetails(linkedNode);
+  graph.centerAt(linkedNode.x ?? 0, linkedNode.y ?? 0, 450);
+  graph.zoom(4, 350);
+});
+
+await loadGraphData();
+
+async function loadGraphData({ refresh = false } = {}) {
+  statsElement.textContent = 'Loading graph...';
+  refreshButtonElement.disabled = true;
+  try {
+    const response = await fetch(refresh ? '/api/graph?refresh=1' : '/api/graph');
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+
+    const payload = await response.json();
+    const nodes = payload.nodes ?? [];
+    const links = (payload.edges ?? []).map((edge) => ({
+      source: edge.source,
+      target: edge.target
+    }));
+
+    hydrateState(nodes, links, payload.stats ?? null);
+    populateCategoryFilter();
+    applyFilters();
+    renderEmptyDetails();
+    updateStats();
+    graph.zoomToFit(600, 80);
+  } catch (error) {
+    statsElement.textContent = `Failed to load graph: ${error instanceof Error ? error.message : String(error)}`;
+  } finally {
+    refreshButtonElement.disabled = false;
+  }
+}
+
+function hydrateState(nodes, links, stats) {
+  state.nodes = nodes;
+  state.links = links;
+  state.stats = stats;
+  state.nodeById = new Map(nodes.map((node) => [node.id, node]));
+  state.neighborsByNodeId = new Map();
+  state.linksByNodeId = new Map();
+  state.hoveredNode = null;
+  state.selectedNode = null;
+
+  for (const node of nodes) {
+    state.neighborsByNodeId.set(node.id, new Set());
+    state.linksByNodeId.set(node.id, new Set());
+  }
+
+  for (const link of links) {
+    const sourceId = getNodeId(link.source);
+    const targetId = getNodeId(link.target);
+    if (!sourceId || !targetId) {
+      continue;
+    }
+    state.neighborsByNodeId.get(sourceId)?.add(targetId);
+    state.neighborsByNodeId.get(targetId)?.add(sourceId);
+    state.linksByNodeId.get(sourceId)?.add(link);
+    state.linksByNodeId.get(targetId)?.add(link);
+  }
+
+  graph.graphData({ nodes: state.nodes, links: state.links });
+}
+
+function applyFilters() {
+  graph.nodeVisibility((node) => isNodeVisible(node));
+  graph.linkVisibility((link) => {
+    const sourceNode = getNodeFromLinkEnd(link.source);
+    const targetNode = getNodeFromLinkEnd(link.target);
+    return Boolean(sourceNode && targetNode && isNodeVisible(sourceNode) && isNodeVisible(targetNode));
+  });
+  syncHighlights();
+  graph.refresh();
+}
+
+function syncHighlights() {
+  state.highlightedNodeIds.clear();
+  state.highlightedLinks.clear();
+
+  const focusNode = state.selectedNode ?? state.hoveredNode;
+  if (!focusNode) {
+    graph.refresh();
+    return;
+  }
+
+  const focusNodeId = focusNode.id;
+  state.highlightedNodeIds.add(focusNodeId);
+
+  for (const neighborId of state.neighborsByNodeId.get(focusNodeId) ?? []) {
+    state.highlightedNodeIds.add(neighborId);
+  }
+  for (const link of state.linksByNodeId.get(focusNodeId) ?? []) {
+    state.highlightedLinks.add(link);
+  }
+
+  graph.refresh();
+}
+
+function renderEmptyDetails() {
+  detailsElement.innerHTML = '<p>Select a node to inspect details and connections.</p>';
+}
+
+function renderDetails(node) {
+  const neighbors = Array.from(state.neighborsByNodeId.get(node.id) ?? [])
+    .map((id) => state.nodeById.get(id))
+    .filter(Boolean)
+    .sort((a, b) => a.title.localeCompare(b.title));
+
+  const tags = Array.isArray(node.tags) && node.tags.length > 0 ? node.tags.join(', ') : 'none';
+  const category = node.category || 'default';
+  const degree = Number(node.degree ?? neighbors.length);
+  const pathValue = node.path ?? '(unresolved link target)';
+
+  const connectionItems = neighbors.length
+    ? neighbors
+        .map((neighbor) => {
+          const color = colorForCategory(neighbor.category);
+          return `<li><a href="#" class="connection-link" data-node-id="${escapeHtml(neighbor.id)}" style="color:${color}">${escapeHtml(neighbor.title)}</a></li>`;
+        })
+        .join('')
+    : '<li>No direct connections</li>';
+
+  detailsElement.innerHTML = `
+    <div class="meta-label">Title</div>
+    <p class="meta-value">${escapeHtml(node.title)}</p>
+    <div class="meta-label">ID</div>
+    <p class="meta-value">${escapeHtml(node.id)}</p>
+    <div class="meta-label">Category</div>
+    <p class="meta-value">${escapeHtml(category)}</p>
+    <div class="meta-label">Tags</div>
+    <p class="meta-value">${escapeHtml(tags)}</p>
+    <div class="meta-label">Degree</div>
+    <p class="meta-value">${degree}</p>
+    <div class="meta-label">Path</div>
+    <p class="meta-value">${escapeHtml(pathValue)}</p>
+    <div class="meta-label">Connections (${neighbors.length})</div>
+    <ul class="connection-list">${connectionItems}</ul>
+  `;
+}
+
+function updateStats() {
+  const nodeCount = state.stats?.nodeCount ?? state.nodes.length;
+  const edgeCount = state.stats?.edgeCount ?? state.links.length;
+  const fileCount = state.stats?.fileCount ?? state.nodes.length;
+  statsElement.textContent = `${nodeCount} nodes • ${edgeCount} links • ${fileCount} files`;
+}
+
+function populateCategoryFilter() {
+  const currentValue = state.category;
+  const categories = new Set(['all']);
+  for (const node of state.nodes) {
+    categories.add(node.category || 'default');
+  }
+
+  const options = Array.from(categories).sort((a, b) => {
+    if (a === 'all') return -1;
+    if (b === 'all') return 1;
+    return a.localeCompare(b);
+  });
+
+  categoryFilterElement.innerHTML = options
+    .map((value) => `<option value="${escapeHtml(value)}">${escapeHtml(value === 'all' ? 'All categories' : value)}</option>`)
+    .join('');
+
+  if (options.includes(currentValue)) {
+    categoryFilterElement.value = currentValue;
+    state.category = currentValue;
+  } else {
+    categoryFilterElement.value = 'all';
+    state.category = 'all';
+  }
+}
+
+function getNodeColor(node) {
+  const nodeId = node.id;
+  if (!isNodeVisible(node)) {
+    return DIMMED_NODE_COLOR;
+  }
+  if (state.highlightedNodeIds.has(nodeId)) {
+    return HIGHLIGHT_NODE_COLOR;
+  }
+  if ((state.selectedNode || state.hoveredNode) && !state.highlightedNodeIds.has(nodeId)) {
+    return DIMMED_NODE_COLOR;
+  }
+  return colorForCategory(node.category);
+}
+
+function getLinkColor(link) {
+  if (state.highlightedLinks.has(link)) {
+    return HIGHLIGHT_LINK_COLOR;
+  }
+  const sourceNode = getNodeFromLinkEnd(link.source);
+  const targetNode = getNodeFromLinkEnd(link.target);
+  if (!sourceNode || !targetNode || !isNodeVisible(sourceNode) || !isNodeVisible(targetNode)) {
+    return 'rgba(0, 0, 0, 0)';
+  }
+  if (state.selectedNode || state.hoveredNode) {
+    return DIMMED_LINK_COLOR;
+  }
+  return 'rgba(157, 176, 198, 0.36)';
+}
+
+function isNodeVisible(node) {
+  const matchesCategory = state.category === 'all' || (node.category || 'default') === state.category;
+  if (!matchesCategory) {
+    return false;
+  }
+
+  if (!state.searchTerm) {
+    return true;
+  }
+
+  const haystack = [
+    node.id,
+    node.title,
+    Array.isArray(node.tags) ? node.tags.join(' ') : '',
+    node.category
+  ]
+    .join(' ')
+    .toLowerCase();
+
+  return haystack.includes(state.searchTerm);
+}
+
+function getNodeFromLinkEnd(linkEnd) {
+  if (!linkEnd) {
+    return null;
+  }
+  if (typeof linkEnd === 'object') {
+    return linkEnd;
+  }
+  return state.nodeById.get(linkEnd) ?? null;
+}
+
+function getNodeId(linkEnd) {
+  if (!linkEnd) {
+    return '';
+  }
+  if (typeof linkEnd === 'object') {
+    return linkEnd.id || '';
+  }
+  return String(linkEnd);
+}
+
+function colorForCategory(category) {
+  return CATEGORY_COLORS[category] ?? CATEGORY_COLORS.default;
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#039;');
+}

package/dashboard/public/index.html

@@ -0,0 +1,42 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>ClawVault Graph Dashboard</title>
+    <link rel="stylesheet" href="/style.css">
+  </head>
+  <body>
+    <header class="toolbar">
+      <div class="toolbar-title">
+        <h1>ClawVault Graph</h1>
+        <p id="stats">Loading graph...</p>
+      </div>
+      <div class="toolbar-controls">
+        <input id="search" type="search" placeholder="Search notes, ids, tags...">
+        <select id="category-filter">
+          <option value="all">All categories</option>
+        </select>
+        <button id="refresh" type="button">Refresh</button>
+      </div>
+    </header>
+
+    <main class="layout">
+      <section id="graph" aria-label="Vault graph visualization"></section>
+      <aside class="details-panel">
+        <h2>Node Details</h2>
+        <div id="node-details">
+          <p>Select a node to inspect details and connections.</p>
+        </div>
+      </aside>
+    </main>
+
+    <script src="/vendor/force-graph.min.js"></script>
+    <script>
+      if (!window.ForceGraph) {
+        document.write('<script src="https://unpkg.com/force-graph"><\/script>');
+      }
+    </script>
+    <script type="module" src="/graph.js"></script>
+  </body>
+</html>

package/dashboard/public/style.css

@@ -0,0 +1,154 @@
+:root {
+  color-scheme: dark;
+  font-family: Inter, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --bg: #0c1117;
+  --panel: #121a24;
+  --panel-border: #1e2936;
+  --text: #d8e3f0;
+  --muted: #8fa1b7;
+  --accent: #4ecdc4;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  margin: 0;
+  width: 100%;
+  height: 100%;
+  background: var(--bg);
+  color: var(--text);
+}
+
+body {
+  display: flex;
+  flex-direction: column;
+}
+
+.toolbar {
+  border-bottom: 1px solid var(--panel-border);
+  background: #0f1520;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.75rem 1rem;
+}
+
+.toolbar h1 {
+  margin: 0;
+  font-size: 1.1rem;
+}
+
+.toolbar p {
+  margin: 0.2rem 0 0;
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+
+.toolbar-controls {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+input,
+select,
+button {
+  border: 1px solid var(--panel-border);
+  background: var(--panel);
+  color: var(--text);
+  border-radius: 8px;
+  padding: 0.5rem 0.65rem;
+  font-size: 0.9rem;
+}
+
+input {
+  min-width: 220px;
+}
+
+button {
+  cursor: pointer;
+}
+
+button:hover {
+  border-color: var(--accent);
+}
+
+.layout {
+  display: grid;
+  grid-template-columns: 1fr 300px;
+  min-height: 0;
+  flex: 1;
+}
+
+#graph {
+  min-height: 0;
+}
+
+.details-panel {
+  border-left: 1px solid var(--panel-border);
+  padding: 1rem;
+  background: #0f1520;
+  overflow-y: auto;
+}
+
+.details-panel h2 {
+  margin-top: 0;
+  font-size: 1rem;
+}
+
+.meta-label {
+  color: var(--muted);
+  font-size: 0.82rem;
+  margin-bottom: 0.15rem;
+}
+
+.meta-value {
+  margin: 0 0 0.8rem;
+  font-size: 0.92rem;
+  word-break: break-word;
+}
+
+.connection-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.connection-list li {
+  border-bottom: 1px solid var(--panel-border);
+  padding: 0.35rem 0;
+  font-size: 0.9rem;
+}
+
+.connection-list li:last-child {
+  border-bottom: none;
+}
+
+.connection-link {
+  color: #9bc3ff;
+  text-decoration: none;
+}
+
+.connection-link:hover {
+  text-decoration: underline;
+}
+
+@media (max-width: 980px) {
+  .layout {
+    grid-template-columns: 1fr;
+    grid-template-rows: 1fr auto;
+  }
+
+  #graph {
+    height: 65vh;
+  }
+
+  .details-panel {
+    border-left: none;
+    border-top: 1px solid var(--panel-border);
+  }
+}

package/dashboard/server.js

@@ -0,0 +1,184 @@
+import express from 'express';
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildVaultGraph } from './lib/vault-parser.js';
+
+const DEFAULT_PORT = 3377;
+const HOST = '0.0.0.0';
+
+export async function startDashboard(options = {}) {
+  const port = normalizePort(options.port ?? DEFAULT_PORT);
+  const vaultPath = resolveVaultPath(options.vaultPath);
+  await assertVaultPath(vaultPath);
+
+  const app = express();
+  const serverDir = path.dirname(fileURLToPath(import.meta.url));
+  const projectDir = path.resolve(serverDir, '..');
+  const publicDir = path.join(serverDir, 'public');
+  const forceGraphDistDir = path.join(projectDir, 'node_modules', 'force-graph', 'dist');
+
+  const graphCache = createGraphCache(vaultPath);
+
+  app.get('/api/graph', async (req, res) => {
+    try {
+      const shouldRefresh = req.query.refresh === '1';
+      const graph = await graphCache.get({ forceRefresh: shouldRefresh });
+      res.json(graph);
+    } catch (error) {
+      res.status(500).json({
+        error: 'Failed to build graph',
+        detail: error instanceof Error ? error.message : String(error)
+      });
+    }
+  });
+
+  app.get('/api/health', (_req, res) => {
+    res.json({
+      ok: true,
+      vaultPath
+    });
+  });
+
+  app.use('/vendor', express.static(forceGraphDistDir));
+  app.use(express.static(publicDir, { extensions: ['html'] }));
+
+  const server = await new Promise((resolve, reject) => {
+    const runningServer = app
+      .listen(port, HOST, () => resolve(runningServer))
+      .on('error', reject);
+  });
+
+  logStartup({
+    port,
+    vaultPath
+  });
+
+  const shutdown = () => {
+    server.close(() => {
+      process.exit(0);
+    });
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  return server;
+}
+
+function createGraphCache(vaultPath) {
+  const ttlMs = 2_000;
+  let cache = null;
+  let fetchedAt = 0;
+  let inFlight = null;
+
+  return {
+    async get({ forceRefresh = false } = {}) {
+      const ageMs = Date.now() - fetchedAt;
+      if (!forceRefresh && cache && ageMs < ttlMs) {
+        return cache;
+      }
+
+      if (inFlight) {
+        return inFlight;
+      }
+
+      inFlight = buildVaultGraph(vaultPath)
+        .then((graph) => {
+          cache = graph;
+          fetchedAt = Date.now();
+          return graph;
+        })
+        .finally(() => {
+          inFlight = null;
+        });
+
+      return inFlight;
+    }
+  };
+}
+
+function parseArgs(argv) {
+  const options = {
+    port: DEFAULT_PORT,
+    vaultPath: undefined
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--port' || arg === '-p') {
+      options.port = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === '--vault' || arg === '-v') {
+      options.vaultPath = argv[i + 1];
+      i += 1;
+    }
+  }
+
+  return options;
+}
+
+function normalizePort(value) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+    throw new Error(`Invalid port: ${value}`);
+  }
+  return parsed;
+}
+
+function resolveVaultPath(input) {
+  const candidate = input || process.env.CLAWVAULT_PATH || process.cwd();
+  return path.resolve(candidate);
+}
+
+async function assertVaultPath(vaultPath) {
+  let stat;
+  try {
+    stat = await fs.stat(vaultPath);
+  } catch (error) {
+    throw new Error(`Vault path not found: ${vaultPath}`);
+  }
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Vault path is not a directory: ${vaultPath}`);
+  }
+}
+
+function logStartup({ port, vaultPath }) {
+  const interfaces = os.networkInterfaces();
+  const networkUrls = [];
+
+  for (const addresses of Object.values(interfaces)) {
+    for (const address of addresses ?? []) {
+      if (address.family !== 'IPv4' || address.internal) {
+        continue;
+      }
+      networkUrls.push(`http://${address.address}:${port}`);
+    }
+  }
+
+  console.log('\nClawVault Dashboard');
+  console.log(`Vault: ${vaultPath}`);
+  console.log(`Local: http://localhost:${port}`);
+  for (const url of networkUrls) {
+    console.log(`Network: ${url}`);
+  }
+  console.log('\nPress Ctrl+C to stop.\n');
+}
+
+const currentFile = fileURLToPath(import.meta.url);
+const executedFile = process.argv[1] ? path.resolve(process.argv[1]) : '';
+
+if (currentFile === executedFile) {
+  startDashboard(parseArgs(process.argv.slice(2))).catch((error) => {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'EADDRINUSE') {
+      console.error('Port already in use.');
+    } else {
+      console.error(error instanceof Error ? error.message : String(error));
+    }
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawvault",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "🐘 An elephant never forgets. Structured memory for OpenClaw agents. Context death resilience, Obsidian-compatible markdown, local semantic search.",
   "type": "module",
   "main": "dist/index.cjs",
@@ -19,6 +19,7 @@
   "files": [
     "dist",
     "bin",
+    "dashboard",
     "templates",
     "hooks"
   ],
@@ -61,13 +62,14 @@
     "node": ">=18"
   },
   "dependencies": {
-    "commander": "^12.0.0",
     "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "express": "^5.2.1",
+    "force-graph": "^1.51.1",
     "glob": "^10.3.10",
     "gray-matter": "^4.0.3",
     "natural": "^6.10.4"
   },
-  "optionalDependencies": {},
   "peerDependencies": {
     "qmd": "*"
   },