@jafreck/lore 0.1.0 → 0.2.1

package/dist/indexer/index.d.ts

@@ -10,6 +10,17 @@
 import type { WalkerConfig } from './walker.js';
 import type { EmbeddingProvider } from './embedder.js';
 import { type CoverageFormat } from './coverage.js';
+import type { EffectiveLspSettings } from './lsp/config.js';
+interface IndexBuilderOptions {
+    history?: boolean | {
+        depth?: number;
+        all?: boolean;
+    };
+    embeddingModel?: string;
+    docsAutoNotes?: boolean;
+    indexDependencies?: boolean;
+    lsp?: EffectiveLspSettings;
+}
 /**
  * Orchestrates the full M1 indexing pipeline.
  *
@@ -26,14 +37,11 @@ export declare class IndexBuilder {
     private readonly resolver;
     private readonly embedder;
     private readonly history;
+    private readonly indexDependencies;
     private readonly embeddingModel;
-    constructor(dbPath: string, walkerConfig: WalkerConfig, embedder?: EmbeddingProvider, embeddingModelOrOptions?: string | {
-        history?: boolean | {
-            depth?: number;
-            all?: boolean;
-        };
-        embeddingModel?: string;
-    });
+    private readonly docsAutoNotes;
+    private readonly lspSettings;
+    constructor(dbPath: string, walkerConfig: WalkerConfig, embedder?: EmbeddingProvider, embeddingModelOrOptions?: string | IndexBuilderOptions);
     /**
      * Performs a full build: walks all files, parses them, extracts
      * symbols/imports/callRefs, resolves imports, and persists everything to
@@ -60,15 +68,30 @@ export declare class IndexBuilder {
     ingestCoverage(reportPath: string, format: CoverageFormat, commitSha?: string): Promise<void>;
     /** Parse one file, extract symbols/imports/callRefs, and insert into the DB. */
     private processFile;
+    private processDocumentationFile;
+    private upsertSeededDocumentationNote;
+    private removeStaleDocumentation;
+    private deleteDocumentationByPath;
+    private deleteDocumentationById;
+    private deleteDocSectionEmbeddings;
     /**
      * Second pass: resolve raw_import strings to file IDs in the
      * `file_imports.resolved_id` column.  Also populates `external_deps` for
      * any import that resolves to an external package.
      */
     private resolveImports;
+    private indexDependencyDeclarations;
+    private createLspEnrichmentCoordinator;
+    private enrichProjectSymbolsAndCallRefs;
     private resolveBranch;
     private saveLastKnownHead;
+    private saveDocsAutoNotesSetting;
     private readGitValue;
+    private loadDirectDependencies;
+    private readInstalledPackageVersion;
+    private collectDeclarationFiles;
+    private shouldIndexDependencySymbol;
+    private hasImplementationBody;
     private loadBuildCheckpoint;
     private saveBuildCheckpoint;
     /**
@@ -79,5 +102,7 @@ export declare class IndexBuilder {
      * creates the vec0 tables if they don't exist yet.
      */
     private embedStructural;
+    private embedDocumentation;
 }
