@andespindola/brainlink 0.1.0-beta.99 → 1.0.1

package/dist/cli/commands/write-commands.js

@@ -5,18 +5,23 @@ import { platform, tmpdir } from 'node:os';
 import { spawn, spawnSync } from 'node:child_process';
 import { addNoteWithMetadata } from '../../application/add-note.js';
 import { buildContextPackage } from '../../application/build-context.js';
+import { deleteNote } from '../../application/delete-note.js';
 import { resolveDuplicateNotes, scanDuplicateNotes } from '../../application/dedupe-notes.js';
 import { importLegacySqliteDatabase } from '../../application/import-legacy-sqlite.js';
 import { indexVault, indexVaultWithOptions } from '../../application/index-vault.js';
+import { migrateContextLinks } from '../../application/migrate-context-links.js';
+import { canonicalizeContextLinks } from '../../application/canonical-context-links.js';
 import { migrateVaultContent, planVaultMigration, previewVaultMigration, shouldMigrateDefaultVault } from '../../application/migrate-vault.js';
 import { createOfflinePackBackup } from '../../application/offline-pack-backup.js';
 import { startServer } from '../../application/start-server.js';
 import { startVaultWatcher } from '../../application/watch-vault.js';
 import { doctorVault, getStats, validateVault } from '../../application/analyze-vault.js';
-import { defaultBrainlinkConfig, sanitizeSearchMode } from '../../infrastructure/config.js';
+import { defaultBrainlinkConfig, sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../../infrastructure/config.js';
-import { assertVaultAllowed, ensureVault } from '../../infrastructure/file-system-vault.js';
+import { assertVaultAllowed, ensureVault, isBucketVaultPath } from '../../infrastructure/file-system-vault.js';
 import { getBootstrapPolicy, getBootstrapSessionStatus, touchBootstrapSession } from '../../infrastructure/session-state.js';
+import { addVolatileMemory, clearVolatileMemory } from '../../infrastructure/volatile-memory.js';
+import { startRemoteMcpServer } from '../../mcp/http-server.js';
 import { installAgentIntegration } from './agent-commands.js';
 import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
 const resolveAddContent = (options) => {
@@ -698,6 +703,68 @@ export const registerWriteCommands = (program) => {
             return `${summary}${indexMessage}${reportMessage}`;
         });
     });
+    program
+        .command('migrate-context-links')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-l, --limit <limit>', 'maximum context links to add per note', '5')
+        .option('--dry-run', 'preview context-link migration without writing files')
+        .option('--no-index', 'skip reindexing after migration')
+        .option('--json', 'print machine-readable JSON')
+        .description('add concise Context Links sections from existing wiki-link mentions')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await migrateContextLinks(resolved.vault, {
+            dryRun: options.dryRun === true,
+            limit: parsePositiveInteger(options.limit ?? '5', 5),
+            agentId: resolved.agent
+        });
+        const shouldIndex = options.index !== false && !result.dryRun && result.changed > 0;
+        const index = shouldIndex ? await indexVault(resolved.vault, { full: true }) : undefined;
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            ...result,
+            ...(index ? { index } : {})
+        }, () => {
+            const mode = result.dryRun ? 'Previewed' : 'Migrated';
+            const indexMessage = index
+                ? ` Fully reindexed ${index.documentCount} documents, ${index.chunkCount} chunks and ${index.linkCount} context links.`
+                : '';
+            return `${mode} ${result.scanned} notes: changed=${result.changed}, skipped=${result.skipped}, limit=${result.limit}.${indexMessage}`;
+        });
+    });
+    program
+        .command('canonicalize-context-links')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--dry-run', 'preview canonical context links without writing files')
+        .option('--no-create-hubs', 'do not create missing context hub notes')
+        .option('--no-index', 'skip reindexing after canonicalization')
+        .option('--json', 'print machine-readable JSON')
+        .description('ensure notes have canonical Context Links to their inferred context hubs')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await canonicalizeContextLinks(resolved.vault, {
+            dryRun: options.dryRun === true,
+            agentId: resolved.agent,
+            createMissingHubs: options.createHubs !== false
+        });
+        const shouldIndex = options.index !== false && !result.dryRun && result.changed > 0;
+        const index = shouldIndex ? await indexVault(resolved.vault, { full: true }) : undefined;
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            ...result,
+            ...(index ? { index } : {})
+        }, () => {
+            const mode = result.dryRun ? 'Previewed' : 'Canonicalized';
+            const indexMessage = index
+                ? ` Fully reindexed ${index.documentCount} documents, ${index.chunkCount} chunks and ${index.linkCount} context links.`
+                : '';
+            return `${mode} ${result.scanned} notes: changed=${result.changed}, createdHubs=${result.createdHubs}, skipped=${result.skipped}.${indexMessage}`;
+        });
+    });
     program
         .command('db-import')
         .option('-v, --vault <vault>', 'vault directory')
