feat: graph browser index page, full brain view, query-param auth

Three major improvements to the entity graph visualization:

1. **Graph Index Page** (`GET /graph/html`) — Browse all 460 entities
   grouped by type (agent, client, technology, system, domain, workflow,
   service, person) with mention counts and search. Click any entity to
   open its interactive D3.js graph.

2. **Full Brain Graph** (`GET /graph/full/html`) — Top 80 entities by
   mention count with all their co-occurrence connections (up to 300
   edges). Shows the entire knowledge landscape at a glance.

3. **Query-param auth** — All endpoints now accept `?key=API_KEY` in
   addition to the `X-Api-Key` header. This makes the graph accessible
   from a browser URL bar without needing custom headers.

All three views inherit the existing dark theme, D3.js force-directed
layout, search, click-to-highlight, info panel, and PNG export.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Skiipy11

api/src/middleware/auth.js

@@ -59,7 +59,7 @@ export function authMiddleware(req, res, next) {
     return res.status(429).json({ error: 'Too many failed attempts. Try again later.' });
   }
 
-  const key = req.headers['x-api-key'];
+  const key = req.headers['x-api-key'] || req.query.key;
   if (!key) {
     recordFailure(ip);
     return res.status(401).json({ error: 'Missing API key' });

api/src/routes/graph.js

@@ -1,18 +1,86 @@
 import { Router } from 'express';
-import { readFileSync } from 'fs';
+import { readFileSync, existsSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import {
-  isEntityStoreAvailable, findEntity, getEntityMemories, _getStoreInstance,
+  isEntityStoreAvailable, findEntity, listEntities, getEntityMemories, getEntityStats, _getStoreInstance,
 } from '../services/stores/interface.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const graphTemplate = readFileSync(join(__dirname, '../templates/graph.html'), 'utf-8');
+const indexTemplatePath = join(__dirname, '../templates/graph-index.html');
+const indexTemplate = existsSync(indexTemplatePath) ? readFileSync(indexTemplatePath, 'utf-8') : null;
 
 export const graphRouter = Router();
 
 // --- Routes ---
 
+// GET /graph/html — Index page: browse all entities, link into individual graphs
+graphRouter.get('/html', async (req, res) => {
+  try {
+    if (!isEntityStoreAvailable()) {
+      return res.status(400).send(
+        '<h1>Entity store not available</h1><p>Graph visualization requires sqlite or postgres backend.</p>'
+      );
+    }
+
+    const stats = await getEntityStats();
+    const allEntities = await listEntities({ limit: 500 });
+    const apiKey = req.query.key || '';
+
+    // Group entities by type
+    const grouped = {};
+    for (const e of allEntities.results) {
+      if (!grouped[e.entity_type]) grouped[e.entity_type] = [];
+      grouped[e.entity_type].push(e);
+    }
+    // Sort each group by mention_count desc
+    for (const type of Object.keys(grouped)) {
+      grouped[type].sort((a, b) => (b.mention_count || 0) - (a.mention_count || 0));
+    }
+
+    if (indexTemplate) {
+      const html = indexTemplate
+        .replace('{{ENTITIES_DATA}}', JSON.stringify(grouped))
+        .replace('{{STATS_DATA}}', JSON.stringify(stats))
+        .replace(/\{\{API_KEY\}\}/g, escapeHtml(apiKey));
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      return res.send(html);
+    }
+
+    // Fallback: simple HTML if template doesn't exist yet
+    let html = buildFallbackIndex(grouped, stats, apiKey);
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.send(html);
+  } catch (err) {
+    console.error('[graph:index] Error:', err.message);
+    res.status(500).send(`<h1>Error</h1><p>${escapeHtml(err.message)}</p>`);
+  }
+});
+
+// GET /graph/full/html — Full brain graph (all entities)
+graphRouter.get('/full/html', async (req, res) => {
+  try {
+    if (!isEntityStoreAvailable()) {
+      return res.status(400).send(
+        '<h1>Entity store not available</h1><p>Graph visualization requires sqlite or postgres backend.</p>'
+      );
+    }
+
+    const graphData = await buildFullGraphData(80);
+
+    const html = graphTemplate
+      .replace(/\{\{ENTITY_NAME\}\}/g, 'Full Brain')
+      .replace('{{GRAPH_DATA}}', JSON.stringify(graphData));
+
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.send(html);
+  } catch (err) {
+    console.error('[graph:full] Error:', err.message);
+    res.status(500).send(`<h1>Error</h1><p>${escapeHtml(err.message)}</p>`);
+  }
+});
+
 // GET /graph/:entity/html — Interactive D3.js visualization
 graphRouter.get('/:entity/html', async (req, res) => {
   try {
@@ -249,6 +317,229 @@ async function findCoOccurringViaInterface(entityId, limit) {
   return findCoOccurringDirect(store.db, entityId, limit);
 }
 
+/**
+ * Build full brain graph — top N entities by mention count with their connections.
+ */
+async function buildFullGraphData(limit = 80) {
+  const store = _getStoreInstance();
+  if (!store) return { nodes: [], edges: [], center: 'Brain' };
+
+  let topEntities;
+  if (store.pool) {
+    // Postgres
+    const result = await store.pool.query(
+      `SELECT id, canonical_name, entity_type, mention_count
+       FROM entities ORDER BY mention_count DESC LIMIT $1`, [limit]
+    );
+    topEntities = result.rows;
+  } else if (store.db) {
+    // SQLite
+    topEntities = store.db.prepare(
+      `SELECT id, canonical_name, entity_type, mention_count
+       FROM entities ORDER BY mention_count DESC LIMIT ?`
+    ).all(limit);
+  } else {
+    return { nodes: [], edges: [], center: 'Brain' };
+  }
+
+  const entityIds = topEntities.map(e => e.id);
+  const entityIdSet = new Set(entityIds);
+
+  const nodes = topEntities.map(e => ({
+    id: e.canonical_name,
+    type: e.entity_type,
+    mention_count: e.mention_count || 1,
+  }));
+
+  // Get edges between these entities
+  const edgeMap = new Map();
+
+  if (store.pool) {
+    // Postgres: find co-occurrences between top entities
+    const result = await store.pool.query(`
+      SELECT e1.canonical_name as source_name, e2.canonical_name as target_name,
+             COUNT(DISTINCT eml1.memory_id) as strength
+      FROM entity_memory_links eml1
+      JOIN entity_memory_links eml2 ON eml1.memory_id = eml2.memory_id AND eml1.entity_id < eml2.entity_id
+      JOIN entities e1 ON e1.id = eml1.entity_id
+      JOIN entities e2 ON e2.id = eml2.entity_id
+      WHERE eml1.entity_id = ANY($1) AND eml2.entity_id = ANY($1)
+      GROUP BY e1.canonical_name, e2.canonical_name
+      HAVING COUNT(DISTINCT eml1.memory_id) >= 2
+      ORDER BY strength DESC
+      LIMIT 300
+    `, [entityIds]);
+
+    for (const row of result.rows) {
+      edgeMap.set(`${row.source_name}||${row.target_name}`, {
+        source: row.source_name,
+        target: row.target_name,
+        type: 'co_occurrence',
+        strength: parseInt(row.strength),
+      });
+    }
+  }
+
+  // Find the highest mention entity as center
+  const center = topEntities.length > 0 ? topEntities[0].canonical_name : 'Brain';
+
+  return {
+    nodes,
+    edges: Array.from(edgeMap.values()),
+    center,
+  };
+}
+
+/**
+ * Fallback index HTML (used if graph-index.html template doesn't exist).
+ */
+function buildFallbackIndex(grouped, stats, apiKey) {
+  const typeColors = {
+    client: '#4ECDB8', person: '#F59E0B', technology: '#3B82F6',
+    workflow: '#8B5CF6', agent: '#EF4444', domain: '#10B981',
+    service: '#EC4899', system: '#6366F1',
+  };
+
+  const keyParam = apiKey ? `?key=${encodeURIComponent(apiKey)}` : '';
+
+  let entityRows = '';
+  const typeOrder = ['agent', 'client', 'technology', 'system', 'domain', 'workflow', 'service', 'person'];
+
+  for (const type of typeOrder) {
+    const entities = grouped[type];
+    if (!entities || entities.length === 0) continue;
+    const color = typeColors[type] || '#94a3b8';
+
+    entityRows += `<div class="type-section">
+      <h2 style="color:${color}"><span class="type-dot" style="background:${color}"></span>${type} <span class="count">(${entities.length})</span></h2>
+      <div class="entity-grid">`;
+
+    for (const e of entities.slice(0, 30)) {
+      entityRows += `
+        <a href="/graph/${encodeURIComponent(e.canonical_name)}/html${keyParam}" class="entity-card">
+          <span class="name">${escapeHtml(e.canonical_name)}</span>
+          <span class="mentions">${e.mention_count || 0}</span>
+        </a>`;
+    }
+    if (entities.length > 30) {
+      entityRows += `<span class="more">+${entities.length - 30} more</span>`;
+    }
+    entityRows += `</div></div>`;
+  }
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Knowledge Graph — Entity Browser</title>
+<style>
+  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  :root {
+    --bg: #0a0a0f; --surface: rgba(255,255,255,0.04); --surface-hover: rgba(255,255,255,0.08);
+    --border: rgba(255,255,255,0.08); --text: #e2e8f0; --text-muted: #94a3b8; --text-dim: #64748b;
+  }
+  body { font-family: 'Inter', system-ui, sans-serif; background: var(--bg); color: var(--text); min-height: 100vh; }
+
+  .header {
+    padding: 40px 40px 32px;
+    border-bottom: 1px solid var(--border);
+    background: linear-gradient(180deg, rgba(78,205,184,0.04) 0%, transparent 100%);
+  }
+  .header h1 { font-size: 28px; font-weight: 700; letter-spacing: -0.03em; margin-bottom: 8px; }
+  .header p { color: var(--text-muted); font-size: 14px; }
+
+  .stats-row {
+    display: flex; gap: 24px; margin-top: 20px; flex-wrap: wrap;
+  }
+  .stat-card {
+    padding: 16px 24px; background: var(--surface); border: 1px solid var(--border);
+    border-radius: 12px; min-width: 120px;
+  }
+  .stat-card .stat-value { font-size: 24px; font-weight: 700; }
+  .stat-card .stat-label { font-size: 11px; color: var(--text-dim); text-transform: uppercase; letter-spacing: 0.06em; margin-top: 4px; }
+
+  .actions { display: flex; gap: 12px; margin-top: 20px; }
+  .action-btn {
+    padding: 10px 20px; background: rgba(78,205,184,0.1); border: 1px solid rgba(78,205,184,0.3);
+    border-radius: 10px; color: #4ECDB8; font-family: inherit; font-size: 13px; font-weight: 600;
+    cursor: pointer; text-decoration: none; transition: all 0.2s ease;
+  }
+  .action-btn:hover { background: rgba(78,205,184,0.2); border-color: rgba(78,205,184,0.5); }
+  .action-btn.secondary { background: var(--surface); border-color: var(--border); color: var(--text-muted); }
+  .action-btn.secondary:hover { background: var(--surface-hover); color: var(--text); }
+
+  .content { padding: 32px 40px; }
+
+  .search-box {
+    width: 100%; max-width: 400px; padding: 12px 16px 12px 40px;
+    background: var(--surface); border: 1px solid var(--border); border-radius: 12px;
+    color: var(--text); font-family: inherit; font-size: 14px; outline: none;
+    margin-bottom: 32px; transition: all 0.3s ease;
+  }
+  .search-box:focus { border-color: rgba(78,205,184,0.4); box-shadow: 0 0 20px rgba(78,205,184,0.08); }
+  .search-box::placeholder { color: var(--text-dim); }
+
+  .type-section { margin-bottom: 32px; }
+  .type-section h2 {
+    font-size: 14px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em;
+    margin-bottom: 12px; display: flex; align-items: center; gap: 8px;
+  }
+  .type-dot { width: 10px; height: 10px; border-radius: 50%; display: inline-block; }
+  .count { font-weight: 400; color: var(--text-dim); font-size: 12px; }
+
+  .entity-grid { display: flex; flex-wrap: wrap; gap: 8px; }
+  .entity-card {
+    display: flex; align-items: center; gap: 10px;
+    padding: 8px 14px; background: var(--surface); border: 1px solid var(--border);
+    border-radius: 8px; text-decoration: none; color: var(--text); font-size: 13px;
+    transition: all 0.2s ease; cursor: pointer;
+  }
+  .entity-card:hover { background: var(--surface-hover); border-color: rgba(255,255,255,0.15); transform: translateY(-1px); }
+  .entity-card .name { font-weight: 500; }
+  .entity-card .mentions {
+    font-size: 10px; background: rgba(255,255,255,0.08); padding: 2px 8px;
+    border-radius: 10px; color: var(--text-dim); font-weight: 600;
+  }
+  .more { font-size: 12px; color: var(--text-dim); padding: 8px 14px; }
+
+  .footer {
+    padding: 32px 40px; border-top: 1px solid var(--border); text-align: center;
+    font-size: 11px; color: var(--text-dim);
+  }
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>Knowledge Graph</h1>
+  <p>Browse and explore entity relationships in the Shared Brain</p>
+  <div class="stats-row">
+    <div class="stat-card"><div class="stat-value">${stats.total || 0}</div><div class="stat-label">Entities</div></div>
+    <div class="stat-card"><div class="stat-value">${Object.keys(grouped).length}</div><div class="stat-label">Types</div></div>
+  </div>
+  <div class="actions">
+    <a href="/graph/full/html${keyParam}" class="action-btn">View Full Brain Graph</a>
+  </div>
+</div>
+<div class="content">
+  <input type="text" class="search-box" placeholder="Search entities..." id="search" autocomplete="off">
+  ${entityRows}
+</div>
+<div class="footer">Powered by Shared Brain &mdash; Multi-Agent Memory</div>
+<script>
+  document.getElementById('search').addEventListener('input', function() {
+    const q = this.value.toLowerCase();
+    document.querySelectorAll('.entity-card').forEach(card => {
+      const name = card.querySelector('.name').textContent.toLowerCase();
+      card.style.display = name.includes(q) ? '' : 'none';
+    });
+  });
+</script>
+</body>
+</html>`;
+}
+
 // --- Utilities ---
 
 function escapeHtml(str) {