@andespindola/brainlink 0.1.0-beta.152 → 0.1.0-beta.154

package/AGENTS.md

@@ -78,10 +78,10 @@ http://127.0.0.1:4321/
 http://127.0.0.1:4321/api/graph
 ```
 
-Use watch mode while editing notes:
+The graph server watches Markdown files by default while editing notes:
 
 ```bash
-npm run dev -- server --vault ./vault --watch
+npm run dev -- server --vault ./vault
 npm run dev -- watch --vault ./vault
 npm run dev -- bench --vault ./vault
 npm run dev -- bench --vault ./vault --watch

package/README.md

@@ -265,7 +265,7 @@ blink search "jwt auth" --vault ./vault
 
 blink context "how does auth work?" --vault ./vault
 
-blink server --vault ./vault --watch
+blink server --vault ./vault
 ```
 
 Open the graph UI:
@@ -536,6 +536,7 @@ Available tools:
 - `brainlink_resolve_duplicate`: resolve duplicate pairs (`merge`, `link`, `ignore`) with connectivity-safe fallback edges.
 - `brainlink_add_note`: write durable Markdown memory and reindex.
 - `brainlink_add_file`: ingest a local file as a note and reindex.
+- `brainlink_canonicalize_context_links`: ensure existing notes link to inferred context hubs.
 - `brainlink_volatile_add`: write temporary agent-decided memory with TTL; volatile sections are included in context and never create durable graph edges.
 - `brainlink_volatile_clear`: clear temporary memory for the current vault/agent namespace.
 - `brainlink_index`: rebuild the vault index. Pass `full=true` for a complete source reindex.
@@ -543,6 +544,7 @@ Available tools:
 - `brainlink_validate`: validate broken links and orphan notes.
 - `brainlink_sync`: run index, stats, validation, broken-link and orphan checks in one call.
 - `brainlink_graph`: read indexed graph nodes and weighted links.
+- `brainlink_graph_contexts`: list the visual graph contexts used by the local server.
 - `brainlink_broken_links`: list unresolved wiki links.
 - `brainlink_orphans`: list disconnected notes.
 
@@ -577,10 +579,11 @@ blink index --vault ./vault --full
 Start the local frontend:
 
 ```bash
-blink server --host 127.0.0.1 --port 4321 --watch
+blink server --host 127.0.0.1 --port 4321
 ```
 
 By default, the server uses `$HOME/.brainlink/vault`. Pass `--vault ./vault` only when you want to inspect a custom vault.
+By default, the server watches Markdown files in local filesystem vaults and reindexes after note changes. Use `--no-watch` to disable realtime reindexing.
 By default, `blink server` tries to open the graph in a native desktop GUI window:
 - macOS: Swift + WebKit
 - Windows: PowerShell WinForms WebBrowser
@@ -601,9 +604,10 @@ The graph UI shows:
 - details opened in a non-modal side panel (tags, outgoing links, backlinks, full Markdown content), so zoom and pan remain available while inspecting data
 - neutral graph nodes with segment/group metadata
 - agent selector (id-only labels) for isolated views
+- context selector for segment-scoped star subgraphs derived from the visual graph context
 - graph filter matches title, path, tags and note content
 - graph filter keeps hub context nodes visible (`Memory Hub`/`MOC`/high-degree fallback) to preserve relationship readability
-- realtime refresh while `--watch` is enabled
+- realtime refresh while watch mode is enabled
 - graph controls for zoom in, zoom out, fit visible nodes and reset-to-fit-all
 - wheel zoom (including `cmd+scroll` and `ctrl+scroll`) anchored to cursor position for faster navigation in large graphs
 - wheel/button zoom updates immediately at the cursor anchor without delayed focus-transition interpolation
@@ -632,6 +636,7 @@ The server always refuses non-loopback hosts. Brainlink HTTP only runs on localh
 Routes:
 
 - `GET /api/agents`
+- `GET /api/graph-contexts`
 - `GET /api/graph`
 - `GET /api/graph-layout`
 - `GET /api/graph-view?x=<x>&y=<y>&w=<width>&h=<height>&scale=<scale>`
@@ -650,6 +655,7 @@ Read routes accept `agent=<agent-id>`:
 
 ```txt
 /api/graph-layout?agent=coding-agent