@@ -729,6 +796,29 @@ export const registerWriteCommands = (program) => {
             return `${summary}${indexMessage}${dryRunMessage}`;
         });
     });
+    program
+        .command('volatile')
+        .option('-c, --content <content>', 'temporary memory content to add')
+        .option('--ttl <minutes>', 'time-to-live in minutes', '240')
+        .option('--tag <tag...>', 'volatile memory tag')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--clear', 'clear volatile memory for the current agent namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('add or clear temporary agent-decided memory')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        if (options.clear) {
+            const cleared = await clearVolatileMemory(resolved.vault, resolved.agent);
+            print(options.json, { cleared, agent: resolved.agent ?? 'shared' }, () => `Cleared ${cleared} volatile memories.`);
+            return;
+        }
+        if (!options.content || options.content.trim().length === 0) {
+            throw new Error('Use --content to add volatile memory, or --clear to remove it.');
+        }
+        const entry = await addVolatileMemory(resolved.vault, options.content, resolved.agent ?? 'shared', parsePositiveInteger(options.ttl ?? '240', 240), options.tag ?? []);
+        print(options.json, { entry }, () => `Stored volatile memory until ${entry.expiresAt}.`);
+    });
     program
         .command('add')
         .argument('<title>', 'note title')
@@ -737,6 +827,7 @@ export const registerWriteCommands = (program) => {
         .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'agent memory namespace')
         .option('--allow-sensitive', 'allow writing content that looks like a secret')
+        .option('--no-auto-context-links', 'skip canonical Context Links for this note')
         .option('--no-auto-index', 'skip reindexing after add')
         .option('--json', 'print machine-readable JSON')
         .description('add a markdown note to the vault')
@@ -744,7 +835,8 @@ export const registerWriteCommands = (program) => {
         const resolved = await resolveOptions(options);
         const content = resolveAddContent(options);
         const added = await addNoteWithMetadata(resolved.vault, title, content, resolved.agent, {
-            allowSensitive: Boolean(options.allowSensitive)
+            allowSensitive: Boolean(options.allowSensitive),
+            autoContextLinks: options.autoContextLinks !== false && resolved.config.autoCanonicalContextLinks
         });
         const shouldAutoIndex = options.autoIndex !== false && resolved.config.autoIndexOnWrite;
         const index = shouldAutoIndex ? await indexVault(resolved.vault) : undefined;
@@ -768,7 +860,9 @@ export const registerWriteCommands = (program) => {
             writeConnectivity: {
                 autoLinked: added.autoLinked,
                 linkTarget: added.linkTarget,
-                guaranteedEdge: true
+                context: added.context,
+                hubCreated: added.hubCreated,
+                guaranteedEdge: added.autoLinked
             },
             possibleDuplicates,
             ...(index ? { index } : {})
@@ -776,8 +870,33 @@ export const registerWriteCommands = (program) => {
             const duplicateMessage = possibleDuplicates.length > 0
                 ? `\nPotential duplicates: ${possibleDuplicates.length}. Use "blink dedupe --json" or "blink dedupe-resolve".`
                 : '';
-            return `Created note at ${added.path}${duplicateMessage}`;
+            const linkMessage = added.autoLinked ? ` Linked to [[${added.linkTarget}]].` : '';
+            return `Created note at ${added.path}.${linkMessage}${duplicateMessage}`;
+        });
+    });
+    program
+        .command('delete-note')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace when deleting by title')
+        .option('--title <title>', 'note title to delete')
+        .option('--path <path>', 'vault-relative or absolute markdown note path to delete')
+        .option('--yes', 'confirm note deletion')
+        .option('--no-auto-index', 'skip reindexing after delete')
+        .option('--json', 'print machine-readable JSON')
+        .description('delete a Markdown note from the vault after explicit confirmation')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await deleteNote(resolved.vault, {
+            title: options.title,
+            path: options.path,
+            agentId: resolved.agent,
+            confirm: Boolean(options.yes),
+            autoIndex: options.autoIndex !== false
         });