+export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/indexer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/indexer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA+BhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAoD1E;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IACtE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAGtC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,YAAY,EAC1B,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,uBAAuB,CAAC,EAAE,MAAM,GAAG;QAAE,OAAO,CAAC,EAAE,OAAO,GAAG;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,OAAO,CAAA;SAAE,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE;IAyBvH;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiC5B;;;;;OAKG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAyDnD;;;;;;;;OAQG;IACG,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,SAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBlF,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBnG,gFAAgF;IAChF,OAAO,CAAC,WAAW;IAsHnB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAyCtB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,mBAAmB;IAW3B;;;;;;OAMG;YACW,eAAe;CA6B9B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/indexer/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AA4D5D,UAAU,mBAAmB;IAC3B,OAAO,CAAC,EAAE,OAAO,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,GAAG,CAAC,EAAE,oBAAoB,CAAC;CAC5B;AAID;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IACtE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;gBAGxD,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,YAAY,EAC1B,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,uBAAuB,CAAC,EAAE,MAAM,GAAG,mBAAmB;IA4BxD;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsD5B;;;;;OAKG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAyFnD;;;;;;;;OAQG;IACG,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,SAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBlF,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBnG,gFAAgF;IAChF,OAAO,CAAC,WAAW;IA8HnB,OAAO,CAAC,wBAAwB;IA6EhC,OAAO,CAAC,6BAA6B;IA8BrC,OAAO,CAAC,wBAAwB;IAShC,OAAO,CAAC,yBAAyB;IAQjC,OAAO,CAAC,uBAAuB;IAM/B,OAAO,CAAC,0BAA0B;IAWlC;;;;OAIG;IACH,OAAO,CAAC,cAAc;YAyCR,2BAA2B;IA8EzC,OAAO,CAAC,8BAA8B;YAOxB,+BAA+B;IA+G7C,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,wBAAwB;IAIhC,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,sBAAsB;IAoB9B,OAAO,CAAC,2BAA2B;IASnC,OAAO,CAAC,uBAAuB;IA2B/B,OAAO,CAAC,2BAA2B;IAMnC,OAAO,CAAC,qBAAqB;IAyB7B,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,mBAAmB;IAW3B;;;;;;OAMG;YACW,eAAe;YAiDf,kBAAkB;CAmCjC"}

package/dist/indexer/index.js

@@ -9,14 +9,18 @@
  */
 import * as fs from 'node:fs';
 import * as crypto from 'node:crypto';
+import * as path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { openDb, setKbMeta, getKbMeta, createVec0Tables, KB_META_INDEX_CHECKPOINT, KB_META_LAST_HEAD_SHA, KB_META_COVERAGE_LAST_SOURCE_PATH, KB_META_COVERAGE_LAST_SOURCE_MTIME, } from './db.js';
 import { walkFiles } from './walker.js';
 import { detectLanguageForPath } from './walker.js';
+import { walkDocumentationFiles } from './walker.js';
+import { inferSeededDocNoteKey, buildDocNoteScope } from './docs.js';
 import { ingestGitHistory } from './git-history.js';
 import { ParserPool } from './parser.js';
 import { ImportResolver } from './resolver.js';
 import { buildCallGraph } from './call-graph.js';
+import { isPublicDeclarationSurfaceSymbol, } from './extractors/types.js';
 import { CExtractor } from './extractors/c.js';
 import { RustExtractor } from './extractors/rust.js';
 import { PythonExtractor } from './extractors/python.js';
@@ -41,9 +45,10 @@ import { HaskellExtractor } from './extractors/haskell.js';
 import { JuliaExtractor } from './extractors/julia.js';
 import { ElmExtractor } from './extractors/elm.js';
 import { ObjcExtractor } from './extractors/objc.js';
-import { DEFAULT_EMBEDDING_MODEL } from './embedder.js';
+import { DEFAULT_EMBEDDING_MODEL, buildStructuralEmbeddingText } from './embedder.js';
 import { ingestCoverageReport } from './coverage.js';
 import { refreshTestMappings } from './test-mapper.js';