+/api/graph-layout?agent=coding-agent&context=Architecture
 /api/search?q=typescript&agent=coding-agent&mode=hybrid
 /api/context?q=module-boundaries&agent=coding-agent&mode=semantic
 ```
@@ -941,15 +947,26 @@ blink watch --vault ./vault
 
 Watches Markdown files and rebuilds the index when notes change.
 
+### `canonicalize-context-links`
+
+```bash
+blink canonicalize-context-links --vault ./vault --dry-run
+blink canonicalize-context-links --vault ./vault
+```
+
+Ensures existing notes have canonical `## Context Links` entries to inferred context hubs such as `User Preferences Hub`, `GitHub Repositories Hub` or `Brainlink Hub`. The command is idempotent, creates missing hub notes by default, and fully reindexes after writes unless `--no-index` is passed.
+
 ### `server`
 
 ```bash
-blink server --watch
-blink server --vault ./vault --watch
-blink server --vault ./vault --watch --no-open
+blink server
+blink server --vault ./vault
+blink server --vault ./vault --no-open
+blink server --vault ./vault --no-watch
 ```
 
 Starts the local read-only graph UI and HTTP API.
+Watch mode is enabled by default for Markdown changes in local filesystem vaults. Use `--no-watch` to run without the watcher.
 By default, it tries to open a native desktop GUI window for the graph URL.
 On Linux, native GUI is disabled by default; enable it with `BRAINLINK_LINUX_NATIVE_GUI=1`.
 If native GUI launch is unavailable, it falls back to dedicated app-window mode and then browser open.
@@ -990,6 +1007,7 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
   "allowedVaults": [".brainlink-vault"],
   "defaultAgent": "shared",
   "autoIndexOnWrite": true,
+  "autoCanonicalContextLinks": true,
   "defaultSearchLimit": 10,
   "defaultContextTokens": 2000,
   "embeddingProvider": "local",
@@ -1019,6 +1037,7 @@ If no `vault` is configured and no `--vault` flag is passed, Brainlink uses `$HO
 `agentProfiles` is optional. When present, CLI and MCP resolve `mode`, `limit` and `tokens` per agent automatically, then fallback to global defaults.
 
 `autoIndexOnWrite` is optional and defaults to `true`. Set it to `false` to defer indexing after writes.
+`autoCanonicalContextLinks` is optional and defaults to `true`. When enabled, `blink add`, `brainlink_add_note` and `brainlink_add_file` add a canonical `## Context Links` entry to the inferred context hub, creating that hub when needed.
 
 Use `"embeddingProvider": "none"` when you want FTS-only indexing.
 
@@ -1097,7 +1116,7 @@ Local CLI:
 
 ```bash
 npm run dev -- --help
-npm run dev -- server --vault .brainlink-vault --watch
+npm run dev -- server --vault .brainlink-vault
 ```
 
 Package smoke test:

package/dist/application/add-note.js

@@ -2,6 +2,7 @@ import { writeMarkdownFile } from '../infrastructure/file-system-vault.js';
 import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
 import { validateNoteInput } from '../domain/note-safety.js';
 import { ensureVault } from '../infrastructure/file-system-vault.js';
+import { addCanonicalContextLinkToContent, ensureCanonicalContextHub } from './canonical-context-links.js';
 const slugify = (title) => title
     .normalize('NFKD')
     .replace(/[\u0300-\u036f]/g, '')
@@ -28,12 +29,20 @@ export const addNoteWithMetadata = async (vaultPath, title, content, agentId = s
     const sanitizedAgentId = sanitizeAgentId(agentId);
     const filename = `agents/${sanitizedAgentId}/${slugify(title) || 'untitled'}.md`;
     await ensureVault(vaultPath);
-    const note = buildNote(title, content.trim(), sanitizedAgentId);
+    const canonical = options.autoContextLinks === false
+        ? null
+        : addCanonicalContextLinkToContent(title, content.trim());
+    const hub = canonical?.changed
+        ? await ensureCanonicalContextHub(vaultPath, canonical.context, sanitizedAgentId)
+        : null;
+    const note = buildNote(title, canonical?.content ?? content.trim(), sanitizedAgentId);
     const path = await writeMarkdownFile(vaultPath, filename, note);
     return {
         path,
-        autoLinked: false,
-        linkTarget: null
+        autoLinked: canonical?.changed ?? false,
+        linkTarget: canonical?.changed ? canonical.hubTitle : null,
+        context: canonical?.context ?? null,
+        hubCreated: hub?.created ?? false
     };
 };
 export const addNote = async (vaultPath, title, content, agentId = sharedAgentId, options = {}) => (await addNoteWithMetadata(vaultPath, title, content, agentId, options)).path;