+        print(options.json, {
+            vault: resolved.vault,
+            ...result
+        }, () => `Deleted note ${result.relativePath}.`);
     });
     program
         .command('dedupe')
@@ -836,12 +955,17 @@ export const registerWriteCommands = (program) => {
     program
         .command('index')
         .option('-v, --vault <vault>', 'vault directory')
+        .option('--full', 'force a complete reindex from Markdown source without reusing unchanged index entries')
         .option('--json', 'print machine-readable JSON')
         .description('index markdown notes, links, tags and chunks')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
-        const result = await indexVault(resolved.vault);
-        print(options.json, result, () => `Indexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`);
+        const result = await indexVault(resolved.vault, {
+            full: options.full === true
+        });
+        print(options.json, result, () => options.full === true
+            ? `Fully reindexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`
+            : `Indexed ${result.documentCount} documents, ${result.chunkCount} chunks and ${result.linkCount} links`);
     });
     program
         .command('bench')
@@ -976,26 +1100,28 @@ export const registerWriteCommands = (program) => {
         .option('-p, --port <port>', 'server port', '4321')
         .option('--no-index', 'skip indexing before starting the server')
         .option('--no-open', 'do not open the graph UI automatically')
-        .option('-w, --watch', 'watch markdown files and reindex on changes')
+        .option('-w, --watch', 'watch markdown files and reindex on changes', true)
+        .option('--no-watch', 'disable markdown file watching')
         .option('--json', 'print machine-readable JSON')
         .description('start a local web UI for the knowledge graph')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
+        const shouldWatch = options.watch !== false && !isBucketVaultPath(resolved.vault);
         const server = await startServer({
             vaultPath: resolved.vault,
             host: options.host ?? resolved.config.host,
             port: parsePositiveInteger(options.port ?? String(resolved.config.port), resolved.config.port),
             shouldIndex: options.index,
-            shouldWatch: Boolean(options.watch)
+            shouldWatch
         });
         const openResult = options.open !== false ? openUrlInUi(server.url, process.pid) : { opened: false, mode: 'none' };
         print(options.json, {
             url: server.url,
-            watch: Boolean(options.watch),
+            watch: shouldWatch,
             readonly: true,
             openedUi: openResult.opened,
             openMode: openResult.mode
-        }, () => `Brainlink graph server running at ${server.url}${openResult.opened
+        }, () => `Brainlink graph server running at ${server.url} (${shouldWatch ? 'watching for changes' : 'watch disabled'})${openResult.opened
             ? openResult.mode === 'native-gui'
                 ? ' (opened in native desktop GUI)'
                 : openResult.mode === 'app-window'
@@ -1005,12 +1131,45 @@ export const registerWriteCommands = (program) => {
                 ? ' (auto-open disabled)'
                 : ''}`);
     });
+    program
+        .command('mcp-server')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-h, --host <host>', 'remote MCP server host', '0.0.0.0')
+        .option('-p, --port <port>', 'remote MCP server port', '3333')
+        .option('--path <path>', 'remote MCP endpoint path', '/mcp')
+        .option('--token <token>', 'bearer token required for MCP requests')
+        .option('--no-index', 'skip indexing before starting the MCP server')
+        .option('--json', 'print machine-readable JSON')
+        .description('start a remote MCP server for centralized cluster access')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const token = options.token ?? process.env.BRAINLINK_MCP_TOKEN;
+        const server = await startRemoteMcpServer({
+            vaultPath: resolved.vault,
+            agent: resolved.agent,
+            host: options.host ?? '0.0.0.0',
+            port: parsePositiveInteger(options.port ?? '3333', 3333),
+            path: options.path ?? '/mcp',
+            token,
+            shouldIndex: options.index
+        });
+        print(options.json, {
+            url: server.url,
+            healthUrl: server.healthUrl,
+            readyUrl: server.readyUrl,
+            vault: resolved.vault,
+            agent: resolved.agent ?? '*',
+            auth: token === undefined ? 'disabled' : 'bearer'
+        }, () => `Brainlink remote MCP server running at ${server.url} (health: ${server.healthUrl}, readiness: ${server.readyUrl})`);
+    });
     program
         .command('quickstart')
         .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'agent memory namespace')
         .option('--query <query>', 'optional task query to return immediate grounded context')
         .option('--mode <mode>', 'search mode for context (fts|semantic|hybrid)')
+        .option('--strategy <strategy>', 'context strategy for context (rag|cag|auto)')
         .option('--limit <limit>', 'maximum context sections')
         .option('--tokens <tokens>', 'maximum context token budget')
         .option('--no-install-agent', 'skip agent MCP/plugin installation and upgrade automation')
@@ -1025,6 +1184,7 @@ export const registerWriteCommands = (program) => {
         const limit = parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit);
         const tokens = parsePositiveInteger(options.tokens ?? String(resolved.defaults.defaultContextTokens), resolved.defaults.defaultContextTokens);
         const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
+        const strategy = sanitizeContextStrategy(options.strategy, resolved.defaults.defaultContextStrategy);
         const index = await indexVault(resolved.vault);
         const stats = await getStats(resolved.vault, resolved.agent);
         const validation = await validateVault(resolved.vault, resolved.agent);
@@ -1033,7 +1193,7 @@ export const registerWriteCommands = (program) => {
         const policy = await getBootstrapPolicy();
         const bootstrapStatus = await getBootstrapSessionStatus(resolved.vault, resolved.agent);
         const context = options.query
-            ? await buildContextPackage(resolved.vault, options.query, limit, tokens, resolved.agent, mode)
+            ? await buildContextPackage(resolved.vault, options.query, limit, tokens, resolved.agent, mode, strategy, resolved.defaults.defaultContextCacheTtlMs)
             : null;
         const agentIntegration = options.installAgent === false
             ? null

package/dist/cli/main.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { registerAgentCommands } from './commands/agent-commands.js';
 import { registerConfigCommands } from './commands/config-commands.js';
 import { registerReadCommands } from './commands/read-commands.js';
+import { registerVaultCommands } from './commands/vault-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
 const readPackageVersion = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
@@ -24,6 +25,7 @@ program
 registerWriteCommands(program);
 registerReadCommands(program);
 registerConfigCommands(program);
+registerVaultCommands(program);
 registerAgentCommands(program);
 program.parseAsync().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);

package/dist/cli/runtime.js

@@ -1,11 +1,19 @@
-import { loadBrainlinkConfig, resolveAgentRuntimeDefaults } from '../infrastructure/config.js';
+import { autoMigrateConfiguredVaultIfChanged } from '../application/auto-migrate-configured-vault.js';
+import { loadBrainlinkConfigWithSource, resolveAgentRuntimeDefaults } from '../infrastructure/config.js';
 import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
 export const parsePositiveInteger = (value, fallback) => {
     const parsed = Number.parseInt(value, 10);
     return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 };
 export const resolveOptions = async (options) => {
-    const config = await loadBrainlinkConfig();
+    const { config, vaultSource } = await loadBrainlinkConfigWithSource();
+    if (options.vault === undefined) {
+        const sourceKey = vaultSource.sourcePath ? `${vaultSource.source}:${vaultSource.sourcePath}` : vaultSource.source;
+        await autoMigrateConfiguredVaultIfChanged({
+            configKey: sourceKey,
+            configuredVault: config.vault
+        });
+    }
     const vault = options.vault ?? config.vault;
     const allowedVault = assertVaultAllowed(vault, config.allowedVaults);
     const agent = options.agent ?? config.defaultAgent;

package/dist/domain/context.js

@@ -76,6 +76,7 @@ export const formatContextPackage = (query, sections) => {
         section.tags.length > 0 ? `Tags: ${section.tags.map((tag) => `#${tag}`).join(' ')}` : null,
         `Score: ${section.score.toFixed(3)}`,
         `Mode: ${section.searchMode}`,
+        section.volatile ? `Volatile: true${section.expiresAt ? `, expires ${section.expiresAt}` : ''}` : null,
         '',
         section.content
     ]

package/dist/domain/graph-contexts.js

@@ -0,0 +1,180 @@
+const normalize = (value) => value.trim().toLowerCase();
+const includesAny = (value, patterns) => patterns.some((pattern) => pattern.test(value));
+const contextId = (title) => title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+const context = (title) => ({
+    id: contextId(title),
+    title
+});
+const byTitle = (left, right) => left.title.localeCompare(right.title);
+const edgeKey = (source, target) => source < target ? `${source}|${target}` : `${target}|${source}`;
+const nodeSearchText = (node) => normalize([node.title, node.path, ...node.tags].join(' '));
+export const inferExplicitVisualGraphContext = (node) => {
+    const text = nodeSearchText(node);
+    const path = normalize(node.path);
+    if (includesAny(text, [/\bgithub repositories hub\b/]))
+        return context('GitHub Repositories');
+    if (includesAny(text, [/\bgithub organizations hub\b/]))
+        return context('GitHub Organizations');
+    if (includesAny(text, [/\bmachine configuration hub\b/]))
+        return context('Machine Configuration');
+    if (includesAny(text, [/\buser preferences hub\b/]))
+        return context('User Preferences');
+    if (includesAny(text, [/\bneovim lazyvim hub\b/]))
+        return context('Neovim LazyVim');
+    if (includesAny(text, [/\bgit workflow hub\b/]))
+        return context('Git Workflow');
+    if (includesAny(text, [/\bagent memory hub\b/]))
+        return context('Agent Memory');
+    if (includesAny(text, [/pingu_ai_codding_pair_programming/, /\bpingu\b/]))
+        return context('Pingu');
+    if (path.startsWith('github-repos/'))
+        return context('GitHub Repositories');
+    if (path.startsWith('github-org-repos/'))
+        return context('GitHub Organizations');
+    if (path.startsWith('machine-config/'))
+        return context('Machine Configuration');
+    if (includesAny(text, [/\bbrainlink\b/]))
+        return context('Brainlink');
+    if (includesAny(text, [/\banonspace\b/]))
+        return context('AnonSpace');
+    if (includesAny(text, [/\bsubstructa\b/]))
+        return context('Substructa');
+    if (includesAny(text, [/\bnebula\b/]))
+        return context('Nebula');
+    if (includesAny(text, [/\bsnippets?\b/, /\bupgrader\b/, /\bversion-map\b/]))
+        return context('Snippets');
+    if (includesAny(text, [
+        /\bpreference\b/,
+        /\bpreferences\b/,
+        /\bpreferencia\b/,
+        /\bpreferencias\b/,
+        /\bpreferência\b/,
+        /\bpreferências\b/,
+        /\bplaybook\b/,
+        /\bdirective\b/,
+        /\bdirectives\b/,
+        /\bdiretiva\b/,
+        /\bdiretivas\b/,
+        /\bengineering-style\b/,
+        /\bglobal-engineering\b/,
+        /\bcoding-identity\b/,
+        /\bagents\.md\b/,
+        /\bagents-md\b/,
+        /\bordem direta\b/,
+        /\bordem-direta\b/,
+        /\bman-in-the-loop\b/,
+        /\bconfig geral\b/,
+        /\bconfig-geral\b/,
+        /\bsync config_files\b/,
+        /\bsync-config-files\b/,
+        /\bregra operacional\b/,
+        /\bregras operacionais\b/,
+        /\boperational rule\b/,
+        /\boperational rules\b/,
+        /\boperational policy\b/
+    ])) {
+        return context('User Preferences');
+    }
+    if (includesAny(text, [/\binkdrop\b/]))
+        return context('Inkdrop');
+    if (includesAny(text, [/\blazyvim\b/, /\bneovim\b/, /\bnvim\b/, /\bmason\b/, /\bwrapper\b/]))
+        return context('Neovim LazyVim');
+    if (includesAny(text, [/\bgit-flow\b/, /\borigin-sync\b/, /\bgit-identidade\b/, /\bcommit\b/, /\bpush\b/]))
+        return context('Git Workflow');
+    if (includesAny(text, [/\bdocker\b/, /\bkubernetes\b/, /\bdeploy\b/, /\bredeploy\b/]))
+        return context('Operations');
+    if (path.startsWith('agents/'))
+        return context('Agent Memory');
+    return null;
+};
+export const inferVisualGraphContext = (node) => {
+    const explicit = inferExplicitVisualGraphContext(node);
+    if (explicit) {
+        return explicit;
+    }
+    const [root] = node.path.split('/').filter(Boolean);
+    return context(root ? root.replace(/[-_]+/g, ' ') : 'Root');
+};
+export const groupNodesByVisualContext = (nodes) => {
+    const groups = new Map();
+    nodes.forEach((node) => {
+        const visualContext = inferVisualGraphContext(node);
+        const bucket = groups.get(visualContext.title);
+        if (bucket) {
+            bucket.push(node);
+            return;
+        }
+        groups.set(visualContext.title, [node]);
+    });
+    return new Map(Array.from(groups.entries(), ([title, groupedNodes]) => [title, [...groupedNodes].sort(byTitle)]));
+};
+const countDegrees = (edges) => edges.reduce((degrees, edge) => {
+    degrees.set(edge.source, (degrees.get(edge.source) ?? 0) + edge.weight);
+    if (edge.target) {
+        degrees.set(edge.target, (degrees.get(edge.target) ?? 0) + edge.weight);
+    }
+    return degrees;
+}, new Map());
+const selectVisualHub = (contextTitle, nodes, degrees) => {
+    const normalizedContext = normalize(contextTitle).replace(/\s+/g, ' ');
+    const ranked = [...nodes].sort((left, right) => {
+        const leftTitle = normalize(left.title);
+        const rightTitle = normalize(right.title);
+        const leftHubScore = leftTitle === normalizedContext || leftTitle === `${normalizedContext} hub`
+            ? 4
+            : leftTitle.includes(normalizedContext) && /\bhub\b/.test(leftTitle)
+                ? 3
+                : /\b(memory hub|knowledge root|moc|map|hub)\b/.test(leftTitle)
+                    ? 2
+                    : 0;
+        const rightHubScore = rightTitle === normalizedContext || rightTitle === `${normalizedContext} hub`
+            ? 4
+            : rightTitle.includes(normalizedContext) && /\bhub\b/.test(rightTitle)
+                ? 3
+                : /\b(memory hub|knowledge root|moc|map|hub)\b/.test(rightTitle)
+                    ? 2
+                    : 0;
+        const hubDelta = rightHubScore - leftHubScore;
+        if (hubDelta !== 0)
+            return hubDelta;
+        const degreeDelta = (degrees.get(right.id) ?? 0) - (degrees.get(left.id) ?? 0);
+        return degreeDelta === 0 ? left.title.localeCompare(right.title) : degreeDelta;
+    });
+    return ranked[0] ?? null;
+};
+export const addVisualContextEdges = (graph) => {
+    const existingPairs = new Set(graph.edges
+        .filter((edge) => Boolean(edge.target))
+        .map((edge) => edgeKey(edge.source, edge.target)));
+    const degrees = countDegrees(graph.edges);
+    const derivedEdges = [];
+    for (const [contextTitle, nodes] of groupNodesByVisualContext(graph.nodes).entries()) {
+        if (nodes.length <= 1) {
+            continue;
+        }
+        const hub = selectVisualHub(contextTitle, nodes, degrees);
+        if (!hub) {
+            continue;
+        }
+        nodes
+            .filter((node) => node.id !== hub.id)
+            .forEach((node) => {
+            const key = edgeKey(hub.id, node.id);
+            if (existingPairs.has(key)) {
+                return;
+            }
+            existingPairs.add(key);
+            derivedEdges.push({
+                source: hub.id,
+                target: node.id,
+                targetTitle: node.title,
+                weight: 0.5,
+                priority: 'low'
+            });
+        });
+    }
+    return {
+        nodes: graph.nodes,
+        edges: [...graph.edges, ...derivedEdges]
+    };
+};