@andespindola/brainlink 0.1.0-beta.16 → 0.1.0-beta.160

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

@@ -1,17 +1,25 @@
-import { readFileSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { dirname, relative, resolve } from 'node:path';
-import { addNote } from '../../application/add-note.js';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+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 { indexVault } from '../../application/index-vault.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 { 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 { installAgentIntegration } from './agent-commands.js';
 import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
 const resolveAddContent = (options) => {
@@ -23,6 +31,600 @@ const resolveAddContent = (options) => {
     }
     return readFileSync(options.contentFile, 'utf8');
 };
+const parseScore = (value, fallback) => {
+    if (value == null) {
+        return fallback;
+    }
+    const parsed = Number.parseFloat(value);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        throw new Error(`Invalid score value: ${value}. Expected a number between 0 and 1.`);
+    }
+    return parsed;
+};
+const formatBytes = (bytes) => {
+    if (!Number.isFinite(bytes) || bytes == null) {
+        return 'n/a';
+    }
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes / 1024;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    return `${value.toFixed(value >= 10 ? 1 : 2)} ${units[unitIndex]}`;
+};
+const formatMs = (value) => Number.isFinite(value) && value != null ? `${value.toFixed(value >= 100 ? 0 : 1)}ms` : 'n/a';
+const benchEventLabel = (event) => `${event.phase}:${event.status}`;
+const printBenchRealtimeEvent = (json, event) => {
+    print(json, {
+        event: 'bench-progress',
+        ...event
+    }, () => `[bench] ${benchEventLabel(event)} ${event.message} (${formatMs(event.elapsedMs)})`);
+};
+const printBenchSummary = (json, trigger, vault, result) => {
+    print(json, {
+        event: 'bench-result',
+        trigger,
+        vault,
+        result
+    }, () => {
+        const packs = result.packs;
+        const compression = packs?.compression;
+        const savedPercent = compression && compression.inputBytes > 0
+            ? `${((1 - compression.ratio) * 100).toFixed(1)}%`
+            : 'n/a';
+        return [
+            `[bench] trigger=${trigger}`,
+            `documents=${result.documentCount} chunks=${result.chunkCount} links=${result.linkCount}`,
+            `changedDocuments=${result.changedDocumentCount ?? 0} totalElapsed=${formatMs(result.elapsedMs)}`,
+            `packsRebuilt=${packs?.rebuilt ? 'yes' : 'no'} reason=${packs?.reason ?? 'n/a'}`,
+            packs?.rebuilt
+                ? `packCount=${packs.packCount ?? 0} packDuration=${formatMs(packs.durationMs)} input=${formatBytes(compression?.inputBytes)} output=${formatBytes(compression?.outputBytes)} saved=${savedPercent}`
+                : 'packCompression=n/a'
+        ].join('\n');
+    });
+};
+const benchHistoryPath = (vaultPath) => join(vaultPath, '.brainlink', 'benchmarks', 'latest.json');
+const readBenchHistory = async (vaultPath) => {
+    try {
+        const parsed = JSON.parse(await readFile(benchHistoryPath(vaultPath), 'utf8'));
+        if (typeof parsed.elapsedMs !== 'number' || typeof parsed.timestamp !== 'string') {
+            return null;
+        }
+        return {
+            elapsedMs: parsed.elapsedMs,
+            timestamp: parsed.timestamp,
+            ...(typeof parsed.compressionRatio === 'number' ? { compressionRatio: parsed.compressionRatio } : {})
+        };
+    }
+    catch {
+        return null;
+    }
+};
+const writeBenchHistory = async (vaultPath, result) => {
+    await mkdir(dirname(benchHistoryPath(vaultPath)), { recursive: true });
+    const payload = {
+        elapsedMs: result.elapsedMs ?? 0,
+        timestamp: new Date().toISOString(),
+        ...(typeof result.packs?.compression?.ratio === 'number' ? { compressionRatio: result.packs.compression.ratio } : {})
+    };
+    await writeFile(benchHistoryPath(vaultPath), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+};
+const evaluateBenchGuardrails = (config, result, baseline) => {
+    const compressionRatio = result.packs?.compression?.ratio;
+    const compressionSavingsPercent = typeof compressionRatio === 'number' ? Math.max(0, (1 - compressionRatio) * 100) : undefined;
+    const compressionPass = compressionSavingsPercent != null
+        ? compressionSavingsPercent >= config.searchPack.guardrailMinSavingsPercent
+        : undefined;
+    const latencyRegressionPercent = baseline && baseline.elapsedMs > 0 && typeof result.elapsedMs === 'number'
+        ? ((result.elapsedMs - baseline.elapsedMs) / baseline.elapsedMs) * 100
+        : undefined;
+    const latencyPass = latencyRegressionPercent != null
+        ? latencyRegressionPercent <= config.searchPack.guardrailMaxLatencyRegressionPercent
+        : undefined;
+    return {
+        ...(compressionSavingsPercent != null ? { compressionSavingsPercent } : {}),
+        ...(compressionPass != null ? { compressionPass } : {}),
+        ...(latencyRegressionPercent != null ? { latencyRegressionPercent } : {}),
+        ...(latencyPass != null ? { latencyPass } : {})
+    };
+};
+const printBenchGuardrails = (json, vault, config, guardrails) => {
+    print(json, {
+        event: 'bench-guardrails',
+        vault,
+        thresholds: {
+            minSavingsPercent: config.searchPack.guardrailMinSavingsPercent,
+            maxLatencyRegressionPercent: config.searchPack.guardrailMaxLatencyRegressionPercent
+        },
+        guardrails
+    }, () => {
+        const savings = guardrails.compressionSavingsPercent;
+        const latency = guardrails.latencyRegressionPercent;
+        return [
+            '[bench] guardrails',
+            `minSavings=${config.searchPack.guardrailMinSavingsPercent.toFixed(1)}% maxLatencyRegression=${config.searchPack.guardrailMaxLatencyRegressionPercent.toFixed(1)}%`,
+            `compressionSavings=${savings != null ? `${savings.toFixed(2)}%` : 'n/a'} pass=${guardrails.compressionPass != null ? (guardrails.compressionPass ? 'yes' : 'no') : 'n/a'}`,
+            `latencyRegression=${latency != null ? `${latency.toFixed(2)}%` : 'n/a'} pass=${guardrails.latencyPass != null ? (guardrails.latencyPass ? 'yes' : 'no') : 'n/a'}`
+        ].join('\n');
+    });
+};
+const spawnDetached = (command, args, envOverrides) => {
+    try {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: 'ignore',
+            env: envOverrides ? { ...process.env, ...envOverrides } : process.env
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const nativeGuiSwiftScriptPath = join(tmpdir(), 'brainlink-native-gui.swift');
+const nativeGuiPowershellScriptPath = join(tmpdir(), 'brainlink-native-gui.ps1');
+const nativeGuiLinuxScriptPath = join(tmpdir(), 'brainlink-native-gui-linux.py');
+const nativeGuiSwiftScript = `import Foundation
+import AppKit
+import WebKit
+import Darwin
+
+final class BrainlinkAppDelegate: NSObject, NSApplicationDelegate, NSWindowDelegate {
+  private let targetUrl: URL
+  private let parentPid: Int32
+  private var window: NSWindow?
+  private var webView: WKWebView?
+  private var monitorTimer: Timer?
+
+  init(targetUrl: URL, parentPid: Int32) {
+    self.targetUrl = targetUrl
+    self.parentPid = parentPid
+  }
+
+  func applicationDidFinishLaunching(_ notification: Notification) {
+    let window = NSWindow(
+      contentRect: NSRect(x: 0, y: 0, width: 1320, height: 860),
+      styleMask: [.titled, .closable, .miniaturizable, .resizable],
+      backing: .buffered,
+      defer: false
+    )
+    window.title = "Brainlink Graph"
+    window.center()
+    window.isReleasedWhenClosed = false
+    window.delegate = self
+
+    let webView = WKWebView(frame: window.contentView?.bounds ?? .zero)
+    webView.autoresizingMask = [.width, .height]
+    webView.allowsBackForwardNavigationGestures = true
+    webView.load(URLRequest(url: targetUrl))
+    window.contentView?.addSubview(webView)
+
+    self.window = window
+    self.webView = webView
+
+    if parentPid > 0 {
+      monitorTimer = Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { _ in
+        if kill(self.parentPid, 0) != 0 {
+          NSApp.terminate(nil)
+        }
+      }
+    }
+
+    window.makeKeyAndOrderFront(nil)
+    NSApp.activate(ignoringOtherApps: true)
+  }
+
+  func windowWillClose(_ notification: Notification) {
+    monitorTimer?.invalidate()
+    NSApp.terminate(nil)
+  }
+}
+
+let args = Array(CommandLine.arguments.dropFirst())
+let rawTarget = args.indices.contains(0) ? args[0] : "http://127.0.0.1:4321"
+let parentPid: Int32 = args.indices.contains(1) ? (Int32(args[1]) ?? 0) : 0
+
+guard let targetUrl = URL(string: rawTarget) else {
+  fputs("Invalid URL for Brainlink GUI: \\(rawTarget)\\n", stderr)
+  exit(1)
+}
+
+let app = NSApplication.shared
+app.setActivationPolicy(.regular)
+let delegate = BrainlinkAppDelegate(targetUrl: targetUrl, parentPid: parentPid)
+app.delegate = delegate
+app.run()
+`;
+const nativeGuiPowershellScript = `param(
+  [string]$TargetUrl = "http://127.0.0.1:4321",
+  [int]$ParentPid = 0
+)
+
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+[System.Windows.Forms.Application]::EnableVisualStyles()
+
+$form = New-Object System.Windows.Forms.Form
+$form.Text = "Brainlink Graph"
+$form.Width = 1320
+$form.Height = 860
+$form.StartPosition = "CenterScreen"
+
+$browser = New-Object System.Windows.Forms.WebBrowser
+$browser.Dock = [System.Windows.Forms.DockStyle]::Fill
+$browser.ScriptErrorsSuppressed = $true
+$browser.Navigate($TargetUrl)
+
+$form.Controls.Add($browser)
+$timer = New-Object System.Windows.Forms.Timer
+$timer.Interval = 1000
+$timer.Add_Tick({
+  if ($ParentPid -le 0) {
+    return
+  }
+  try {
+    Get-Process -Id $ParentPid -ErrorAction Stop | Out-Null
+  } catch {
+    $timer.Stop()
+    $form.Close()
+  }
+})
+$form.Add_FormClosed({
+  $timer.Stop()
+})
+$timer.Start()
+[void]$form.ShowDialog()
+`;
+const nativeGuiLinuxPythonScript = `#!/usr/bin/env python3
+import sys
+
+def run() -> int:
+    try:
+        import gi
+        gi.require_version("Gtk", "3.0")
+        try:
+            gi.require_version("WebKit2", "4.1")
+        except ValueError:
+            gi.require_version("WebKit2", "4.0")
+        from gi.repository import Gtk, WebKit2, GLib
+    except Exception:
+        return 1
+
+    target_url = sys.argv[1] if len(sys.argv) > 1 else "http://127.0.0.1:4321"
+    parent_pid = int(sys.argv[2]) if len(sys.argv) > 2 else 0
+
+    window = Gtk.Window(title="Brainlink Graph")
+    window.set_default_size(1320, 860)
+    window.connect("destroy", Gtk.main_quit)
+
+    webview = WebKit2.WebView()
+    webview.load_uri(target_url)
+    window.add(webview)
+    window.show_all()
+
+    if parent_pid > 0:
+        def _watch_parent() -> bool:
+            try:
+                import os
+                os.kill(parent_pid, 0)
+            except Exception:
+                Gtk.main_quit()
+                return False
+            return True
+
+        GLib.timeout_add(1000, _watch_parent)
+
+    Gtk.main()
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(run())
+`;
+const commandExists = (command) => {
+    try {
+        const probe = platform() === 'win32'
+            ? spawnSync('where', [command], { stdio: 'ignore' })
+            : spawnSync('which', [command], { stdio: 'ignore' });
+        return probe.status === 0;
+    }
+    catch {
+        return false;
+    }
+};
+const readLinuxDefaultBrowserDesktopEntry = () => {
+    try {
+        const preferred = spawnSync('xdg-settings', ['get', 'default-web-browser'], { encoding: 'utf8' });
+        const rawPreferred = preferred.status === 0 ? preferred.stdout.trim() : '';
+        if (rawPreferred.length > 0) {
+            return rawPreferred;
+        }
+    }
+    catch {
+        // fallback below
+    }
+    try {
+        const fallback = spawnSync('xdg-mime', ['query', 'default', 'x-scheme-handler/https'], { encoding: 'utf8' });
+        const rawFallback = fallback.status === 0 ? fallback.stdout.trim() : '';
+        return rawFallback.length > 0 ? rawFallback : null;
+    }
+    catch {
+        return null;
+    }
+};
+const toLinuxDefaultBrowserCommands = (desktopEntry) => {
+    if (!desktopEntry) {
+        return [];
+    }
+    const normalized = desktopEntry.toLowerCase().trim();
+    if (normalized.includes('firefox')) {
+        return ['firefox'];
+    }
+    if (normalized.includes('edge')) {
+        return ['microsoft-edge', 'microsoft-edge-stable'];
+    }
+    if (normalized.includes('brave')) {
+        return ['brave-browser'];
+    }
+    if (normalized.includes('chromium')) {
+        return ['chromium', 'chromium-browser'];
+    }
+    if (normalized.includes('chrome')) {
+        return ['google-chrome', 'google-chrome-stable'];
+    }
+    return [];
+};
+const readBrowserEnvCommands = () => {
+    const value = process.env.BROWSER?.trim();
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(':')
+        .map((entry) => entry.trim().split(/\s+/)[0] ?? '')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+};
+const prioritizeLinuxBrowserCandidates = (candidates) => {
+    const preferredCommands = toLinuxDefaultBrowserCommands(readLinuxDefaultBrowserDesktopEntry());
+    if (preferredCommands.length === 0) {
+        return candidates;
+    }
+    const priorityMap = new Map(preferredCommands.map((command, index) => [command, index]));
+    return [...candidates].sort((left, right) => {
+        const leftPriority = priorityMap.get(left[0]);
+        const rightPriority = priorityMap.get(right[0]);
+        const leftScore = leftPriority == null ? Number.POSITIVE_INFINITY : leftPriority;
+        const rightScore = rightPriority == null ? Number.POSITIVE_INFINITY : rightPriority;
+        return leftScore - rightScore;
+    });
+};
+const envFlagEnabled = (name) => process.env[name] === '1' || process.env[name] === 'true';
+const spawnAnyDetached = (candidates) => candidates.some(([command, args]) => spawnDetached(command, args));
+const spawnAnyDetachedWithEnv = (candidates) => candidates.some(([command, args, env]) => spawnDetached(command, args, env));
+const windowsStartCandidates = (program, args = []) => [
+    ['cmd', ['/c', 'start', '', program, ...args]]
+];
+const resolveSwiftExecutable = () => {
+    const directSwift = '/usr/bin/swift';
+    if (existsSync(directSwift)) {
+        return directSwift;
+    }
+    try {
+        const probe = spawnSync('xcrun', ['--find', 'swift'], { encoding: 'utf8' });
+        const swiftPath = probe.status === 0 ? probe.stdout.trim() : '';
+        return swiftPath.length > 0 ? swiftPath : null;
+    }
+    catch {
+        return null;
+    }
+};
+const openGraphInMacNativeGui = (url, parentPid) => {
+    const swiftBinary = resolveSwiftExecutable();
+    if (!swiftBinary) {
+        return false;
+    }
+    try {
+        writeFileSync(nativeGuiSwiftScriptPath, nativeGuiSwiftScript, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    return spawnDetached(swiftBinary, [nativeGuiSwiftScriptPath, url, String(parentPid)]);
+};
+const resolveWindowsPowershellExecutable = () => {
+    if (commandExists('powershell')) {
+        return 'powershell';
+    }
+    if (commandExists('pwsh')) {
+        return 'pwsh';
+    }
+    return null;
+};
+const openGraphInWindowsNativeGui = (url, parentPid) => {
+    const powershell = resolveWindowsPowershellExecutable();
+    if (!powershell) {
+        return false;
+    }
+    try {
+        writeFileSync(nativeGuiPowershellScriptPath, nativeGuiPowershellScript, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    return spawnDetached(powershell, ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-STA', '-File', nativeGuiPowershellScriptPath, url, String(parentPid)]);
+};
+const openGraphInLinuxNativeGui = (url, parentPid) => {
+    if (!commandExists('python3')) {
+        return false;
+    }
+    try {
+        writeFileSync(nativeGuiLinuxScriptPath, nativeGuiLinuxPythonScript, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    return spawnDetached('python3', [nativeGuiLinuxScriptPath, url, String(parentPid)]);
+};
+const openGraphInNativeGui = (url, parentPid) => {
+    if (platform() === 'darwin') {
+        return openGraphInMacNativeGui(url, parentPid);
+    }
+    if (platform() === 'win32') {
+        return openGraphInWindowsNativeGui(url, parentPid);
+    }
+    return openGraphInLinuxNativeGui(url, parentPid);
+};
+const openGraphInAppWindow = (url) => {
+    if (platform() === 'darwin') {
+        const macCandidates = [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+            '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'
+        ]
+            .filter((candidate) => existsSync(candidate))
+            .map((binary) => ({ binary, args: [`--app=${url}`, '--new-window'] }));
+        for (const candidate of macCandidates) {
+            if (spawnDetached(candidate.binary, candidate.args)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    if (platform() === 'win32') {
+        const appArgument = `--app=${url}`;
+        return spawnAnyDetached([
+            ...windowsStartCandidates('msedge', [appArgument, '--new-window']),
+            ...windowsStartCandidates('chrome', [appArgument, '--new-window']),
+            ...windowsStartCandidates('chromium', [appArgument, '--new-window']),
+            ...windowsStartCandidates('brave', [appArgument, '--new-window'])
+        ]);
+    }
+    const appArgument = `--app=${url}`;
+    const linuxAppWindowEnabled = envFlagEnabled('BRAINLINK_LINUX_APP_WINDOW');
+    if (!linuxAppWindowEnabled) {
+        return false;
+    }
+    const linuxChromiumStableFlags = [
+        '--ozone-platform=x11',
+        '--ozone-platform-hint=x11',
+        '--disable-gpu',
+        '--disable-vulkan',
+        '--use-gl=swiftshader',
+        '--disable-features=Vulkan,VaapiVideoDecoder',
+        '--disable-background-networking'
+    ];
+    const linuxChromiumEnv = {
+        GDK_BACKEND: 'x11',
+        OZONE_PLATFORM: 'x11'
+    };
+    const linuxAppWindowCandidates = [
+        'microsoft-edge',
+        'microsoft-edge-stable',
+        'google-chrome',
+        'google-chrome-stable',
+        'chromium',
+        'chromium-browser',
+        'brave-browser'
+    ].filter((candidate) => commandExists(candidate));
+    return spawnAnyDetachedWithEnv(linuxAppWindowCandidates.map((command) => [
+        command,
+        [...linuxChromiumStableFlags, appArgument, '--new-window'],
+        linuxChromiumEnv
+    ]));
+};
+const openGraphInDetectedBrowser = (url) => {
+    if (platform() === 'win32') {
+        return spawnAnyDetached([
+            ...windowsStartCandidates('msedge', [url]),
+            ...windowsStartCandidates('chrome', [url]),
+            ...windowsStartCandidates('firefox', ['-new-window', url]),
+            ...windowsStartCandidates('chromium', [url]),
+            ...windowsStartCandidates('brave', [url])
+        ]);
+    }
+    const linuxChromiumStableFlags = [
+        '--ozone-platform=x11',
+        '--ozone-platform-hint=x11',
+        '--disable-gpu',
+        '--disable-vulkan',
+        '--use-gl=swiftshader',
+        '--disable-features=Vulkan,VaapiVideoDecoder',
+        '--disable-background-networking'
+    ];
+    const linuxChromiumEnv = {
+        GDK_BACKEND: 'x11',
+        OZONE_PLATFORM: 'x11'
+    };
+    const envBrowserCandidates = readBrowserEnvCommands()
+        .map((command) => command.includes('firefox')
+        ? [command, ['-new-window', url], undefined]
+        : [command, [url], undefined])
+        .filter(([command]) => commandExists(command));
+    if (envBrowserCandidates.length > 0 && spawnAnyDetachedWithEnv(envBrowserCandidates)) {
+        return true;
+    }
+    const linuxBrowserCandidates = [
+        ['firefox', ['-new-window', url], undefined],
+        ['microsoft-edge', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['microsoft-edge-stable', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['google-chrome', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['google-chrome-stable', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['brave-browser', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['chromium', [...linuxChromiumStableFlags, url], linuxChromiumEnv],
+        ['chromium-browser', [...linuxChromiumStableFlags, url], linuxChromiumEnv]
+    ];
+    const available = prioritizeLinuxBrowserCandidates(linuxBrowserCandidates.filter(([command]) => commandExists(command)));
+    return spawnAnyDetachedWithEnv(available);
+};
+const openUrlInUi = (url, parentPid) => {
+    const openDisabled = process.env.BRAINLINK_NO_BROWSER === '1' ||
+        process.env.BRAINLINK_NO_BROWSER === 'true' ||
+        process.env.CI === 'true';
+    if (openDisabled) {
+        return { opened: false, mode: 'none' };
+    }
+    const currentPlatform = platform();
+    const nativeGuiEnabled = !envFlagEnabled('BRAINLINK_NO_NATIVE_GUI') &&
+        (currentPlatform !== 'linux' || envFlagEnabled('BRAINLINK_LINUX_NATIVE_GUI') || envFlagEnabled('BRAINLINK_FORCE_NATIVE_GUI'));
+    if (nativeGuiEnabled && openGraphInNativeGui(url, parentPid)) {
+        return { opened: true, mode: 'native-gui' };
+    }
+    if (platform() === 'linux') {
+        if (spawnDetached('xdg-open', [url])) {
+            return { opened: true, mode: 'browser' };
+        }
+        if (openGraphInDetectedBrowser(url)) {
+            return { opened: true, mode: 'browser' };
+        }
+        if (openGraphInAppWindow(url)) {
+            return { opened: true, mode: 'app-window' };
+        }
+        return { opened: false, mode: 'none' };
+    }
+    if (openGraphInAppWindow(url)) {
+        return { opened: true, mode: 'app-window' };
+    }
+    try {
+        if (platform() === 'darwin') {
+            return { opened: spawnDetached('open', [url]), mode: 'browser' };
+        }
+        if (openGraphInDetectedBrowser(url)) {
+            return { opened: true, mode: 'browser' };
+        }
+        if (platform() === 'win32') {
+            return { opened: spawnDetached('cmd', ['/c', 'start', '', url]), mode: 'browser' };
+        }
+        return { opened: spawnDetached('xdg-open', [url]), mode: 'browser' };
+    }
+    catch {
+        return { opened: false, mode: 'none' };
+    }
+};
 export const registerWriteCommands = (program) => {
     program
         .command('init')
@@ -99,6 +701,122 @@ 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')
+        .option('--db <path>', 'legacy SQLite database path (default: <vault>/.brainlink/brainlink.db)')
+        .option('--table <name>', 'legacy table name override')
+        .option('-a, --agent <agent>', 'force imported notes into a target agent namespace')
+        .option('-l, --limit <limit>', 'maximum number of rows to import')
+        .option('--dry-run', 'preview import without writing Markdown files')
+        .option('--no-index', 'skip reindexing after import')
+        .option('--json', 'print machine-readable JSON')
+        .description('import legacy SQLite memory into Markdown vault and current index model')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await importLegacySqliteDatabase(resolved.vault, {
+            dbPath: options.db,
+            table: options.table,
+            agentOverride: options.agent ? resolved.agent : undefined,
+            limit: options.limit ? parsePositiveInteger(options.limit, 100_000) : undefined,
+            dryRun: Boolean(options.dryRun)
+        });
+        const shouldIndex = options.index !== false && !result.dryRun && result.imported > 0;
+        const index = shouldIndex ? await indexVault(resolved.vault) : undefined;
+        print(options.json, { ...result, ...(index ? { index } : {}) }, () => {
+            const summary = `Imported ${result.imported}/${result.rowsRead} rows from ${result.table} (skipped ${result.skipped}).`;
+            const indexMessage = index
+                ? ` Indexed ${index.documentCount} documents, ${index.chunkCount} chunks and ${index.linkCount} links.`
+                : '';
+            const dryRunMessage = result.dryRun ? ' Dry run only; no files were written.' : '';
+            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')
@@ -107,28 +825,178 @@ 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')
         .action(async (title, options) => {
         const resolved = await resolveOptions(options);
         const content = resolveAddContent(options);
-        const notePath = await addNote(resolved.vault, title, content, resolved.agent, {
-            allowSensitive: Boolean(options.allowSensitive)
+        const added = await addNoteWithMetadata(resolved.vault, title, content, resolved.agent, {
+            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;
-        print(options.json, { title, agent: resolved.agent ?? 'shared', path: notePath, ...(index ? { index } : {}) }, () => `Created note at ${notePath}`);
+        const absoluteVaultPath = await ensureVault(resolved.vault);
+        const focusPath = added.path.startsWith(absoluteVaultPath)
+            ? relative(absoluteVaultPath, added.path).replaceAll('\\', '/')
+            : added.path.includes('agents/')
+                ? added.path.slice(added.path.indexOf('agents/')).replaceAll('\\', '/')
+                : undefined;
+        const possibleDuplicates = await scanDuplicateNotes(resolved.vault, {
+            agentId: resolved.agent,
+            focusPath,
+            limit: 5,
+            minSemanticScore: 0.92,
+            includeSemantic: true
+        });
+        print(options.json, {
+            title,
+            agent: resolved.agent ?? 'shared',
+            path: added.path,
+            writeConnectivity: {
+                autoLinked: added.autoLinked,
+                linkTarget: added.linkTarget,
+                context: added.context,
+                hubCreated: added.hubCreated,
+                guaranteedEdge: added.autoLinked
+            },
+            possibleDuplicates,
+            ...(index ? { index } : {})
+        }, () => {
+            const duplicateMessage = possibleDuplicates.length > 0
+                ? `\nPotential duplicates: ${possibleDuplicates.length}. Use "blink dedupe --json" or "blink dedupe-resolve".`
+                : '';
+            const linkMessage = added.autoLinked ? ` Linked to [[${added.linkTarget}]].` : '';
+            return `Created note at ${added.path}.${linkMessage}${duplicateMessage}`;
+        });
+    });
+    program
+        .command('dedupe')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-l, --limit <limit>', 'maximum duplicate candidate pairs')
+        .option('--min-score <score>', 'minimum semantic similarity score between 0 and 1', '0.92')
+        .option('--no-semantic', 'disable semantic duplicate detection and keep exact-content matching only')
+        .option('--json', 'print machine-readable JSON')
+        .description('detect possible duplicate notes with exact hash and semantic similarity scores')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const duplicates = await scanDuplicateNotes(resolved.vault, {
+            agentId: resolved.agent,
+            limit: parsePositiveInteger(options.limit ?? '25', 25),
+            minSemanticScore: parseScore(options.minScore, 0.92),
+            includeSemantic: options.semantic !== false
+        });
+        print(options.json, { vault: resolved.vault, agent: resolved.agent, duplicates }, () => {
+            if (duplicates.length === 0) {
+                return 'No possible duplicates found.';
+            }
+            return duplicates
+                .map((item, index) => `${index + 1}. [${item.kind}] score=${item.score.toFixed(4)} ${item.left.path} <-> ${item.right.path} (${item.reason})`)
+                .join('\n');
+        });
+    });
+    program
+        .command('dedupe-resolve')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('--left <path>', 'left note relative path from dedupe result')
+        .option('--right <path>', 'right note relative path from dedupe result')
+        .option('--action <action>', 'resolution action: merge, link or ignore')
+        .option('--no-auto-index', 'skip reindex after duplicate resolution')
+        .option('--json', 'print machine-readable JSON')
+        .description('resolve a duplicate candidate with merge, link or ignore')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        if (!options.left || !options.right) {
+            throw new Error('Use --left <path> and --right <path> to resolve a duplicate pair.');
+        }
+        if (options.action !== 'merge' && options.action !== 'link' && options.action !== 'ignore') {
+            throw new Error('Use --action merge|link|ignore.');
+        }
+        const result = await resolveDuplicateNotes(resolved.vault, {
+            leftPath: options.left,
+            rightPath: options.right,
+            action: options.action,
+            autoIndex: options.autoIndex !== false
+        });
+        print(options.json, {
+            vault: resolved.vault,
+            ...result
+        }, () => `Resolved duplicate (${result.action}) for ${result.leftPath} <-> ${result.rightPath}`);
     });
     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')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-w, --watch', 'watch markdown changes and re-run benchmark in realtime')
+        .option('--debounce <ms>', 'watch debounce in milliseconds', '350')
+        .option('--json', 'print machine-readable JSON events')
+        .description('benchmark indexing in realtime, including compressed pack behavior')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const config = await loadBrainlinkConfig();
+        const emitProgress = (event) => {
+            printBenchRealtimeEvent(options.json, event);
+        };
+        const printBenchError = (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            print(options.json, { event: 'bench-error', message }, () => `[bench] error ${message}`);
+        };
+        const runAndPrint = async (trigger) => {
+            const baseline = await readBenchHistory(resolved.vault);
+            const result = await indexVaultWithOptions(resolved.vault, {
+                onProgress: emitProgress
+            });
+            printBenchSummary(options.json, trigger, resolved.vault, result);
+            const guardrails = evaluateBenchGuardrails(config, result, baseline);
+            printBenchGuardrails(options.json, resolved.vault, config, guardrails);
+            await writeBenchHistory(resolved.vault, result);
+            return result;
+        };
+        if (!options.watch) {
+            await runAndPrint('manual');
+            return;
+        }
+        const debounceMs = parsePositiveInteger(options.debounce ?? '350', 350);
+        await runAndPrint('manual');
+        print(options.json, {
+            event: 'bench-watching',
+            vault: resolved.vault,
+            debounceMs
+        }, () => `[bench] watching ${resolved.vault} (debounce=${debounceMs}ms)`);
+        const watcher = startVaultWatcher({
+            vaultPath: resolved.vault,
+            debounceMs,
+            onProgress: emitProgress,
+            onIndex: (result) => {
+                printBenchSummary(options.json, 'watch', resolved.vault, result);
+            },
+            onError: printBenchError
+        });
+        await new Promise((resolveSignal) => {
+            const shutdown = () => {
+                watcher.close();
+                resolveSignal();
+            };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+        });
     });
     program
         .command('doctor')
@@ -147,6 +1015,30 @@ export const registerWriteCommands = (program) => {
         });
         process.exitCode = report.ok ? 0 : 1;
     });
+    program
+        .command('pack-backup')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-o, --output <path>', 'output file path (.blpkbak.gz)')
+        .option('--json', 'print machine-readable JSON')
+        .description('create offline backup with second-stage compression for encrypted search packs')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const outputPath = options.output?.trim().length
+            ? resolve(options.output)
+            : join(resolved.vault, '.brainlink', 'backups', `search-packs-${new Date().toISOString().replace(/[:.]/g, '-')}.blpkbak.gz`);
+        const backup = await createOfflinePackBackup({
+            vaultPath: resolved.vault,
+            outputPath
+        });
+        print(options.json, {
+            vault: resolved.vault,
+            backup
+        }, () => [
+            `Offline backup created: ${backup.outputPath}`,
+            `files=${backup.fileCount}`,
+            `input=${formatBytes(backup.inputBytes)} output=${formatBytes(backup.outputBytes)} saved=${((1 - backup.ratio) * 100).toFixed(2)}%`
+        ].join('\n'));
+    });
     program
         .command('watch')
         .option('-v, --vault <vault>', 'vault directory')
@@ -181,19 +1073,37 @@ export const registerWriteCommands = (program) => {
         .option('-h, --host <host>', 'server host', '127.0.0.1')
         .option('-p, --port <port>', 'server port', '4321')
         .option('--no-index', 'skip indexing before starting the server')
-        .option('-w, --watch', 'watch markdown files and reindex on changes')
+        .option('--no-open', 'do not open the graph UI automatically')
+        .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
         });
-        print(options.json, { url: server.url, watch: Boolean(options.watch), readonly: true }, () => `Brainlink graph server running at ${server.url}`);
+        const openResult = options.open !== false ? openUrlInUi(server.url, process.pid) : { opened: false, mode: 'none' };
+        print(options.json, {
+            url: server.url,
+            watch: shouldWatch,
+            readonly: true,
+            openedUi: openResult.opened,
+            openMode: openResult.mode
+        }, () => `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'
+                    ? ' (opened in dedicated app window)'
+                    : ' (opened in browser)'
+            : options.open === false
+                ? ' (auto-open disabled)'
+                : ''}`);
     });
     program
         .command('quickstart')