package/dist/application/canonical-context-links.js

@@ -0,0 +1,209 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { inferVisualGraphContext } from '../domain/graph-contexts.js';
+import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
+import { extractContextLinkWeights, parseMarkdownDocument } from '../domain/markdown.js';
+import { ensureVault, readMarkdownFileSummaries, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+const canonicalPriority = 'high';
+const slugify = (title) => title
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+export const hubTitleForContext = (contextTitle) => `${contextTitle} Hub`;
+const hubPathForContext = (contextTitle, agentId) => {
+    if (contextTitle === 'GitHub Repositories')
+        return 'github-repos/github-repositories-hub.md';
+    if (contextTitle === 'GitHub Organizations')
+        return 'github-org-repos/github-organizations-hub.md';
+    if (contextTitle === 'Machine Configuration')
+        return 'machine-config/machine-configuration-hub.md';
+    return join('agents', sanitizeAgentId(agentId), `${slugify(hubTitleForContext(contextTitle))}.md`).replaceAll('\\', '/');
+};
+const normalizeTitle = (title) => title.trim().replace(/\.md$/i, '').toLowerCase();
+const hasCanonicalLink = (content, hubTitle) => extractContextLinkWeights(content).some((link) => normalizeTitle(link.title) === normalizeTitle(hubTitle));
+const linkLine = (hubTitle) => `- [[${hubTitle}]] priority: ${canonicalPriority}`;
+const contextLinksHeading = (line) => line.match(/^(#{2,6})\s+(Context Links|Links de Contexto)\s*$/i);
+export const upsertCanonicalContextLink = (content, hubTitle) => {
+    if (hasCanonicalLink(content, hubTitle)) {
+        return content;
+    }
+    const lines = content.replace(/\s+$/u, '').split('\n');
+    const headingIndex = lines.findIndex((line) => contextLinksHeading(line.trim()));
+    if (headingIndex === -1) {
+        return `${lines.join('\n')}\n\n## Context Links\n\n${linkLine(hubTitle)}\n`;
+    }
+    const heading = contextLinksHeading(lines[headingIndex].trim());
+    const headingDepth = heading?.[1]?.length ?? 2;
+    const insertIndex = lines.findIndex((line, index) => {
+        if (index <= headingIndex)
+            return false;
+        const candidate = line.match(/^(#{2,6})\s+/);
+        return Boolean(candidate && candidate[1].length <= headingDepth);
+    });
+    const targetIndex = insertIndex === -1 ? lines.length : insertIndex;
+    const before = lines.slice(0, targetIndex);
+    const after = lines.slice(targetIndex);
+    const needsSpacer = before[before.length - 1]?.trim() !== '';
+    const nextLines = [...before, ...(needsSpacer ? [''] : []), linkLine(hubTitle), ...after];
+    return `${nextLines.join('\n').replace(/\s+$/u, '')}\n`;
+};
+const buildHubContent = (hubTitle, contextTitle, agentId) => [
+    '---',
+    `title: "${hubTitle.replaceAll('"', '\\"')}"`,
+    `agent: "${sanitizeAgentId(agentId)}"`,
+    '---',
+    '',
+    `# ${hubTitle}`,
+    '',
+    `Canonical hub for the ${contextTitle} context. #memory #hub`,
+    ''
+].join('\n');
+const readNotes = async (vaultPath) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const summaries = await readMarkdownFileSummaries(absoluteVaultPath);
+    return Promise.all(summaries.map(async (summary) => {
+        const content = await readFile(summary.absolutePath, 'utf8');
+        const document = parseMarkdownDocument({
+            absolutePath: summary.absolutePath,
+            vaultPath: absoluteVaultPath,
+            content,
+            createdAt: summary.createdAt,
+            updatedAt: summary.updatedAt
+        });
+        return {
+            summary,
+            content,
+            document
+        };
+    }));
+};
+export const ensureCanonicalContextHub = async (vaultPath, contextTitle, agentId = sharedAgentId) => {
+    const hubTitle = hubTitleForContext(contextTitle);
+    const notes = await readNotes(vaultPath);
+    const existing = notes.find((note) => normalizeTitle(note.document.title) === normalizeTitle(hubTitle));
+    const hubPath = existing?.summary.relativePath ?? hubPathForContext(contextTitle, agentId);
+    if (existing) {
+        return {
+            created: false,
+            title: hubTitle,
+            path: hubPath
+        };
+    }
+    const path = await writeMarkdownFile(vaultPath, hubPath, buildHubContent(hubTitle, contextTitle, agentId));
+    return {
+        created: true,
+        title: hubTitle,
+        path
+    };
+};
+export const canonicalizeContextLinks = async (vaultPath, options = {}) => {
+    const agentId = options.agentId ? sanitizeAgentId(options.agentId) : undefined;
+    const createMissingHubs = options.createMissingHubs !== false;
+    const notes = await readNotes(vaultPath);
+    const scopedNotes = agentId ? notes.filter((note) => note.document.agentId === agentId) : notes;
+    const knownTitles = new Set(notes.map((note) => normalizeTitle(note.document.title)));
+    const entries = [];
+    const ensureHub = async (contextTitle, hubTitle, targetAgentId) => {
+        if (knownTitles.has(normalizeTitle(hubTitle))) {
+            return true;
+        }
+        const path = hubPathForContext(contextTitle, targetAgentId);
+        if (!createMissingHubs) {
+            entries.push({
+                path,
+                title: hubTitle,
+                context: contextTitle,
+                hubTitle,
+                changed: false,
+                reason: 'missing-hub'
+            });
+            return false;
+        }
+        knownTitles.add(normalizeTitle(hubTitle));
+        if (!options.dryRun) {
+            await writeMarkdownFile(vaultPath, path, buildHubContent(hubTitle, contextTitle, targetAgentId));
+        }
+        entries.push({
+            path,
+            title: hubTitle,
+            context: contextTitle,
+            hubTitle,
+            changed: true,
+            reason: 'created-hub'
+        });
+        return true;
+    };
+    for (const note of scopedNotes) {
+        const context = inferVisualGraphContext(note.document);
+        const hubTitle = hubTitleForContext(context.title);
+        const isHub = normalizeTitle(note.document.title) === normalizeTitle(hubTitle);
+        if (isHub) {
+            entries.push({
+                path: note.summary.relativePath,
+                title: note.document.title,
+                context: context.title,
+                hubTitle,
+                changed: false,
+                reason: 'hub-note'
+            });
+            continue;
+        }
+        const hubAvailable = await ensureHub(context.title, hubTitle, note.document.agentId || sharedAgentId);
+        if (!hubAvailable) {
+            continue;
+        }
+        if (hasCanonicalLink(note.content, hubTitle)) {
+            entries.push({
+                path: note.summary.relativePath,
+                title: note.document.title,
+                context: context.title,
+                hubTitle,
+                changed: false,
+                reason: 'already-linked'
+            });
+            continue;
+        }
+        const nextContent = upsertCanonicalContextLink(note.content, hubTitle);
+        if (!options.dryRun) {
+            await writeMarkdownFile(vaultPath, note.summary.relativePath, nextContent);
+        }
+        entries.push({
+            path: note.summary.relativePath,
+            title: note.document.title,
+            context: context.title,
+            hubTitle,
+            changed: true,
+            reason: 'added-context-link'
+        });
+    }
+    const changed = entries.filter((entry) => entry.changed).length;
+    const createdHubs = entries.filter((entry) => entry.reason === 'created-hub' && entry.changed).length;
+    return {
+        dryRun: options.dryRun === true,
+        scanned: scopedNotes.length,
+        changed,
+        createdHubs,
+        skipped: entries.length - changed,
+        entries
+    };
+};
+export const addCanonicalContextLinkToContent = (title, content) => {
+    const context = inferVisualGraphContext({
+        id: '',
+        agentId: sharedAgentId,
+        title,
+        path: '',
+        content,
+        tags: [],
+    });
+    const hubTitle = hubTitleForContext(context.title);
+    const nextContent = normalizeTitle(title) === normalizeTitle(hubTitle) ? content : upsertCanonicalContextLink(content, hubTitle);
+    return {
+        content: nextContent,
+        context: context.title,
+        hubTitle,
+        changed: nextContent !== content
+    };
+};

package/dist/application/frontend/client-css.js

@@ -113,7 +113,8 @@ select {
   min-width: 220px;
 }
 
-.agent-filter {
+.agent-filter,
+.context-filter {
   width: min(220px, 28vw);
 }
 
@@ -125,7 +126,8 @@ select {
 }
 
 .search input,
-.agent-filter select {
+.agent-filter select,
+.context-filter select {
   width: 100%;
   height: 40px;
   border: 1px solid var(--line);
@@ -137,7 +139,8 @@ select {
 }
 
 .search input:focus,
-.agent-filter select:focus {
+.agent-filter select:focus,
+.context-filter select:focus {
   border-color: var(--accent);
 }
 
@@ -405,7 +408,8 @@ li small {
     order: 3;
   }
 
-  .agent-filter {
+  .agent-filter,
+  .context-filter {
     width: 100%;
   }
 

package/dist/application/frontend/client-html.js

@@ -35,6 +35,9 @@ export const createClientHtml = () => `<!doctype html>
             <label class="agent-filter">
               <select id="agent"></select>
             </label>
+            <label class="context-filter">
+              <select id="context"></select>
+            </label>
             <div class="toolbar" aria-label="Graph controls">
               <button id="zoomIn" type="button" title="Zoom in">+</button>
               <button id="zoomOut" type="button" title="Zoom out">-</button>

package/dist/application/frontend/client-js.js

@@ -4,6 +4,7 @@ const byId = (id) => document.getElementById(id)
 const elements = {
   search: byId('search'),
   agent: byId('agent'),
+  context: byId('context'),
   nodeCount: byId('nodeCount'),
   edgeCount: byId('edgeCount'),
   tagCount: byId('tagCount'),
@@ -49,6 +50,7 @@ const state = {
   rendererMode: 'worker',
   renderWorker: null,
   agentId: '',
+  contextId: '',
   graphSignature: '',
   graphMode: 'near',
   chunk: {
@@ -77,6 +79,7 @@ const zoomRange = {
 }
 
 const selectedAgentStorageKey = 'brainlink:selected-agent'
+const selectedContextStorageKey = 'brainlink:selected-context'
 
 const escapeHtml = (value) => String(value)
   .replaceAll('&', '&')
@@ -104,6 +107,25 @@ const writeStoredAgent = (agentId) => {
   } catch {}
 }
 
+const readStoredContext = () => {
+  try {
+    const value = window.localStorage.getItem(selectedContextStorageKey)?.trim() ?? ''
+    return value.length > 0 ? value : ''
+  } catch {
+    return ''
+  }
+}
+
+const writeStoredContext = (contextId) => {
+  try {
+    if (!contextId) {
+      window.localStorage.removeItem(selectedContextStorageKey)
+      return
+    }
+    window.localStorage.setItem(selectedContextStorageKey, contextId)
+  } catch {}
+}
+
 const syncAgentInUrl = (agentId) => {
   try {
     const url = new URL(window.location.href)
@@ -116,6 +138,18 @@ const syncAgentInUrl = (agentId) => {
   } catch {}
 }
 
+const syncContextInUrl = (contextId) => {
+  try {
+    const url = new URL(window.location.href)
+    if (contextId && contextId.trim().length > 0) {
+      url.searchParams.set('context', contextId)
+    } else {
+      url.searchParams.delete('context')
+    }
+    window.history.replaceState({}, '', url.toString())
+  } catch {}
+}
+
 const initialAgentFromUrl = (() => {
   try {
     const raw = new URL(window.location.href).searchParams.get('agent')
@@ -126,7 +160,28 @@ const initialAgentFromUrl = (() => {
   }
 })()
 
-const agentQuery = (separator = '?') => state.agentId ? separator + 'agent=' + encodeURIComponent(state.agentId) : ''
+const initialContextFromUrl = (() => {
+  try {
+    const raw = new URL(window.location.href).searchParams.get('context')
+    const value = raw?.trim() ?? ''
+    return value.length > 0 ? value : ''
+  } catch {
+    return ''
+  }
+})()
+
+const scopeQuery = (separator = '?') => {
+  const params = new URLSearchParams()
+  if (state.agentId) {
+    params.set('agent', state.agentId)
+  }
+  if (state.contextId) {
+    params.set('context', state.contextId)
+  }
+  const query = params.toString()
+
+  return query ? separator + query : ''
+}
 
 const parseColor = (hex) => {
   const normalized = String(hex || '#ffffff').replace('#', '')
@@ -375,7 +430,7 @@ const loadNodeDetails = async (nodeId) => {
     return
   }
 
-  const response = await fetch('/api/graph-node?id=' + encodeURIComponent(nodeId) + agentQuery('&'))
+  const response = await fetch('/api/graph-node?id=' + encodeURIComponent(nodeId) + scopeQuery('&'))
   if (!response.ok) {
     throw new Error('Failed to load graph node details')
   }
@@ -479,6 +534,9 @@ const fetchChunk = async ({ fit } = { fit: false }) => {
   if (state.agentId) {
     params.set('agent', state.agentId)
   }
+  if (state.contextId) {
+    params.set('context', state.contextId)
+  }
 
   const response = await fetch('/api/graph-stream?' + params.toString(), { signal: controller.signal })
   if (!response.ok) {
@@ -751,7 +809,7 @@ const setupControls = () => {
       return
     }
 
-    fetch('/api/graph-filter?q=' + encodeURIComponent(query) + '&limit=1800' + agentQuery('&'))
+    fetch('/api/graph-filter?q=' + encodeURIComponent(query) + '&limit=1800' + scopeQuery('&'))
       .then((response) => response.json())
       .then((payload) => {
         if (token !== state.searchToken) {
@@ -795,12 +853,50 @@ const loadAgents = async () => {
     state.agentId = elements.agent.value || ''
     writeStoredAgent(state.agentId)
     syncAgentInUrl(state.agentId)
-    scheduleChunkFetch({ fit: true })
+    loadContexts().then(() => scheduleChunkFetch({ fit: true })).catch((error) => console.error(error))
   })
 
   syncAgentInUrl(state.agentId)
 }
 
+const loadContexts = async () => {
+  const response = await fetch('/api/graph-contexts' + (state.agentId ? '?agent=' + encodeURIComponent(state.agentId) : ''))
+  if (!response.ok) {
+    throw new Error('Failed to load graph contexts')
+  }
+
+  const payload = await response.json()
+  const contexts = Array.isArray(payload?.contexts) ? payload.contexts : []
+  const options = [
+    '<option value="">All contexts</option>',
+    ...contexts.map((context) => {
+      const id = String(context?.id || '')
+      const title = String(context?.title || id || 'Untitled')
+      const count = Number.isFinite(context?.nodeCount) ? context.nodeCount : 0
+      return '<option value="' + escapeHtml(id) + '">' + escapeHtml(title) + ' (' + count + ')</option>'
+    })
+  ]
+
+  elements.context.innerHTML = options.join('')
+
+  const preferredContext = initialContextFromUrl || readStoredContext()
+  const hasPreferred = preferredContext && contexts.some((context) => context?.id === preferredContext)
+  state.contextId = hasPreferred ? preferredContext : ''
+  elements.context.value = state.contextId
+  writeStoredContext(state.contextId)
+  syncContextInUrl(state.contextId)
+}
+
+const setupContextControl = () => {
+  elements.context.addEventListener('change', () => {
+    state.contextId = elements.context.value || ''
+    state.selectedNodeId = null
+    writeStoredContext(state.contextId)
+    syncContextInUrl(state.contextId)
+    scheduleChunkFetch({ fit: true })
+  })
+}
+
 const setupRenderWorker = () => {
   const hasWorker = typeof Worker !== 'undefined'
   const canTransfer = typeof canvas.transferControlToOffscreen === 'function'
@@ -892,6 +988,7 @@ const bootstrap = async () => {
   setupRenderWorker()
   setupInput()
   setupControls()
+  setupContextControl()
   wireNodeLinkClicks()
 
   window.addEventListener('resize', () => {
@@ -900,12 +997,11 @@ const bootstrap = async () => {
   })
 
   await loadAgents()
+  await loadContexts()
   updateTotals()
   updateTagCount()
 
-  if (state.rendererMode === 'fallback') {
-    scheduleChunkFetch({ fit: true })
-  }
+  scheduleChunkFetch({ fit: true })
 }
 
 bootstrap().catch((error) => {

package/dist/application/get-graph-contexts.js

@@ -0,0 +1,19 @@
+import { getGraphLayout } from './get-graph-layout.js';
+export const getGraphContexts = async (vaultPath, agentId) => {
+    const { layout } = await getGraphLayout(vaultPath, { agentId });
+    const nodeIdsByContext = layout.nodes.reduce((contexts, node) => {
+        const title = node.segment || node.group || 'root';
+        const nodeIds = contexts.get(title) ?? new Set();
+        nodeIds.add(node.id);
+        contexts.set(title, nodeIds);
+        return contexts;
+    }, new Map());
+    return Array.from(nodeIdsByContext.entries())
+        .map(([title, nodeIds]) => ({
+        id: title,
+        title,
+        nodeCount: nodeIds.size,
+        edgeCount: layout.edges.filter((edge) => nodeIds.has(edge.source) && Boolean(edge.target && nodeIds.has(edge.target))).length
+    }))
+        .sort((left, right) => right.nodeCount - left.nodeCount || left.title.localeCompare(right.title));
+};