+import { LspEnrichmentCoordinator } from './lsp/enrichment.js';
 // ─── Extractor registry ───────────────────────────────────────────────────────
 const EXTRACTORS = {
     c: new CExtractor(),
@@ -90,7 +95,10 @@ export class IndexBuilder {
     resolver;
     embedder;
     history;
+    indexDependencies;
     embeddingModel;
+    docsAutoNotes;
+    lspSettings;
     constructor(dbPath, walkerConfig, embedder, embeddingModelOrOptions) {
         this.dbPath = dbPath;
         this.walkerConfig = walkerConfig;
@@ -108,6 +116,9 @@ export class IndexBuilder {
             this.embedder = null;
         }
         this.history = opts.history ?? false;
+        this.docsAutoNotes = opts.docsAutoNotes ?? true;
+        this.indexDependencies = opts.indexDependencies ?? false;
+        this.lspSettings = opts.lsp ?? null;
     }
     // ─── Public API ──────────────────────────────────────────────────────────
     /**
@@ -118,8 +129,17 @@ export class IndexBuilder {
     async build() {
         const db = openDb(this.dbPath);
         const branch = this.resolveBranch();
+        const lspCoordinator = this.createLspEnrichmentCoordinator();
         try {
+            this.saveDocsAutoNotesSetting(db);
             const files = await walkFiles(this.walkerConfig);
+            const docs = await walkDocumentationFiles(this.walkerConfig);
+            if (lspCoordinator) {
+                const languages = new Set(files.map((file) => file.language));
+                if (this.indexDependencies)
+                    languages.add('typescript');
+                await lspCoordinator.start(languages);
+            }
             const resumeAt = this.loadBuildCheckpoint(db, branch, files.length);
             db.transaction(() => {
                 for (let i = resumeAt; i < files.length; i++) {
@@ -129,15 +149,25 @@ export class IndexBuilder {
                     this.processFile(db, file.path, file.language, branch);
                     this.saveBuildCheckpoint(db, branch, i + 1, files.length);
                 }
+                const seenDocPaths = new Set();
+                for (const doc of docs) {
+                    seenDocPaths.add(doc.path);
+                    this.processDocumentationFile(db, doc, branch);
+                    this.upsertSeededDocumentationNote(db, doc, branch);
+                }
+                this.removeStaleDocumentation(db, branch, seenDocPaths);
             })();
             this.saveBuildCheckpoint(db, branch, files.length, files.length);
             this.resolveImports(db, branch);
+            await this.indexDependencyDeclarations(db, lspCoordinator);
+            await this.enrichProjectSymbolsAndCallRefs(db, branch, files, lspCoordinator);
             refreshTestMappings(db, branch);
             buildCallGraph(db);
             this.saveLastKnownHead(db);
             if (this.embedder) {
                 await this.embedder.init();
                 await this.embedStructural(db);
+                await this.embedDocumentation(db);
             }
             if (this.history) {
                 const historyOptions = typeof this.history === 'object' ? this.history : undefined;
@@ -145,6 +175,9 @@ export class IndexBuilder {
             }
         }
         finally {
+            if (lspCoordinator) {
+                await lspCoordinator.dispose();
+            }
             db.close();
         }
     }
@@ -157,7 +190,25 @@ export class IndexBuilder {
     async update(changedFiles) {
         const db = openDb(this.dbPath);
         const branch = this.resolveBranch();
+        const lspCoordinator = this.createLspEnrichmentCoordinator();
+        const enrichedFiles = [];
         try {
+            this.saveDocsAutoNotesSetting(db);
+            const docs = await walkDocumentationFiles(this.walkerConfig);
+            const docsByPath = new Map(docs.map(doc => [doc.path, doc]));
+            if (lspCoordinator) {
+                const languages = new Set();
+                for (const filePath of changedFiles) {
+                    if (!fs.existsSync(filePath))
+                        continue;
+                    const language = detectLanguageForPath(filePath, this.walkerConfig);
+                    if (language)
+                        languages.add(language);
+                }
+                if (this.indexDependencies)
+                    languages.add('typescript');
+                await lspCoordinator.start(languages);
+            }
             db.transaction(() => {
                 for (const filePath of changedFiles) {
                     // If the file no longer exists, remove it from the DB
@@ -169,23 +220,35 @@ export class IndexBuilder {
                             db.prepare('DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_id = ?)').run(row.id);
                             db.prepare('DELETE FROM files WHERE id = ?').run(row.id);
                         }
+                        this.deleteDocumentationByPath(db, filePath, branch);
                         continue;
                     }
                     const language = detectLanguageForPath(filePath, this.walkerConfig);
-                    if (!language)
-                        continue;
-                    // Null out resolved_id references pointing to this file before deletion
-                    const existingRow = db.prepare('SELECT id FROM files WHERE path = ? AND branch = ?').get(filePath, branch);
-                    if (existingRow) {
-                        db.prepare('UPDATE file_imports SET resolved_id = NULL WHERE resolved_id = ?').run(existingRow.id);
-                        db.prepare('DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_id = ?)').run(existingRow.id);
+                    if (language) {
+                        enrichedFiles.push({ path: filePath, language });
+                        // Null out resolved_id references pointing to this file before deletion
+                        const existingRow = db.prepare('SELECT id FROM files WHERE path = ? AND branch = ?').get(filePath, branch);
+                        if (existingRow) {
+                            db.prepare('UPDATE file_imports SET resolved_id = NULL WHERE resolved_id = ?').run(existingRow.id);
+                            db.prepare('DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file_id = ?)').run(existingRow.id);
+                        }
+                        // Delete existing rows for this file (cascade handles symbols/imports)
+                        db.prepare('DELETE FROM files WHERE path = ? AND branch = ?').run(filePath, branch);
+                        this.processFile(db, filePath, language, branch);
+                    }
+                    const changedDoc = docsByPath.get(filePath);
+                    if (changedDoc) {
+                        this.processDocumentationFile(db, changedDoc, branch);
+                        this.upsertSeededDocumentationNote(db, changedDoc, branch);
+                    }
+                    else {
+                        this.deleteDocumentationByPath(db, filePath, branch);
                     }
-                    // Delete existing rows for this file (cascade handles symbols/imports)
-                    db.prepare('DELETE FROM files WHERE path = ? AND branch = ?').run(filePath, branch);
-                    this.processFile(db, filePath, language, branch);
                 }
             })();
             this.resolveImports(db, branch);
+            await this.indexDependencyDeclarations(db, lspCoordinator);
+            await this.enrichProjectSymbolsAndCallRefs(db, branch, enrichedFiles, lspCoordinator);
             refreshTestMappings(db, branch);
             if (this.history) {
                 const historyOptions = typeof this.history === 'object' ? this.history : undefined;
@@ -194,11 +257,15 @@ export class IndexBuilder {
             if (this.embedder) {
                 await this.embedder.init();
                 await this.embedStructural(db);
+                await this.embedDocumentation(db);
             }
             buildCallGraph(db);
             this.saveLastKnownHead(db);
         }
         finally {
+            if (lspCoordinator) {
+                await lspCoordinator.dispose();
+            }
             db.close();
         }
     }
@@ -299,7 +366,10 @@ export class IndexBuilder {
             const info = insertSymbol.run(fileId, sym.name, sym.kind, sym.startLine, sym.endLine, sym.signature ?? null, sym.docComment ?? null);
             const symId = Number(info.lastInsertRowid);
             symbolIdMap.set(sym.name, symId);
-            insertFts.run(symId, sym.name, sym.signature ?? '', sym.kind);
+            insertFts.run(symId, sym.name, buildStructuralEmbeddingText({
+                name: sym.name,
+                signature: sym.signature ?? null,
+            }), sym.kind);
         }
         const insertRoute = db.prepare(`INSERT INTO api_routes (file_id, method, path, handler_id, handler_name, framework, line, middleware)
        VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
@@ -321,6 +391,95 @@ export class IndexBuilder {
             }
         }
     }
+    processDocumentationFile(db, doc, branch) {
+        const existing = db.prepare('SELECT id, content_hash FROM docs WHERE path = ? AND branch = ?').get(doc.path, branch);
+        if (existing?.content_hash === doc.hash) {
+            return;
+        }
+        let docId;
+        if (existing) {
+            db.prepare(`UPDATE docs
+         SET kind = ?, title = ?, content = ?, content_hash = ?, indexed_at = unixepoch()
+         WHERE id = ?`).run(doc.kind, doc.title, doc.content, doc.hash, existing.id);
+            docId = existing.id;
+        }
+        else {
+            const info = db.prepare(`INSERT INTO docs (path, branch, kind, title, content, content_hash)
+         VALUES (?, ?, ?, ?, ?, ?)`).run(doc.path, branch, doc.kind, doc.title, doc.content, doc.hash);
+            docId = Number(info.lastInsertRowid);
+        }
+        const existingSections = db.prepare('SELECT id, section_index FROM doc_sections WHERE doc_id = ?').all(docId);
+        const insertSection = db.prepare(`INSERT INTO doc_sections (
+         doc_id, section_index, title, depth, heading_path, line_start, line_end, content, content_hash
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(doc_id, section_index) DO UPDATE SET
+         title = excluded.title,
+         depth = excluded.depth,
+         heading_path = excluded.heading_path,
+         line_start = excluded.line_start,
+         line_end = excluded.line_end,
+         content = excluded.content,
+         content_hash = excluded.content_hash`);
+        const activeSectionIndexes = new Set();
+        for (const chunk of doc.chunks) {
+            activeSectionIndexes.add(chunk.sectionIndex);
+            insertSection.run(docId, chunk.sectionIndex, chunk.title, chunk.depth, JSON.stringify(chunk.headingPath), chunk.lineStart, chunk.lineEnd, chunk.content, chunk.hash);
+        }
+        const staleSectionIds = existingSections
+            .filter(section => !activeSectionIndexes.has(section.section_index))
+            .map(section => section.id);
+        this.deleteDocSectionEmbeddings(db, staleSectionIds);
+        if (staleSectionIds.length > 0) {
+            db.prepare(`DELETE FROM doc_sections
+         WHERE id IN (${staleSectionIds.map(() => '?').join(', ')})`).run(...staleSectionIds);
+        }
+    }
+    upsertSeededDocumentationNote(db, doc, branch) {
+        if (!this.docsAutoNotes)
+            return;
+        const key = inferSeededDocNoteKey(doc);
+        if (!key)
+            return;
+        const scope = buildDocNoteScope(doc.path, branch);
+        const existing = db.prepare('SELECT content, source_hash FROM notes WHERE key = ? AND scope = ?').get(key, scope);
+        if (existing?.content === doc.content && existing.source_hash === doc.hash) {
+            return;
+        }
+        db.prepare(`INSERT INTO notes (key, scope, content, model, source_hash, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, unixepoch(), unixepoch())
+       ON CONFLICT(key, scope) DO UPDATE SET
+         content = excluded.content,
+         model = excluded.model,
+         source_hash = excluded.source_hash,
+         updated_at = unixepoch()`).run(key, scope, doc.content, 'system:auto-doc-seed', doc.hash);
+    }
+    removeStaleDocumentation(db, branch, retainedPaths) {
+        const docs = db.prepare('SELECT id, path FROM docs WHERE branch = ?').all(branch);
+        for (const doc of docs) {
+            if (!retainedPaths.has(doc.path)) {
+                this.deleteDocumentationById(db, doc.id);
+            }
+        }
+    }
+    deleteDocumentationByPath(db, docPath, branch) {
+        const row = db.prepare('SELECT id FROM docs WHERE path = ? AND branch = ?').get(docPath, branch);
+        if (!row)
+            return;
+        this.deleteDocumentationById(db, row.id);
+    }
+    deleteDocumentationById(db, docId) {
+        const sectionIds = db.prepare('SELECT id FROM doc_sections WHERE doc_id = ?').all(docId);
+        this.deleteDocSectionEmbeddings(db, sectionIds.map(row => row.id));
+        db.prepare('DELETE FROM docs WHERE id = ?').run(docId);
+    }
+    deleteDocSectionEmbeddings(db, sectionIds) {
+        if (sectionIds.length === 0)
+            return;
+        const hasEmbeddingsTable = db.prepare("SELECT 1 AS present FROM sqlite_master WHERE type IN ('table', 'virtual table') AND name = 'doc_section_embeddings'").get();
+        if (!hasEmbeddingsTable)
+            return;
+        db.prepare(`DELETE FROM doc_section_embeddings WHERE rowid IN (${sectionIds.map(() => '?').join(', ')})`).run(...sectionIds);
+    }
     /**
      * Second pass: resolve raw_import strings to file IDs in the
      * `file_imports.resolved_id` column.  Also populates `external_deps` for
@@ -352,6 +511,146 @@ export class IndexBuilder {
             }
         }
     }
+    async indexDependencyDeclarations(db, lspCoordinator) {
+        db.prepare('DELETE FROM external_symbols').run();
+        if (!this.indexDependencies)
+            return;
+        const directDependencies = this.loadDirectDependencies();
+        if (directDependencies.size === 0)
+            return;
+        const extractor = EXTRACTORS.typescript;
+        if (!extractor)
+            return;
+        const insertExternalSymbol = db.prepare(`INSERT OR IGNORE INTO external_symbols
+         (
+           package_name,
+           package_version,
+           source_ref,
+           symbol_name,
+           symbol_kind,
+           signature,
+           doc_comment,
+           resolved_type_signature,
+           resolved_return_type,
+           definition_uri,
+           definition_path
+         )
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const [packageName, declaredVersion] of directDependencies) {
+            const packageDir = path.join(this.walkerConfig.rootDir, 'node_modules', packageName);
+            if (!fs.existsSync(packageDir) || !fs.statSync(packageDir).isDirectory())
+                continue;
+            const packageVersion = this.readInstalledPackageVersion(packageDir) ?? declaredVersion ?? null;
+            const declarationFiles = this.collectDeclarationFiles(packageDir);
+            for (const declarationFile of declarationFiles) {
+                const source = fs.readFileSync(declarationFile, 'utf8');
+                const tree = this.pool.parse('typescript', source);
+                if (!tree)
+                    continue;
+                const result = extractor.extract(tree, source, declarationFile);
+                const declarationSymbols = result.symbols.filter((symbol) => this.shouldIndexDependencySymbol(symbol));
+                const enrichmentRows = lspCoordinator
+                    ? await lspCoordinator.enrich({
+                        filePath: declarationFile,
+                        language: 'typescript',
+                        source,
+                        targets: declarationSymbols.map((symbol) => ({
+                            line: symbol.startLine,
+                            character: symbol.startCharacter ?? 0,
+                        })),
+                    })
+                    : declarationSymbols.map(() => null);
+                for (let i = 0; i < declarationSymbols.length; i++) {
+                    const symbol = declarationSymbols[i];
+                    if (!symbol)
+                        continue;
+                    const metadata = enrichmentRows[i];
+                    insertExternalSymbol.run(packageName, packageVersion, declarationFile, symbol.name, symbol.kind, symbol.signature, symbol.docComment ?? null, metadata?.resolvedTypeSignature ?? null, metadata?.resolvedReturnType ?? null, metadata?.definitionUri ?? null, metadata?.definitionPath ?? null);
+                }
+            }
+        }
+    }
+    createLspEnrichmentCoordinator() {
+        if (!this.lspSettings?.enabled) {
+            return null;
+        }
+        return new LspEnrichmentCoordinator(this.lspSettings, this.walkerConfig.rootDir);
+    }
+    async enrichProjectSymbolsAndCallRefs(db, branch, files, lspCoordinator) {
+        if (!lspCoordinator || files.length === 0)
+            return;
+        const selectSymbols = db.prepare(`SELECT s.id, s.name, s.signature, s.start_line
+       FROM symbols s
+       JOIN files f ON f.id = s.file_id
+       WHERE f.path = ? AND f.branch = ?
+       ORDER BY s.id`);
+        const selectCallRefs = db.prepare(`SELECT sr.id, sr.call_line
+       FROM symbol_refs sr
+       JOIN symbols s ON s.id = sr.caller_id
+       JOIN files f ON f.id = s.file_id
+       WHERE f.path = ? AND f.branch = ?
+       ORDER BY sr.id`);
+        const updateSymbol = db.prepare(`UPDATE symbols
+       SET resolved_type_signature = ?, resolved_return_type = ?, definition_uri = ?, definition_path = ?
+       WHERE id = ?`);
+        const updateSymbolFts = db.prepare('UPDATE symbols_fts SET signature = ? WHERE rowid = ?');
+        const updateCallRef = db.prepare(`UPDATE symbol_refs
+       SET resolved_type_signature = ?, resolved_return_type = ?, definition_uri = ?, definition_path = ?
+       WHERE id = ?`);
+        for (const file of files) {
+            if (!file || !fs.existsSync(file.path))
+                continue;
+            let source;
+            try {
+                source = fs.readFileSync(file.path, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const symbols = selectSymbols.all(file.path, branch);
+            if (symbols.length > 0) {
+                const symbolMetadata = await lspCoordinator.enrich({
+                    filePath: file.path,
+                    language: file.language,
+                    source,
+                    targets: symbols.map((symbol) => ({ line: symbol.start_line, character: 0 })),
+                });
+                for (let i = 0; i < symbols.length; i++) {
+                    const symbol = symbols[i];
+                    if (!symbol)
+                        continue;
+                    const metadata = symbolMetadata[i];
+                    if (!metadata)
+                        continue;
+                    updateSymbol.run(metadata.resolvedTypeSignature, metadata.resolvedReturnType, metadata.definitionUri, metadata.definitionPath, symbol.id);
+                    updateSymbolFts.run(buildStructuralEmbeddingText({
+                        name: symbol.name,
+                        signature: symbol.signature,
+                        resolvedTypeSignature: metadata.resolvedTypeSignature,
+                        resolvedReturnType: metadata.resolvedReturnType,
+                    }), symbol.id);
+                }
+            }
+            const callRefs = selectCallRefs.all(file.path, branch);
+            if (callRefs.length > 0) {
+                const callRefMetadata = await lspCoordinator.enrich({
+                    filePath: file.path,
+                    language: file.language,
+                    source,
+                    targets: callRefs.map((callRef) => ({ line: callRef.call_line, character: 0 })),
+                });
+                for (let i = 0; i < callRefs.length; i++) {
+                    const callRef = callRefs[i];
+                    if (!callRef)
+                        continue;
+                    const metadata = callRefMetadata[i];
+                    if (!metadata)
+                        continue;
+                    updateCallRef.run(metadata.resolvedTypeSignature, metadata.resolvedReturnType, metadata.definitionUri, metadata.definitionPath, callRef.id);
+                }
+            }
+        }
+    }
     resolveBranch() {
         if (this.walkerConfig.branch)
             return this.walkerConfig.branch;
@@ -363,6 +662,9 @@ export class IndexBuilder {
             setKbMeta(db, KB_META_LAST_HEAD_SHA, headSha);
         }
     }
+    saveDocsAutoNotesSetting(db) {
+        setKbMeta(db, 'docs_auto_notes', this.docsAutoNotes ? '1' : '0');
+    }
     readGitValue(args) {
         try {
             const value = execFileSync('git', ['-C', this.walkerConfig.rootDir, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
@@ -372,6 +674,80 @@ export class IndexBuilder {
             return undefined;
         }
     }
+    loadDirectDependencies() {
+        const packageJsonPath = path.join(this.walkerConfig.rootDir, 'package.json');
+        if (!fs.existsSync(packageJsonPath))
+            return new Map();
+        const raw = fs.readFileSync(packageJsonPath, 'utf8');
+        const pkg = JSON.parse(raw);
+        const deps = new Map();
+        for (const section of [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies]) {
+            if (!section)
+                continue;
+            for (const [name, version] of Object.entries(section)) {
+                if (!deps.has(name))
+                    deps.set(name, version);
+            }
+        }
+        return deps;
+    }
+    readInstalledPackageVersion(packageDir) {
+        const packageJsonPath = path.join(packageDir, 'package.json');
+        if (!fs.existsSync(packageJsonPath))
+            return undefined;
+        const raw = fs.readFileSync(packageJsonPath, 'utf8');
+        const pkg = JSON.parse(raw);
+        return pkg.version;
+    }
+    collectDeclarationFiles(packageDir) {
+        const declarations = [];
+        const stack = [packageDir];
+        while (stack.length > 0) {
+            const currentDir = stack.pop();
+            if (!currentDir)
+                continue;
+            const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.name === 'node_modules')
+                    continue;
+                const fullPath = path.join(currentDir, entry.name);
+                if (entry.isDirectory()) {
+                    stack.push(fullPath);
+                    continue;
+                }
+                if (entry.isFile() && fullPath.endsWith('.d.ts')) {
+                    declarations.push(fullPath);
+                }
+            }
+        }
+        return declarations;
+    }
+    shouldIndexDependencySymbol(symbol) {
+        if (!isPublicDeclarationSurfaceSymbol(symbol))
+            return false;
+        if (symbol.declarationSurface)
+            return true;
+        return !this.hasImplementationBody(symbol);
+    }
+    hasImplementationBody(symbol) {
+        const node = symbol.astNode;
+        if (!node)
+            return false;
+        if (node.type === 'arrow_function' ||
+            node.type === 'function_expression' ||
+            node.type === 'generator_function') {
+            return true;
+        }
+        if (node.type === 'class_declaration' ||
+            node.type === 'interface_declaration' ||
+            node.type === 'type_alias_declaration') {
+            return false;
+        }
+        const bodyNode = node.childForFieldName('body');
+        if (!bodyNode)
+            return false;
+        return bodyNode.namedChildCount > 0 || bodyNode.text.trim() !== '';
+    }
     loadBuildCheckpoint(db, branch, totalFiles) {
         const raw = getKbMeta(db, KB_META_INDEX_CHECKPOINT);
         if (!raw)
@@ -409,14 +785,23 @@ export class IndexBuilder {
         setKbMeta(db, 'embedding_model', embedder.modelName);
         setKbMeta(db, 'embedding_dims', String(embedder.dims));
         createVec0Tables(db, embedder.dims);
-        // Fetch all symbols that have a signature to embed.
+        // Fetch all symbols that have structural text to embed.
         const symbols = db
-            .prepare('SELECT id, name, signature FROM symbols WHERE signature IS NOT NULL')
+            .prepare(`SELECT id, name, signature, resolved_type_signature, resolved_return_type
+         FROM symbols
+         WHERE signature IS NOT NULL
+            OR resolved_type_signature IS NOT NULL
+            OR resolved_return_type IS NOT NULL`)
             .all();
         const insertEmbed = db.prepare('INSERT OR REPLACE INTO symbol_embeddings(rowid, embedding) VALUES (CAST(? AS INTEGER), json(?))');
         for (let i = 0; i < symbols.length; i += EMBED_BATCH_SIZE) {
             const batch = symbols.slice(i, i + EMBED_BATCH_SIZE);
-            const texts = batch.map(s => s.signature || s.name);
+            const texts = batch.map((symbol) => buildStructuralEmbeddingText({
+                name: symbol.name,
+                signature: symbol.signature,
+                resolvedTypeSignature: symbol.resolved_type_signature,
+                resolvedReturnType: symbol.resolved_return_type,
+            }));
             const embeddings = await embedder.embed(texts);
             db.transaction(() => {
                 for (let j = 0; j < batch.length; j++) {
@@ -427,5 +812,32 @@ export class IndexBuilder {
             })();
         }
     }
+    async embedDocumentation(db) {
+        const embedder = this.embedder;
+        db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS doc_section_embeddings USING vec0(
+        embedding FLOAT[${embedder.dims}]
+      );
+    `);
+        const sections = db.prepare(`SELECT id, title, content
+       FROM doc_sections
+       ORDER BY id`).all();
+        if (sections.length === 0)
+            return;
+        const insertEmbed = db.prepare('INSERT OR REPLACE INTO doc_section_embeddings(rowid, embedding) VALUES (CAST(? AS INTEGER), json(?))');
+        for (let i = 0; i < sections.length; i += EMBED_BATCH_SIZE) {
+            const batch = sections.slice(i, i + EMBED_BATCH_SIZE);
+            const texts = batch.map(section => section.content || section.title);
+            const embeddings = await embedder.embed(texts);
+            db.transaction(() => {
+                for (let j = 0; j < batch.length; j++) {
+                    const section = batch[j];
+                    if (section) {
+                        insertEmbed.run(section.id, JSON.stringify(embeddings[j]));
+                    }
+                }
+            })();
+        }
+    }
 }
 //# sourceMappingURL=index.js.map