@andespindola/brainlink 0.1.0-beta.153 → 0.1.0-beta.155

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
@@ -604,7 +607,7 @@ The graph UI shows:
 - 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
@@ -944,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.
@@ -993,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",
@@ -1022,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.
 
@@ -1100,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

@@ -99,10 +99,87 @@ select {
   cursor: grab;
 }
 
+#graph.is-node-hover {
+  cursor: pointer;
+}
+
+#graph.is-node-dragging {
+  cursor: move;
+}
+
 #graph:active {
   cursor: grabbing;
 }
 
+.graph-labels {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  overflow: hidden;
+}
+
+.graph-label {
+  position: absolute;
+  max-width: 220px;
+  transform: translate(-50%, calc(-100% - 10px));
+  padding: 4px 7px;
+  border: 1px solid rgba(129, 146, 170, 0.28);
+  border-radius: 6px;
+  background: rgba(13, 16, 20, 0.78);
+  color: var(--text);
+  font-size: 11px;
+  line-height: 1.25;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  box-shadow: 0 8px 22px rgba(0, 0, 0, 0.28);
+}
+
+.graph-label.is-focused {
+  border-color: rgba(53, 208, 162, 0.72);
+  color: #dffbf3;
+}
+
+.graph-tooltip {
+  position: absolute;
+  z-index: 4;
+  max-width: min(320px, calc(100vw - 32px));
+  padding: 8px 10px;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  background: rgba(13, 16, 20, 0.94);
+  color: var(--text);
+  font-size: 12px;
+  line-height: 1.35;
+  pointer-events: none;
+  box-shadow: 0 16px 40px rgba(0, 0, 0, 0.38);
+}
+
+.graph-tooltip strong,
+.graph-tooltip small {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.graph-tooltip small {
+  margin-top: 3px;
+  color: var(--muted);
+}
+
+.mini-map {
+  position: absolute;
+  right: 14px;
+  bottom: 14px;
+  z-index: 3;
+  width: 180px;
+  height: 120px;
+  border: 1px solid rgba(129, 146, 170, 0.28);
+  border-radius: 8px;
+  background: rgba(13, 16, 20, 0.78);
+  box-shadow: 0 16px 42px rgba(0, 0, 0, 0.38);
+}
+
 .eyebrow {
   color: var(--muted);
   font-size: 12px;

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

@@ -42,12 +42,16 @@ export const createClientHtml = () => `<!doctype html>
               <button id="zoomIn" type="button" title="Zoom in">+</button>
               <button id="zoomOut" type="button" title="Zoom out">-</button>
               <button id="fit" type="button" title="Focus central hub">◎</button>
+              <button id="releaseNode" type="button" title="Release selected node">◇</button>
               <button id="reset" type="button" title="Reset view">⌂</button>
             </div>
           </div>
         </header>
         <div class="graph-stage">
           <canvas id="graph" aria-label="Brainlink knowledge graph"></canvas>
+          <div id="graphLabels" class="graph-labels" aria-hidden="true"></div>
+          <div id="graphTooltip" class="graph-tooltip" role="tooltip" hidden></div>
+          <canvas id="miniMap" class="mini-map" aria-label="Graph overview"></canvas>
         </div>
       </section>
     </main>