@geminilight/mindos 0.6.31 → 0.6.33

package/app/components/renderers/workflow-yaml/WorkflowEditor.tsx

@@ -18,7 +18,6 @@ export default function WorkflowEditor({ workflow, filePath, onChange, onSaved }
   const [saving, setSaving] = useState(false);
   const [saveError, setSaveError] = useState('');
   const [saveSuccess, setSaveSuccess] = useState(false);
-  const [showAdvanced, setShowAdvanced] = useState(!!(workflow.workDir));
 
   useEffect(() => {
     if (!saveSuccess) return;
@@ -109,19 +108,10 @@ export default function WorkflowEditor({ workflow, filePath, onChange, onSaved }
           className="w-full text-sm bg-transparent text-muted-foreground placeholder:text-muted-foreground/30 focus:outline-none border-none p-0"
         />
 
-        {/* Advanced toggle */}
-        <div className="flex items-center gap-3">
-          {!showAdvanced ? (
-            <button onClick={() => setShowAdvanced(true)}
-              className="text-2xs text-muted-foreground/50 hover:text-muted-foreground transition-colors">
-              + Working directory
-            </button>
-          ) : (
-            <div className="flex items-center gap-2 flex-1">
-              <FolderOpen size={12} className="text-muted-foreground/40 shrink-0" />
-              <DirPicker value={workflow.workDir || ''} onChange={v => updateMeta({ workDir: v || undefined })} />
-            </div>
-          )}
+        {/* Working directory — always visible */}
+        <div className="flex items-center gap-2">
+          <FolderOpen size={12} className="text-muted-foreground/40 shrink-0" />
+          <DirPicker value={workflow.workDir || ''} onChange={v => updateMeta({ workDir: v || undefined })} />
         </div>
       </div>
 
@@ -130,16 +120,16 @@ export default function WorkflowEditor({ workflow, filePath, onChange, onSaved }
         <div className="relative">
           {/* Vertical timeline line */}
           {workflow.steps.length > 1 && (
-            <div className="absolute left-[15px] top-6 bottom-16 w-px bg-border" />
+            <div className="absolute left-[19px] top-6 bottom-16 w-px bg-border" />
           )}
 
           {/* Step list */}
           <div className="flex flex-col gap-3 mb-5 relative">
             {workflow.steps.map((step, i) => (
-              <div key={step.id} className="relative pl-9">
+              <div key={step.id} className="relative pl-11">
                 {/* Timeline node */}
-                <div className="absolute left-[9px] top-3 w-[13px] h-[13px] rounded-full border-2 border-border bg-background z-10 flex items-center justify-center">
-                  <span className="text-[7px] font-bold text-muted-foreground/60">{i + 1}</span>
+                <div className="absolute left-[7px] top-3 w-[22px] h-[22px] rounded-full border-2 border-border bg-background z-10 flex items-center justify-center">
+                  <span className="text-[10px] font-bold text-muted-foreground/60">{i + 1}</span>
                 </div>
                 <StepEditor
                   step={step}
@@ -154,9 +144,9 @@ export default function WorkflowEditor({ workflow, filePath, onChange, onSaved }
           </div>
 
           {/* Add step — at the end of timeline */}
-          <div className="relative pl-9">
-            <div className="absolute left-[9px] top-2.5 w-[13px] h-[13px] rounded-full border-2 border-dashed border-border bg-background z-10 flex items-center justify-center">
-              <Plus size={7} className="text-muted-foreground/40" />
+          <div className="relative pl-11">
+            <div className="absolute left-[7px] top-2.5 w-[22px] h-[22px] rounded-full border-2 border-dashed border-border bg-background z-10 flex items-center justify-center">
+              <Plus size={9} className="text-muted-foreground/40" />
             </div>
             <button onClick={addStep}
               className="w-full text-left px-3 py-2 rounded-lg text-xs text-muted-foreground/60 hover:text-muted-foreground hover:bg-muted/40 transition-colors">

package/app/components/renderers/workflow-yaml/WorkflowRunner.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useState, useRef, useCallback, useEffect } from 'react';
-import { Play, SkipForward, RotateCcw, CheckCircle2, Circle, Loader2, AlertCircle, ChevronDown, Sparkles, XCircle, Clock, ArrowRight } from 'lucide-react';
+import { Play, SkipForward, RotateCcw, CheckCircle2, Circle, Loader2, AlertCircle, ChevronDown, Sparkles, XCircle, Clock, ArrowRight, FolderOpen } from 'lucide-react';
 import { runStepWithAI, clearSkillCache } from './execution';
 import type { WorkflowYaml, WorkflowStepRuntime, StepStatus } from './types';
 
@@ -44,7 +44,7 @@ function TimelineNode({ status, index }: { status: StepStatus; index: number })
   // pending
   return (
     <div className={`${base} border-2 border-border bg-background`}>
-      <span className="text-[9px] font-bold text-muted-foreground/40">{index + 1}</span>
+      <span className="text-[11px] font-bold text-muted-foreground/50">{index + 1}</span>
     </div>
   );
 }
@@ -205,6 +205,19 @@ export default function WorkflowRunner({ workflow, filePath }: { workflow: Workf
 
   return (
     <div>
+      {/* Working directory + description */}
+      {(workflow.workDir || workflow.description) && (
+        <div className="flex items-center gap-3 mb-4 text-xs text-muted-foreground flex-wrap">
+          {workflow.workDir && (
+            <span className="flex items-center gap-1.5 font-mono text-2xs bg-muted/50 px-2 py-0.5 rounded">
+              <FolderOpen size={10} className="shrink-0" />
+              {workflow.workDir}
+            </span>
+          )}
+          {workflow.description && <span className="leading-relaxed">{workflow.description}</span>}
+        </div>
+      )}
+
       {/* Progress bar — full width, thin, elegant */}
       <div className="mb-6">
         <div className="flex items-center justify-between mb-2">

package/app/components/renderers/workflow-yaml/selectors.tsx

@@ -85,7 +85,7 @@ export function AgentSelector({ value, onChange }: { value?: string; onChange: (
         <button type="button" onClick={() => setOpen(v => !v)}
           className="w-full flex items-center justify-between px-2.5 py-1.5 text-xs rounded-md border border-border bg-background text-foreground hover:bg-muted transition-colors">
           <span className={value ? 'text-foreground truncate' : 'text-muted-foreground'}>
-            {displayName || 'Select agent'}
+            {displayName || 'MindOS'}
           </span>
           <ChevronDown size={12} className="text-muted-foreground shrink-0" />
         </button>
@@ -103,8 +103,8 @@ export function AgentSelector({ value, onChange }: { value?: string; onChange: (
       </div>
 
       <button onClick={() => select(undefined)}
-        className={`w-full text-left px-3 py-1.5 text-xs hover:bg-muted transition-colors ${!value ? 'text-[var(--amber)] font-medium' : 'text-muted-foreground'}`}>
-        (none — use default)
+        className={`w-full text-left px-3 py-1.5 text-xs hover:bg-muted transition-colors ${!value ? 'text-[var(--amber)] font-medium' : 'text-foreground'}`}>
+        MindOS <span className="text-muted-foreground/50 ml-1">(default)</span>
       </button>
       {filtered.slice(0, 30).map(a => (
         <button key={a.id} onClick={() => select(a.id)}

package/app/components/ui/Toaster.tsx

@@ -24,11 +24,20 @@ export default function Toaster() {
         >
           {icons[t.type]}
           <span className="text-sm text-foreground flex-1 truncate">{t.message}</span>
+          {t.action && (
+            <button
+              type="button"
+              onClick={() => { t.action!.onClick(); dismiss(t.id); }}
+              className="shrink-0 px-2.5 py-1 rounded text-xs font-medium text-[var(--amber)] hover:bg-[var(--amber-dim)] transition-colors min-h-[28px] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+            >
+              {t.action.label}
+            </button>
+          )}
           <button
             type="button"
             onClick={() => dismiss(t.id)}
-            className="shrink-0 p-0.5 rounded text-muted-foreground hover:text-foreground transition-colors"
-            aria-label="Dismiss"
+            className="shrink-0 p-0.5 rounded text-muted-foreground hover:text-foreground transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+            aria-label={t.action?.label ? 'Close' : 'Dismiss'}
           >
             <X size={13} />
           </button>

package/app/lib/actions.ts

@@ -24,12 +24,12 @@ export async function createFileAction(dirPath: string, fileName: string): Promi
   }
 }
 
-export async function deleteFileAction(filePath: string): Promise<{ success: boolean; error?: string }> {
+export async function deleteFileAction(filePath: string): Promise<{ success: boolean; trashId?: string; error?: string }> {
   try {
-    moveToTrash(getMindRoot(), filePath);
+    const meta = moveToTrash(getMindRoot(), filePath);
     invalidateCache();
     revalidatePath('/', 'layout');
-    return { success: true };
+    return { success: true, trashId: meta.id };
   } catch (err) {
     return { success: false, error: err instanceof Error ? err.message : 'Failed to delete file' };
   }
@@ -59,12 +59,12 @@ export async function convertToSpaceAction(
 
 export async function deleteFolderAction(
   dirPath: string,
-): Promise<{ success: boolean; error?: string }> {
+): Promise<{ success: boolean; trashId?: string; error?: string }> {
   try {
-    moveToTrash(getMindRoot(), dirPath);
+    const meta = moveToTrash(getMindRoot(), dirPath);
     invalidateCache();
     revalidatePath('/', 'layout');
-    return { success: true };
+    return { success: true, trashId: meta.id };
   } catch (err) {
     return { success: false, error: err instanceof Error ? err.message : 'Failed to delete folder' };
   }
@@ -85,17 +85,28 @@ export async function renameSpaceAction(
 
 export async function deleteSpaceAction(
   spacePath: string,
-): Promise<{ success: boolean; error?: string }> {
+): Promise<{ success: boolean; trashId?: string; error?: string }> {
   try {
-    moveToTrash(getMindRoot(), spacePath);
+    const meta = moveToTrash(getMindRoot(), spacePath);
     invalidateCache();
     revalidatePath('/', 'layout');
-    return { success: true };
+    return { success: true, trashId: meta.id };
   } catch (err) {
     return { success: false, error: err instanceof Error ? err.message : 'Failed to delete space' };
   }
 }
 
+export async function undoDeleteAction(trashId: string): Promise<{ success: boolean; error?: string }> {
+  try {
+    restoreFromTrash(getMindRoot(), trashId, false);
+    invalidateCache();
+    revalidatePath('/', 'layout');
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : 'Undo failed' };
+  }
+}
+
 /**
  * Create a new Mind Space (top-level directory) with README.md + auto-scaffolded INSTRUCTION.md.
  * The description is written into README.md so it appears on the homepage Space card

package/app/lib/agent/context.ts

@@ -9,21 +9,37 @@ import type { AgentMessage } from '@mariozechner/pi-agent-core';
 import type { ToolResultMessage, AssistantMessage, UserMessage } from '@mariozechner/pi-ai';
 
 // ---------------------------------------------------------------------------
-// Token estimation (1 token ≈ 4 chars)
+// Token estimation — CJK-aware (CJK ~1.5 tokens/char, ASCII ~0.25 tokens/char)
 // ---------------------------------------------------------------------------
 
+/** CJK character ranges: Han, Hiragana, Katakana, Hangul */
+const CJK_RANGE = /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/g;
+
+/**
+ * Estimate token count for a string using character-class heuristics.
+ * - CJK characters: ~1.5 tokens per character (measured against cl100k_base)
+ * - ASCII/Latin: ~0.25 tokens per character (1 token ≈ 4 chars)
+ * This is 3-4x more accurate than naive length/4 for mixed CJK/English text.
+ */
+export function estimateStringTokens(text: string): number {
+  const cjkMatches = text.match(CJK_RANGE);
+  const cjkCount = cjkMatches ? cjkMatches.length : 0;
+  const nonCjkCount = text.length - cjkCount;
+  return Math.ceil(cjkCount * 1.5 + nonCjkCount / 4);
+}
+
 /** Rough token count for a single AgentMessage */
 function messageTokens(msg: AgentMessage): number {
   if ('content' in msg) {
     const content = (msg as any).content;
-    if (typeof content === 'string') return Math.ceil(content.length / 4);
+    if (typeof content === 'string') return estimateStringTokens(content);
     if (Array.isArray(content)) {
-      let chars = 0;
+      let tokens = 0;
       for (const part of content) {
-        if ('text' in part && typeof part.text === 'string') chars += part.text.length;
-        if ('args' in part) chars += JSON.stringify(part.args).length;
+        if ('text' in part && typeof part.text === 'string') tokens += estimateStringTokens(part.text);
+        if ('args' in part) tokens += estimateStringTokens(JSON.stringify(part.args));
       }
-      return Math.ceil(chars / 4);
+      return tokens;
     }
   }
   return 0;
@@ -36,11 +52,6 @@ export function estimateTokens(messages: AgentMessage[]): number {
   return total;
 }
 
-/** Estimate tokens for a plain string (e.g. system prompt) */
-export function estimateStringTokens(text: string): number {
-  return Math.ceil(text.length / 4);
-}
-
 // ---------------------------------------------------------------------------
 // Context limits by model family
 // ---------------------------------------------------------------------------

package/app/lib/agent/loop-detection.ts

@@ -0,0 +1,52 @@
+/**
+ * Detect loops in agent tool call history.
+ *
+ * Two strategies:
+ * 1. Identical repetition: same tool+args N times in a row
+ * 2. Pattern cycle: tool sequence repeats (A→B→A→B, A→B→C→A→B→C)
+ */
+
+export interface StepEntry {
+  tool: string;
+  input: string;
+}
+
+/**
+ * Check if the step history contains a repeating loop.
+ * Returns true if a loop is detected.
+ */
+export function detectLoop(history: StepEntry[], threshold = 3): boolean {
+  if (history.length < threshold) return false;
+
+  // Check 1: identical tool+args repeated `threshold` times
+  const lastN = history.slice(-threshold);
+  if (lastN.every(s => s.tool === lastN[0].tool && s.input === lastN[0].input)) {
+    return true;
+  }
+
+  // Check 2: pattern cycle detection (e.g. A→B→A→B or A→B→C→A→B→C)
+  // Compares tool name only (not args) to catch cycles where the same
+  // tools are called in the same order but with slightly varied args.
+  // To reduce false positives, we require the cycle to repeat at least
+  // twice AND at least one pair in the cycle must share identical args.
+  if (history.length >= 4) {
+    const window = history.slice(-8);
+    for (let cycleLen = 2; cycleLen <= 4 && cycleLen * 2 <= window.length; cycleLen++) {
+      const tail = window.slice(-cycleLen * 2);
+      let toolsMatch = true;
+      let anyArgsMatch = false;
+      for (let i = 0; i < cycleLen; i++) {
+        if (tail[i].tool !== tail[i + cycleLen].tool) {
+          toolsMatch = false;
+          break;
+        }
+        if (tail[i].input === tail[i + cycleLen].input) {
+          anyArgsMatch = true;
+        }
+      }
+      if (toolsMatch && anyArgsMatch) return true;
+    }
+  }
+
+  return false;
+}

package/app/lib/agent/retry.ts

@@ -0,0 +1,19 @@
+/**
+ * Detect transient errors that are safe to retry: timeouts, rate limits (429),
+ * and server errors (5xx). Auth errors (401/403), bad requests (400), and
+ * content policy violations should NOT be retried.
+ */
+export function isTransientError(err: Error): boolean {
+  const msg = err.message.toLowerCase();
+  // Timeout patterns
+  if (msg.includes('timeout') || msg.includes('timed out') || msg.includes('etimedout')) return true;
+  // Rate limiting
+  if (msg.includes('429') || msg.includes('rate limit') || msg.includes('too many requests')) return true;
+  // Server errors (5xx)
+  if (/\b5\d{2}\b/.test(msg) || msg.includes('internal server error') || msg.includes('service unavailable')) return true;
+  // Connection errors
+  if (msg.includes('econnreset') || msg.includes('econnrefused') || msg.includes('socket hang up')) return true;
+  // Overloaded
+  if (msg.includes('overloaded') || msg.includes('capacity')) return true;
+  return false;
+}

package/app/lib/core/backlinks.ts

@@ -6,9 +6,24 @@ import type { BacklinkEntry } from './types';
 /**
  * Finds files that reference the given targetPath via wikilinks,
  * markdown links, or backtick references.
+ *
+ * Uses the pre-built LinkIndex for O(1) source lookup, then scans
+ * only the matching files for line-level context. This reduces the
+ * scanning cost from O(all-files * lines * patterns) to
+ * O(linking-files * lines * patterns).
+ *
+ * @param mindRoot  - absolute path to MIND_ROOT
+ * @param targetPath - relative file path to find backlinks for
+ * @param linkingSources - optional pre-computed list of files that link to targetPath
+ *                         (from LinkIndex.getBacklinks). If omitted, falls back to full scan.
+ * @param cachedFiles - optional full file list (legacy, used when linkingSources not available)
  */
-export function findBacklinks(mindRoot: string, targetPath: string, cachedFiles?: string[]): BacklinkEntry[] {
-  const allFiles = (cachedFiles ?? collectAllFiles(mindRoot)).filter(f => f.endsWith('.md') && f !== targetPath);
+export function findBacklinks(
+  mindRoot: string,
+  targetPath: string,
+  linkingSources?: string[],
+  cachedFiles?: string[],
+): BacklinkEntry[] {
   const results: BacklinkEntry[] = [];
   const bname = path.basename(targetPath, '.md');
   const escapedTarget = targetPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -22,25 +37,34 @@ export function findBacklinks(mindRoot: string, targetPath: string, cachedFiles?
     new RegExp('`' + escapedTarget.replace(/\//g, '\\/') + '`'),
   ];
 
-  for (const filePath of allFiles) {
+  // Use linkingSources from LinkIndex (O(1) lookup) when available,
+  // otherwise fall back to scanning all .md files
+  let filesToScan: string[];
+  if (linkingSources) {
+    filesToScan = linkingSources;
+  } else if (cachedFiles) {
+    filesToScan = cachedFiles.filter(f => f.endsWith('.md') && f !== targetPath);
+  } else {
+    filesToScan = collectAllFiles(mindRoot).filter(f => f.endsWith('.md') && f !== targetPath);
+  }
+
+  for (const filePath of filesToScan) {
+    if (filePath === targetPath) continue;
     let content: string;
     try { content = readFile(mindRoot, filePath); } catch { continue; }
     const lines = content.split('\n');
     for (let i = 0; i < lines.length; i++) {
       if (patterns.some(p => p.test(lines[i]))) {
-        // Expand to a slightly larger context block for agent comprehension
-        // Attempt to find paragraph boundaries (empty lines) or cap at a reasonable size
         let start = i;
         while (start > 0 && start > i - 3 && lines[start].trim() !== '') start--;
         let end = i;
         while (end < lines.length - 1 && end < i + 3 && lines[end].trim() !== '') end++;
-        
+
         let ctx = lines.slice(start, end + 1).join('\n').trim();
-        // Collapse multiple newlines in the context to save tokens, but keep simple structure
         ctx = ctx.replace(/\n{2,}/g, ' ↵ ');
-        
+
         results.push({ source: filePath, line: i + 1, context: ctx });
-        break; // currently only records the first match per file
+        break;
       }
     }
   }

package/app/lib/core/index.ts

@@ -39,7 +39,10 @@ export {
 export type { TreeOptions } from './tree';
 
 // Search
-export { searchFiles, invalidateSearchIndex } from './search';
+export { searchFiles, invalidateSearchIndex, updateSearchIndexFile, addSearchIndexFile, removeSearchIndexFile } from './search';
+
+// Link index (graph + backlinks)
+export { LinkIndex } from './link-index';
 
 // Line-level operations
 export {

package/app/lib/core/link-index.ts

@@ -0,0 +1,224 @@
+import path from 'path';
+import { collectAllFiles } from './tree';
+import { readFile } from './fs-ops';
+
+/**
+ * In-memory bidirectional link index for the knowledge graph.
+ *
+ * Maintains forward links (source → targets) and backward links (target → sources)
+ * in a single pass. Used by:
+ * - GET /api/graph — forward links for edge rendering
+ * - findBacklinks() — backward links for reference discovery
+ *
+ * Lifecycle:
+ * - `rebuild(mindRoot)` — full build from disk (called lazily on first access)
+ * - `updateFile(mindRoot, filePath)` — incremental re-index after write
+ * - `addFile(mindRoot, filePath)` — incremental add after create
+ * - `removeFile(filePath)` — incremental remove after delete
+ * - `invalidate()` — mark stale (next access triggers rebuild)
+ */
+export class LinkIndex {
+  private forwardLinks = new Map<string, Set<string>>();  // source → targets
+  private backwardLinks = new Map<string, Set<string>>(); // target → sources
+  private builtForRoot: string | null = null;
+  /** Cached file set and basename map for incremental link resolution. */
+  private fileSet = new Set<string>();
+  private basenameMap = new Map<string, string[]>();
+
+  /** Full rebuild: read all .md files and extract links. */
+  rebuild(mindRoot: string): void {
+    const allFiles = collectAllFiles(mindRoot).filter(f => f.endsWith('.md'));
+    const fileSet = new Set(allFiles);
+    const basenameMap = buildBasenameMap(allFiles);
+
+    const forward = new Map<string, Set<string>>();
+    const backward = new Map<string, Set<string>>();
+
+    for (const filePath of allFiles) {
+      let content: string;
+      try { content = readFile(mindRoot, filePath); } catch { continue; }
+
+      const targets = extractLinks(content, filePath, fileSet, basenameMap);
+      const targetSet = new Set<string>();
+      for (const t of targets) {
+        if (t !== filePath) targetSet.add(t); // skip self-links
+      }
+      forward.set(filePath, targetSet);
+
+      for (const t of targetSet) {
+        let sources = backward.get(t);
+        if (!sources) { sources = new Set(); backward.set(t, sources); }
+        sources.add(filePath);
+      }
+    }
+
+    this.forwardLinks = forward;
+    this.backwardLinks = backward;
+    this.builtForRoot = mindRoot;
+    this.fileSet = fileSet;
+    this.basenameMap = basenameMap;
+  }
+
+  /** Clear the index. Next access triggers lazy rebuild. */
+  invalidate(): void {
+    this.forwardLinks.clear();
+    this.backwardLinks.clear();
+    this.builtForRoot = null;
+    this.fileSet.clear();
+    this.basenameMap.clear();
+  }
+
+  isBuiltFor(mindRoot: string): boolean {
+    return this.builtForRoot === mindRoot;
+  }
+
+  isBuilt(): boolean {
+    return this.builtForRoot !== null;
+  }
+
+  // ── Queries ────────────────────────────────────────────────────────
+
+  /** Get all files that `sourcePath` links to. O(1). */
+  getForwardLinks(sourcePath: string): string[] {
+    return [...(this.forwardLinks.get(sourcePath) ?? [])];
+  }
+
+  /** Get all files that link to `targetPath`. O(1). */
+  getBacklinks(targetPath: string): string[] {
+    return [...(this.backwardLinks.get(targetPath) ?? [])];
+  }
+
+  /** Get all edges as [source, target] pairs. Used by Graph API. */
+  getAllEdges(): Array<{ source: string; target: string }> {
+    const edges: Array<{ source: string; target: string }> = [];
+    for (const [source, targets] of this.forwardLinks) {
+      for (const target of targets) {
+        edges.push({ source, target });
+      }
+    }
+    return edges;
+  }
+
+  // ── Incremental updates ──────────────────────────────────────────
+
+  /** Remove a file's links from the index. */
+  removeFile(filePath: string): void {
+    // Remove forward links and corresponding backward entries
+    const oldTargets = this.forwardLinks.get(filePath);
+    if (oldTargets) {
+      for (const t of oldTargets) {
+        this.backwardLinks.get(t)?.delete(filePath);
+      }
+      this.forwardLinks.delete(filePath);
+    }
+
+    // Also remove as a target in backward links (file deleted)
+    const oldSources = this.backwardLinks.get(filePath);
+    if (oldSources) {
+      for (const s of oldSources) {
+        this.forwardLinks.get(s)?.delete(filePath);
+      }
+      this.backwardLinks.delete(filePath);
+    }
+
+    // Remove from cached resolution sets
+    this.fileSet.delete(filePath);
+    const key = path.basename(filePath).toLowerCase();
+    const candidates = this.basenameMap.get(key);
+    if (candidates) {
+      const idx = candidates.indexOf(filePath);
+      if (idx >= 0) candidates.splice(idx, 1);
+      if (candidates.length === 0) this.basenameMap.delete(key);
+    }
+  }
+
+  /** Add or re-index a single file. */
+  updateFile(mindRoot: string, filePath: string): void {
+    if (!this.builtForRoot) return;
+    if (!filePath.endsWith('.md')) return;
+
+    // Remove old links
+    const oldTargets = this.forwardLinks.get(filePath);
+    if (oldTargets) {
+      for (const t of oldTargets) {
+        this.backwardLinks.get(t)?.delete(filePath);
+      }
+    }
+
+    // Re-extract links using cached fileSet/basenameMap
+    let content: string;
+    try { content = readFile(mindRoot, filePath); } catch { return; }
+
+    // Ensure this file is in the resolution sets
+    if (!this.fileSet.has(filePath)) {
+      this.fileSet.add(filePath);
+      const key = path.basename(filePath).toLowerCase();
+      if (!this.basenameMap.has(key)) this.basenameMap.set(key, []);
+      this.basenameMap.get(key)!.push(filePath);
+    }
+
+    const targets = extractLinks(content, filePath, this.fileSet, this.basenameMap);
+    const targetSet = new Set<string>();
+    for (const t of targets) {
+      if (t !== filePath) targetSet.add(t);
+    }
+    this.forwardLinks.set(filePath, targetSet);
+
+    for (const t of targetSet) {
+      let sources = this.backwardLinks.get(t);
+      if (!sources) { sources = new Set(); this.backwardLinks.set(t, sources); }
+      sources.add(filePath);
+    }
+  }
+}
+
+// ── Link extraction (shared between graph + backlinks) ─────────────
+
+function buildBasenameMap(allFiles: string[]): Map<string, string[]> {
+  const map = new Map<string, string[]>();
+  for (const f of allFiles) {
+    const key = path.basename(f).toLowerCase();
+    if (!map.has(key)) map.set(key, []);
+    map.get(key)!.push(f);
+  }
+  return map;
+}
+
+/**
+ * Extract wiki-links and markdown-links from file content.
+ * Returns an array of resolved target file paths.
+ */
+export function extractLinks(
+  content: string,
+  sourcePath: string,
+  fileSet: Set<string>,
+  basenameMap: Map<string, string[]>,
+): string[] {
+  const targets: string[] = [];
+  const sourceDir = path.dirname(sourcePath);
+
+  // WikiLinks: [[target]] or [[target|alias]] or [[target#section]]
+  const wikiRe = /\[\[([^\]|#]+)(?:[|#][^\]]*)?/g;
+  let m: RegExpExecArray | null;
+  while ((m = wikiRe.exec(content)) !== null) {
+    const raw = m[1].trim();
+    if (!raw) continue;
+    if (fileSet.has(raw)) { targets.push(raw); continue; }
+    const withMd = raw.endsWith('.md') ? raw : raw + '.md';
+    if (fileSet.has(withMd)) { targets.push(withMd); continue; }
+    const lower = path.basename(withMd).toLowerCase();
+    const candidates = basenameMap.get(lower);
+    if (candidates && candidates.length === 1) targets.push(candidates[0]);
+  }
+
+  // Markdown links: [text](relative/path.md)
+  const mdLinkRe = /\[[^\]]+\]\(([^)]+\.md)(?:#[^)]*)?\)/g;
+  while ((m = mdLinkRe.exec(content)) !== null) {
+    const raw = m[1].trim();
+    if (!raw || raw.startsWith('http')) continue;
+    const resolved = path.normalize(path.join(sourceDir, raw));
+    if (fileSet.has(resolved)) targets.push(resolved);
+  }
+
+  return targets;
+}