@tobilu/qmd 1.1.6 → 2.0.1

package/dist/embedded-skills.js

@@ -0,0 +1,14 @@
+// Generated from skills/qmd source files. Keep this in sync when updating the packaged skill.
+const EMBEDDED_QMD_SKILL_BASE64 = {
+    "SKILL.md": "LS0tCm5hbWU6IHFtZApkZXNjcmlwdGlvbjogU2VhcmNoIG1hcmtkb3duIGtub3dsZWRnZSBiYXNlcywgbm90ZXMsIGFuZCBkb2N1bWVudGF0aW9uIHVzaW5nIFFNRC4gVXNlIHdoZW4gdXNlcnMgYXNrIHRvIHNlYXJjaCBub3RlcywgZmluZCBkb2N1bWVudHMsIG9yIGxvb2sgdXAgaW5mb3JtYXRpb24uCmxpY2Vuc2U6IE1JVApjb21wYXRpYmlsaXR5OiBSZXF1aXJlcyBxbWQgQ0xJIG9yIE1DUCBzZXJ2ZXIuIEluc3RhbGwgdmlhIGBucG0gaW5zdGFsbCAtZyBAdG9iaWx1L3FtZGAuCm1ldGFkYXRhOgogIGF1dGhvcjogdG9iaQogIHZlcnNpb246ICIyLjAuMCIKYWxsb3dlZC10b29sczogQmFzaChxbWQ6KiksIG1jcF9fcW1kX18qCi0tLQoKIyBRTUQgLSBRdWljayBNYXJrZG93biBTZWFyY2gKCkxvY2FsIHNlYXJjaCBlbmdpbmUgZm9yIG1hcmtkb3duIGNvbnRlbnQuCgojIyBTdGF0dXMKCiFgcW1kIHN0YXR1cyAyPi9kZXYvbnVsbCB8fCBlY2hvICJOb3QgaW5zdGFsbGVkOiBucG0gaW5zdGFsbCAtZyBAdG9iaWx1L3FtZCJgCgojIyBNQ1A6IGBxdWVyeWAKCmBgYGpzb24KewogICJzZWFyY2hlcyI6IFsKICAgIHsgInR5cGUiOiAibGV4IiwgInF1ZXJ5IjogIkNBUCB0aGVvcmVtIGNvbnNpc3RlbmN5IiB9LAogICAgeyAidHlwZSI6ICJ2ZWMiLCAicXVlcnkiOiAidHJhZGVvZmYgYmV0d2VlbiBjb25zaXN0ZW5jeSBhbmQgYXZhaWxhYmlsaXR5IiB9CiAgXSwKICAiY29sbGVjdGlvbnMiOiBbImRvY3MiXSwKICAibGltaXQiOiAxMAp9CmBgYAoKIyMjIFF1ZXJ5IFR5cGVzCgp8IFR5cGUgfCBNZXRob2QgfCBJbnB1dCB8CnwtLS0tLS18LS0tLS0tLS18LS0tLS0tLXwKfCBgbGV4YCB8IEJNMjUgfCBLZXl3b3JkcyDigJQgZXhhY3QgdGVybXMsIG5hbWVzLCBjb2RlIHwKfCBgdmVjYCB8IFZlY3RvciB8IFF1ZXN0aW9uIOKAlCBuYXR1cmFsIGxhbmd1YWdlIHwKfCBgaHlkZWAgfCBWZWN0b3IgfCBBbnN3ZXIg4oCUIGh5cG90aGV0aWNhbCByZXN1bHQgKDUwLTEwMCB3b3JkcykgfAoKIyMjIFdyaXRpbmcgR29vZCBRdWVyaWVzCgoqKmxleCAoa2V5d29yZCkqKgotIDItNSB0ZXJtcywgbm8gZmlsbGVyIHdvcmRzCi0gRXhhY3QgcGhyYXNlOiBgImNvbm5lY3Rpb24gcG9vbCJgIChxdW90ZWQpCi0gRXhjbHVkZSB0ZXJtczogYHBlcmZvcm1hbmNlIC1zcG9ydHNgIChtaW51cyBwcmVmaXgpCi0gQ29kZSBpZGVudGlmaWVycyB3b3JrOiBgaGFuZGxlRXJyb3IgYXN5bmNgCgoqKnZlYyAoc2VtYW50aWMpKioKLSBGdWxsIG5hdHVyYWwgbGFuZ3VhZ2UgcXVlc3Rpb24KLSBCZSBzcGVjaWZpYzogYCJob3cgZG9lcyB0aGUgcmF0ZSBsaW1pdGVyIGhhbmRsZSBidXJzdCB0cmFmZmljImAKLSBJbmNsdWRlIGNvbnRleHQ6IGAiaW4gdGhlIHBheW1lbnQgc2VydmljZSwgaG93IGFyZSByZWZ1bmRzIHByb2Nlc3NlZCJgCgoqKmh5ZGUgKGh5cG90aGV0aWNhbCBkb2N1bWVudCkqKgotIFdyaXRlIDUwLTEwMCB3b3JkcyBvZiB3aGF0IHRoZSAqYW5zd2VyKiBsb29rcyBsaWtlCi0gVXNlIHRoZSB2b2NhYnVsYXJ5IHlvdSBleHBlY3QgaW4gdGhlIHJlc3VsdAoKKipleHBhbmQgKGF1dG8tZXhwYW5kKSoqCi0gVXNlIGEgc2luZ2xlLWxpbmUgcXVlcnkgKGltcGxpY2l0KSBvciBgZXhwYW5kOiBxdWVzdGlvbmAgb24gaXRzIG93biBsaW5lCi0gTGV0cyB0aGUgbG9jYWwgTExNIGdlbmVyYXRlIGxleC92ZWMvaHlkZSB2YXJpYXRpb25zCi0gRG8gbm90IG1peCBgZXhwYW5kOmAgd2l0aCBvdGhlciB0eXBlZCBsaW5lcyDigJQgaXQncyBlaXRoZXIgYSBzdGFuZGFsb25lIGV4cGFuZCBxdWVyeSBvciBhIGZ1bGwgcXVlcnkgZG9jdW1lbnQKCiMjIyBJbnRlbnQgKERpc2FtYmlndWF0aW9uKQoKV2hlbiBhIHF1ZXJ5IHRlcm0gaXMgYW1iaWd1b3VzLCBhZGQgYGludGVudGAgdG8gc3RlZXIgcmVzdWx0czoKCmBgYGpzb24KewogICJzZWFyY2hlcyI6IFsKICAgIHsgInR5cGUiOiAibGV4IiwgInF1ZXJ5IjogInBlcmZvcm1hbmNlIiB9CiAgXSwKICAiaW50ZW50IjogIndlYiBwYWdlIGxvYWQgdGltZXMgYW5kIENvcmUgV2ViIFZpdGFscyIKfQpgYGAKCkludGVudCBhZmZlY3RzIGV4cGFuc2lvbiwgcmVyYW5raW5nLCBjaHVuayBzZWxlY3Rpb24sIGFuZCBzbmlwcGV0IGV4dHJhY3Rpb24uIEl0IGRvZXMgbm90IHNlYXJjaCBvbiBpdHMgb3duIOKAlCBpdCdzIGEgc3RlZXJpbmcgc2lnbmFsIHRoYXQgZGlzYW1iaWd1YXRlcyBxdWVyaWVzIGxpa2UgInBlcmZvcm1hbmNlIiAod2ViLXBlcmYgdnMgdGVhbSBoZWFsdGggdnMgZml0bmVzcykuCgojIyMgQ29tYmluaW5nIFR5cGVzCgp8IEdvYWwgfCBBcHByb2FjaCB8CnwtLS0tLS18LS0tLS0tLS0tLXwKfCBLbm93IGV4YWN0IHRlcm1zIHwgYGxleGAgb25seSB8CnwgRG9uJ3Qga25vdyB2b2NhYnVsYXJ5IHwgVXNlIGEgc2luZ2xlLWxpbmUgcXVlcnkgKGltcGxpY2l0IGBleHBhbmQ6YCkgb3IgYHZlY2AgfAp8IEJlc3QgcmVjYWxsIHwgYGxleGAgKyBgdmVjYCB8CnwgQ29tcGxleCB0b3BpYyB8IGBsZXhgICsgYHZlY2AgKyBgaHlkZWAgfAp8IEFtYmlndW91cyBxdWVyeSB8IEFkZCBgaW50ZW50YCB0byBhbnkgY29tYmluYXRpb24gYWJvdmUgfAoKRmlyc3QgcXVlcnkgZ2V0cyAyeCB3ZWlnaHQgaW4gZnVzaW9uIOKAlCBwdXQgeW91ciBiZXN0IGd1ZXNzIGZpcnN0LgoKIyMjIExleCBRdWVyeSBTeW50YXgKCnwgU3ludGF4IHwgTWVhbmluZyB8IEV4YW1wbGUgfAp8LS0tLS0tLS18LS0tLS0tLS0tfC0tLS0tLS0tLXwKfCBgdGVybWAgfCBQcmVmaXggbWF0Y2ggfCBgcGVyZmAgbWF0Y2hlcyAicGVyZm9ybWFuY2UiIHwKfCBgInBocmFzZSJgIHwgRXhhY3QgcGhyYXNlIHwgYCJyYXRlIGxpbWl0ZXIiYCB8CnwgYC10ZXJtYCB8IEV4Y2x1ZGUgfCBgcGVyZm9ybWFuY2UgLXNwb3J0c2AgfAoKTm90ZTogYC10ZXJtYCBvbmx5IHdvcmtzIGluIGxleCBxdWVyaWVzLCBub3QgdmVjL2h5ZGUuCgojIyMgQ29sbGVjdGlvbiBGaWx0ZXJpbmcKCmBgYGpzb24KeyAiY29sbGVjdGlvbnMiOiBbImRvY3MiXSB9ICAgICAgICAgICAgICAvLyBTaW5nbGUKeyAiY29sbGVjdGlvbnMiOiBbImRvY3MiLCAibm90ZXMiXSB9ICAgICAvLyBNdWx0aXBsZSAoT1IpCmBgYAoKT21pdCB0byBzZWFyY2ggYWxsIGNvbGxlY3Rpb25zLgoKIyMgT3RoZXIgTUNQIFRvb2xzCgp8IFRvb2wgfCBVc2UgfAp8LS0tLS0tfC0tLS0tfAp8IGBnZXRgIHwgUmV0cmlldmUgZG9jIGJ5IHBhdGggb3IgYCNkb2NpZGAgfAp8IGBtdWx0aV9nZXRgIHwgUmV0cmlldmUgbXVsdGlwbGUgYnkgZ2xvYi9saXN0IHwKfCBgc3RhdHVzYCB8IENvbGxlY3Rpb25zIGFuZCBoZWFsdGggfAoKIyMgQ0xJCgpgYGBiYXNoCnFtZCBxdWVyeSAicXVlc3Rpb24iICAgICAgICAgICAgICAjIEF1dG8tZXhwYW5kICsgcmVyYW5rCnFtZCBxdWVyeSAkJ2xleDogWFxudmVjOiBZJyAgICAgICAjIFN0cnVjdHVyZWQKcW1kIHF1ZXJ5ICQnZXhwYW5kOiBxdWVzdGlvbicgICAgICMgRXhwbGljaXQgZXhwYW5kCnFtZCBxdWVyeSAtLWpzb24gLS1leHBsYWluICJxIiAgICAjIFNob3cgc2NvcmUgdHJhY2VzIChSUkYgKyByZXJhbmsgYmxlbmQpCnFtZCBzZWFyY2ggImtleXdvcmRzIiAgICAgICAgICAgICAjIEJNMjUgb25seSAobm8gTExNKQpxbWQgZ2V0ICIjYWJjMTIzIiAgICAgICAgICAgICAgICAgIyBCeSBkb2NpZApxbWQgbXVsdGktZ2V0ICJqb3VybmFscy8yMDI2LSoubWQiIC1sIDQwICAjIEJhdGNoIHB1bGwgc25pcHBldHMgYnkgZ2xvYgpxbWQgbXVsdGktZ2V0IG5vdGVzL2Zvby5tZCxub3Rlcy9iYXIubWQgICAjIENvbW1hLXNlcGFyYXRlZCBsaXN0LCBwcmVzZXJ2ZXMgb3JkZXIKYGBgCgojIyBIVFRQIEFQSQoKYGBgYmFzaApjdXJsIC1YIFBPU1QgaHR0cDovL2xvY2FsaG9zdDo4MTgxL3F1ZXJ5IFwKICAtSCAiQ29udGVudC1UeXBlOiBhcHBsaWNhdGlvbi9qc29uIiBcCiAgLWQgJ3sic2VhcmNoZXMiOiBbeyJ0eXBlIjogImxleCIsICJxdWVyeSI6ICJ0ZXN0In1dfScKYGBgCgojIyBTZXR1cAoKYGBgYmFzaApucG0gaW5zdGFsbCAtZyBAdG9iaWx1L3FtZApxbWQgY29sbGVjdGlvbiBhZGQgfi9ub3RlcyAtLW5hbWUgbm90ZXMKcW1kIGVtYmVkCmBgYAo=",
+    "references/mcp-setup.md": "IyBRTUQgTUNQIFNlcnZlciBTZXR1cAoKIyMgSW5zdGFsbAoKYGBgYmFzaApucG0gaW5zdGFsbCAtZyBAdG9iaWx1L3FtZApxbWQgY29sbGVjdGlvbiBhZGQgfi9wYXRoL3RvL21hcmtkb3duIC0tbmFtZSBteWtub3dsZWRnZQpxbWQgZW1iZWQKYGBgCgojIyBDb25maWd1cmUgTUNQIENsaWVudAoKKipDbGF1ZGUgQ29kZSoqIChgfi8uY2xhdWRlL3NldHRpbmdzLmpzb25gKToKYGBganNvbgp7CiAgIm1jcFNlcnZlcnMiOiB7CiAgICAicW1kIjogeyAiY29tbWFuZCI6ICJxbWQiLCAiYXJncyI6IFsibWNwIl0gfQogIH0KfQpgYGAKCioqQ2xhdWRlIERlc2t0b3AqKiAoYH4vTGlicmFyeS9BcHBsaWNhdGlvbiBTdXBwb3J0L0NsYXVkZS9jbGF1ZGVfZGVza3RvcF9jb25maWcuanNvbmApOgpgYGBqc29uCnsKICAibWNwU2VydmVycyI6IHsKICAgICJxbWQiOiB7ICJjb21tYW5kIjogInFtZCIsICJhcmdzIjogWyJtY3AiXSB9CiAgfQp9CmBgYAoKKipPcGVuQ2xhdyoqIChgfi8ub3BlbmNsYXcvb3BlbmNsYXcuanNvbmApOgpgYGBqc29uCnsKICAibWNwIjogewogICAgInNlcnZlcnMiOiB7CiAgICAgICJxbWQiOiB7ICJjb21tYW5kIjogInFtZCIsICJhcmdzIjogWyJtY3AiXSB9CiAgICB9CiAgfQp9CmBgYAoKIyMgSFRUUCBNb2RlCgpgYGBiYXNoCnFtZCBtY3AgLS1odHRwICAgICAgICAgICAgICAjIFBvcnQgODE4MQpxbWQgbWNwIC0taHR0cCAtLWRhZW1vbiAgICAgIyBCYWNrZ3JvdW5kCnFtZCBtY3Agc3RvcCAgICAgICAgICAgICAgICAjIFN0b3AgZGFlbW9uCmBgYAoKIyMgVG9vbHMKCiMjIyBzdHJ1Y3R1cmVkX3NlYXJjaAoKU2VhcmNoIHdpdGggcHJlLWV4cGFuZGVkIHF1ZXJpZXMuCgpgYGBqc29uCnsKICAic2VhcmNoZXMiOiBbCiAgICB7ICJ0eXBlIjogImxleCIsICJxdWVyeSI6ICJrZXl3b3JkIHBocmFzZXMiIH0sCiAgICB7ICJ0eXBlIjogInZlYyIsICJxdWVyeSI6ICJuYXR1cmFsIGxhbmd1YWdlIHF1ZXN0aW9uIiB9LAogICAgeyAidHlwZSI6ICJoeWRlIiwgInF1ZXJ5IjogImh5cG90aGV0aWNhbCBhbnN3ZXIgcGFzc2FnZS4uLiIgfQogIF0sCiAgImxpbWl0IjogMTAsCiAgImNvbGxlY3Rpb24iOiAib3B0aW9uYWwiLAogICJtaW5TY29yZSI6IDAuMAp9CmBgYAoKfCBUeXBlIHwgTWV0aG9kIHwgSW5wdXQgfAp8LS0tLS0tfC0tLS0tLS0tfC0tLS0tLS18CnwgYGxleGAgfCBCTTI1IHwgS2V5d29yZHMgKDItNSB0ZXJtcykgfAp8IGB2ZWNgIHwgVmVjdG9yIHwgUXVlc3Rpb24gfAp8IGBoeWRlYCB8IFZlY3RvciB8IEFuc3dlciBwYXNzYWdlICg1MC0xMDAgd29yZHMpIHwKCiMjIyBnZXQKClJldHJpZXZlIGRvY3VtZW50IGJ5IHBhdGggb3IgYCNkb2NpZGAuCgp8IFBhcmFtIHwgVHlwZSB8IERlc2NyaXB0aW9uIHwKfC0tLS0tLS18LS0tLS0tfC0tLS0tLS0tLS0tLS18CnwgYHBhdGhgIHwgc3RyaW5nIHwgRmlsZSBwYXRoIG9yIGAjZG9jaWRgIHwKfCBgZnVsbGAgfCBib29sPyB8IFJldHVybiBmdWxsIGNvbnRlbnQgfAp8IGBsaW5lTnVtYmVyc2AgfCBib29sPyB8IEFkZCBsaW5lIG51bWJlcnMgfAoKIyMjIG11bHRpX2dldAoKUmV0cmlldmUgbXVsdGlwbGUgZG9jdW1lbnRzLgoKfCBQYXJhbSB8IFR5cGUgfCBEZXNjcmlwdGlvbiB8CnwtLS0tLS0tfC0tLS0tLXwtLS0tLS0tLS0tLS0tfAp8IGBwYXR0ZXJuYCB8IHN0cmluZyB8IEdsb2Igb3IgY29tbWEtc2VwYXJhdGVkIGxpc3QgfAp8IGBtYXhCeXRlc2AgfCBudW1iZXI/IHwgU2tpcCBsYXJnZSBmaWxlcyAoZGVmYXVsdCAxMEtCKSB8CgojIyMgc3RhdHVzCgpJbmRleCBoZWFsdGggYW5kIGNvbGxlY3Rpb25zLiBObyBwYXJhbXMuCgojIyBUcm91Ymxlc2hvb3RpbmcKCi0gKipOb3Qgc3RhcnRpbmcqKjogYHdoaWNoIHFtZGAsIGBxbWQgbWNwYCBtYW51YWxseQotICoqTm8gcmVzdWx0cyoqOiBgcW1kIGNvbGxlY3Rpb24gbGlzdGAsIGBxbWQgZW1iZWRgCi0gKipTbG93IGZpcnN0IHNlYXJjaCoqOiBOb3JtYWwsIG1vZGVscyBsb2FkaW5nICh+M0dCKQo="
+};
+export function getEmbeddedQmdSkillFiles() {
+    return Object.entries(EMBEDDED_QMD_SKILL_BASE64).map(([relativePath, encoded]) => ({
+        relativePath,
+        content: Buffer.from(encoded, 'base64').toString('utf8'),
+    }));
+}
+export function getEmbeddedQmdSkillContent() {
+    return Buffer.from(EMBEDDED_QMD_SKILL_BASE64["SKILL.md"], "base64").toString("utf8");
+}

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * Usage:
  *   import { createStore } from '@tobilu/qmd'
  *
- *   const store = createStore({
+ *   const store = await createStore({
  *     dbPath: './my-index.sqlite',
  *     config: {
  *       collections: {
@@ -13,15 +13,85 @@
  *     }
  *   })
  *
- *   const results = await store.query("how does auth work?")
- *   store.close()
+ *   const results = await store.search({ query: "how does auth work?" })
+ *   await store.close()
  */
-import { type Store as InternalStore, type DocumentResult, type DocumentNotFound, type SearchResult, type HybridQueryResult, type HybridQueryOptions, type HybridQueryExplain, type StructuredSubSearch, type StructuredSearchOptions, type MultiGetResult, type IndexStatus, type IndexHealthInfo, type ExpandedQuery, type SearchHooks } from "./store.js";
+import { extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES, type Store as InternalStore, type DocumentResult, type DocumentNotFound, type SearchResult, type HybridQueryResult, type HybridQueryOptions, type HybridQueryExplain, type ExpandedQuery, type StructuredSearchOptions, type MultiGetResult, type IndexStatus, type IndexHealthInfo, type SearchHooks, type ReindexProgress, type ReindexResult, type EmbedProgress, type EmbedResult } from "./store.js";
 import { type Collection, type CollectionConfig, type NamedCollection, type ContextMap } from "./collections.js";
-export type { DocumentResult, DocumentNotFound, SearchResult, HybridQueryResult, HybridQueryOptions, HybridQueryExplain, StructuredSubSearch, StructuredSearchOptions, MultiGetResult, IndexStatus, IndexHealthInfo, ExpandedQuery, SearchHooks, Collection, CollectionConfig, NamedCollection, ContextMap, };
+export type { DocumentResult, DocumentNotFound, SearchResult, HybridQueryResult, HybridQueryOptions, HybridQueryExplain, ExpandedQuery, StructuredSearchOptions, MultiGetResult, IndexStatus, IndexHealthInfo, SearchHooks, ReindexProgress, ReindexResult, EmbedProgress, EmbedResult, Collection, CollectionConfig, NamedCollection, ContextMap, };
+export type { InternalStore };
+export { extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES };
+export { getDefaultDbPath } from "./store.js";
+export { Maintenance } from "./maintenance.js";
+/**
+ * Progress info emitted during update() for each file processed.
+ */
+export type UpdateProgress = {
+    collection: string;
+    file: string;
+    current: number;
+    total: number;
+};
+/**
+ * Aggregated result from update() across all collections.
+ */
+export type UpdateResult = {
+    collections: number;
+    indexed: number;
+    updated: number;
+    unchanged: number;
+    removed: number;
+    needsEmbedding: number;
+};
+/**
+ * Options for the unified search() method.
+ */
+export interface SearchOptions {
+    /** Simple query string — will be auto-expanded via LLM */
+    query?: string;
+    /** Pre-expanded queries (from expandQuery) — skips auto-expansion */
+    queries?: ExpandedQuery[];
+    /** Domain intent hint — steers expansion and reranking */
+    intent?: string;
+    /** Rerank results using LLM (default: true) */
+    rerank?: boolean;
+    /** Filter to a specific collection */
+    collection?: string;
+    /** Filter to specific collections */
+    collections?: string[];
+    /** Max results (default: 10) */
+    limit?: number;
+    /** Minimum score threshold */
+    minScore?: number;
+    /** Include explain traces */
+    explain?: boolean;
+}
+/**
+ * Options for searchLex() — BM25 keyword search.
+ */
+export interface LexSearchOptions {
+    limit?: number;
+    collection?: string;
+}
+/**
+ * Options for searchVector() — vector similarity search.
+ */
+export interface VectorSearchOptions {
+    limit?: number;
+    collection?: string;
+}
+/**
+ * Options for expandQuery() — manual query expansion.
+ */
+export interface ExpandQueryOptions {
+    intent?: string;
+}
 /**
  * Options for creating a QMD store.
- * You must provide `dbPath` and either `configPath` (YAML file) or `config` (inline).
+ *
+ * Provide `dbPath` and optionally `configPath` (YAML file) or `config` (inline).
+ * If neither configPath nor config is provided, the store reads from existing
+ * DB state (useful for reopening a previously-configured store).
  */
 export interface StoreOptions {
     /** Path to the SQLite database file */
@@ -34,72 +104,93 @@ export interface StoreOptions {
 /**
  * The QMD SDK store — provides search, retrieval, collection management,
  * context management, and indexing operations.
+ *
+ * All methods are async. The store manages its own LlamaCpp instance
+ * (lazy-loaded, auto-unloaded after inactivity) — no global singletons.
  */
 export interface QMDStore {
     /** The underlying internal store (for advanced use) */
     readonly internal: InternalStore;
     /** Path to the SQLite database */
     readonly dbPath: string;
-    /** Hybrid search: BM25 + vector + query expansion + LLM reranking */
-    query(query: string, options?: HybridQueryOptions): Promise<HybridQueryResult[]>;
-    /** BM25 full-text keyword search (fast, no LLM) */
-    search(query: string, options?: {
-        limit?: number;
-        collection?: string;
-    }): SearchResult[];
-    /** Structured search with pre-expanded queries (for LLM callers) */
-    structuredSearch(searches: StructuredSubSearch[], options?: StructuredSearchOptions): Promise<HybridQueryResult[]>;
+    /** Full search: query expansion + multi-signal retrieval + LLM reranking */
+    search(options: SearchOptions): Promise<HybridQueryResult[]>;
+    /** BM25 keyword search (fast, no LLM) */
+    searchLex(query: string, options?: LexSearchOptions): Promise<SearchResult[]>;
+    /** Vector similarity search (embedding model, no reranking) */
+    searchVector(query: string, options?: VectorSearchOptions): Promise<SearchResult[]>;
+    /** Expand a query into typed sub-searches (lex/vec/hyde) for manual control */
+    expandQuery(query: string, options?: ExpandQueryOptions): Promise<ExpandedQuery[]>;
     /** Get a single document by path or docid */
     get(pathOrDocid: string, options?: {
         includeBody?: boolean;
-    }): DocumentResult | DocumentNotFound;
+    }): Promise<DocumentResult | DocumentNotFound>;
+    /** Get the body content of a document, optionally sliced by line range */
+    getDocumentBody(pathOrDocid: string, opts?: {
+        fromLine?: number;
+        maxLines?: number;
+    }): Promise<string | null>;
     /** Get multiple documents by glob pattern or comma-separated list */
     multiGet(pattern: string, options?: {
         includeBody?: boolean;
         maxBytes?: number;
-    }): {
+    }): Promise<{
         docs: MultiGetResult[];
         errors: string[];
-    };
+    }>;
     /** Add or update a collection */
     addCollection(name: string, opts: {
         path: string;
         pattern?: string;
         ignore?: string[];
-    }): void;
+    }): Promise<void>;
     /** Remove a collection */
-    removeCollection(name: string): boolean;
+    removeCollection(name: string): Promise<boolean>;
     /** Rename a collection */
-    renameCollection(oldName: string, newName: string): boolean;
+    renameCollection(oldName: string, newName: string): Promise<boolean>;
     /** List all collections with document stats */
-    listCollections(): {
+    listCollections(): Promise<{
         name: string;
         pwd: string;
         glob_pattern: string;
         doc_count: number;
         active_count: number;
         last_modified: string | null;
-    }[];
+        includeByDefault: boolean;
+    }[]>;
+    /** Get names of collections included by default in queries */
+    getDefaultCollectionNames(): Promise<string[]>;
     /** Add context for a path within a collection */
-    addContext(collectionName: string, pathPrefix: string, contextText: string): boolean;
+    addContext(collectionName: string, pathPrefix: string, contextText: string): Promise<boolean>;
     /** Remove context from a collection path */
-    removeContext(collectionName: string, pathPrefix: string): boolean;
+    removeContext(collectionName: string, pathPrefix: string): Promise<boolean>;
     /** Set global context (applies to all collections) */
-    setGlobalContext(context: string | undefined): void;
+    setGlobalContext(context: string | undefined): Promise<void>;
     /** Get global context */
-    getGlobalContext(): string | undefined;
+    getGlobalContext(): Promise<string | undefined>;
     /** List all contexts across all collections */
-    listContexts(): Array<{
+    listContexts(): Promise<Array<{
         collection: string;
         path: string;
         context: string;
-    }>;
+    }>>;
+    /** Re-index collections by scanning the filesystem */
+    update(options?: {
+        collections?: string[];
+        onProgress?: (info: UpdateProgress) => void;
+    }): Promise<UpdateResult>;
+    /** Generate vector embeddings for documents that need them */
+    embed(options?: {
+        force?: boolean;
+        model?: string;
+        onProgress?: (info: EmbedProgress) => void;
+    }): Promise<EmbedResult>;
     /** Get index status (document counts, collections, embedding state) */
-    getStatus(): IndexStatus;
+    getStatus(): Promise<IndexStatus>;
     /** Get index health info (stale embeddings, etc.) */
-    getIndexHealth(): IndexHealthInfo;
-    /** Close the database connection */
-    close(): void;
+    getIndexHealth(): Promise<IndexHealthInfo>;
+    /** Close the store and release all resources (LLM models, DB connection) */
+    close(): Promise<void>;
 }
 /**
  * Create a QMD store for programmatic access to search and indexing.
@@ -107,13 +198,13 @@ export interface QMDStore {
  * @example
  * ```typescript
  * // With a YAML config file
- * const store = createStore({
+ * const store = await createStore({
  *   dbPath: './index.sqlite',
  *   configPath: './qmd.yml',
  * })
  *
  * // With inline config (no files needed besides the DB)
- * const store = createStore({
+ * const store = await createStore({
  *   dbPath: './index.sqlite',
  *   config: {
  *     collections: {
@@ -122,8 +213,8 @@ export interface QMDStore {
  *   }
  * })
  *
- * const results = await store.query("authentication flow")
- * store.close()
+ * const results = await store.search({ query: "authentication flow" })
+ * await store.close()
  * ```
  */
-export declare function createStore(options: StoreOptions): QMDStore;
+export declare function createStore(options: StoreOptions): Promise<QMDStore>;

package/dist/index.js

@@ -4,7 +4,7 @@
  * Usage:
  *   import { createStore } from '@tobilu/qmd'
  *
- *   const store = createStore({
+ *   const store = await createStore({
  *     dbPath: './my-index.sqlite',
  *     config: {
  *       collections: {
@@ -13,24 +13,31 @@
  *     }
  *   })
  *
- *   const results = await store.query("how does auth work?")
- *   store.close()
+ *   const results = await store.search({ query: "how does auth work?" })
+ *   await store.close()
  */
-import { createStore as createStoreInternal, hybridQuery, structuredSearch, listCollections as storeListCollections, } from "./store.js";
-import { setConfigSource, loadConfig, addCollection as collectionsAddCollection, removeCollection as collectionsRemoveCollection, renameCollection as collectionsRenameCollection, listCollections as collectionsListCollections, addContext as collectionsAddContext, removeContext as collectionsRemoveContext, setGlobalContext as collectionsSetGlobalContext, getGlobalContext as collectionsGetGlobalContext, listAllContexts as collectionsListAllContexts, } from "./collections.js";
+import { createStore as createStoreInternal, hybridQuery, structuredSearch, extractSnippet, addLineNumbers, DEFAULT_EMBED_MODEL, DEFAULT_MULTI_GET_MAX_BYTES, reindexCollection, generateEmbeddings, listCollections as storeListCollections, syncConfigToDb, getStoreCollections, getStoreCollection, getStoreGlobalContext, getStoreContexts, upsertStoreCollection, deleteStoreCollection, renameStoreCollection, updateStoreContext, removeStoreContext, setStoreGlobalContext, vacuumDatabase, cleanupOrphanedContent, cleanupOrphanedVectors, deleteLLMCache, deleteInactiveDocuments, clearAllEmbeddings, } from "./store.js";
+import { LlamaCpp, } from "./llm.js";
+import { setConfigSource, loadConfig, addCollection as collectionsAddCollection, removeCollection as collectionsRemoveCollection, renameCollection as collectionsRenameCollection, addContext as collectionsAddContext, removeContext as collectionsRemoveContext, setGlobalContext as collectionsSetGlobalContext, } from "./collections.js";
+// Re-export utility functions used by frontends
+export { extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES };
+// Re-export getDefaultDbPath for CLI/MCP that need the default database location
+export { getDefaultDbPath } from "./store.js";
+// Re-export Maintenance class for CLI housekeeping operations
+export { Maintenance } from "./maintenance.js";
 /**
  * Create a QMD store for programmatic access to search and indexing.
  *
  * @example
  * ```typescript
  * // With a YAML config file
- * const store = createStore({
+ * const store = await createStore({
  *   dbPath: './index.sqlite',
  *   configPath: './qmd.yml',
  * })
  *
  * // With inline config (no files needed besides the DB)
- * const store = createStore({
+ * const store = await createStore({
  *   dbPath: './index.sqlite',
  *   config: {
  *     collections: {
@@ -39,56 +46,183 @@ import { setConfigSource, loadConfig, addCollection as collectionsAddCollection,
  *   }
  * })
  *
- * const results = await store.query("authentication flow")
- * store.close()
+ * const results = await store.search({ query: "authentication flow" })
+ * await store.close()
  * ```
  */
-export function createStore(options) {
+export async function createStore(options) {
     if (!options.dbPath) {
         throw new Error("dbPath is required");
     }
-    if (!options.configPath && !options.config) {
-        throw new Error("Either configPath or config is required");
-    }
     if (options.configPath && options.config) {
         throw new Error("Provide either configPath or config, not both");
     }
-    // Inject config source into collections module
-    setConfigSource({
-        configPath: options.configPath,
-        config: options.config,
-    });
-    // Create the internal store
+    // Create the internal store (opens DB, creates tables)
     const internal = createStoreInternal(options.dbPath);
+    const db = internal.db;
+    // Track whether we have a YAML config path for write-through
+    const hasYamlConfig = !!options.configPath;
+    // Sync config into SQLite store_collections
+    if (options.configPath) {
+        // YAML mode: inject config source for write-through, sync to DB
+        setConfigSource({ configPath: options.configPath });
+        const config = loadConfig();
+        syncConfigToDb(db, config);
+    }
+    else if (options.config) {
+        // Inline config mode: inject config source for mutations, sync to DB
+        setConfigSource({ config: options.config });
+        syncConfigToDb(db, options.config);
+    }
+    // else: DB-only mode — no external config, use existing store_collections
+    // Create a per-store LlamaCpp instance — lazy-loads models on first use,
+    // auto-unloads after 5 min inactivity to free VRAM.
+    const llm = new LlamaCpp({
+        inactivityTimeoutMs: 5 * 60 * 1000,
+        disposeModelsOnInactivity: true,
+    });
+    internal.llm = llm;
     const store = {
         internal,
         dbPath: internal.dbPath,
-        // Search & Retrieval
-        query: (q, opts) => hybridQuery(internal, q, opts),
-        search: (q, opts) => internal.searchFTS(q, opts?.limit, opts?.collection),
-        structuredSearch: (searches, opts) => structuredSearch(internal, searches, opts),
-        get: (pathOrDocid, opts) => internal.findDocument(pathOrDocid, opts),
-        multiGet: (pattern, opts) => internal.findDocuments(pattern, opts),
-        // Collection Management
-        addCollection: (name, opts) => {
-            collectionsAddCollection(name, opts.path, opts.pattern);
+        // Search
+        search: async (opts) => {
+            if (!opts.query && !opts.queries) {
+                throw new Error("search() requires either 'query' or 'queries'");
+            }
+            // Normalize collection/collections
+            const collections = [
+                ...(opts.collection ? [opts.collection] : []),
+                ...(opts.collections ?? []),
+            ];
+            const skipRerank = opts.rerank === false;
+            if (opts.queries) {
+                // Pre-expanded queries — use structuredSearch
+                return structuredSearch(internal, opts.queries, {
+                    collections: collections.length > 0 ? collections : undefined,
+                    limit: opts.limit,
+                    minScore: opts.minScore,
+                    explain: opts.explain,
+                    intent: opts.intent,
+                    skipRerank,
+                });
+            }
+            // Simple query string — use hybridQuery (expand + search + rerank)
+            return hybridQuery(internal, opts.query, {
+                collection: collections[0],
+                limit: opts.limit,
+                minScore: opts.minScore,
+                explain: opts.explain,
+                intent: opts.intent,
+                skipRerank,
+            });
+        },
+        searchLex: async (q, opts) => internal.searchFTS(q, opts?.limit, opts?.collection),
+        searchVector: async (q, opts) => internal.searchVec(q, DEFAULT_EMBED_MODEL, opts?.limit, opts?.collection),
+        expandQuery: async (q, opts) => internal.expandQuery(q, undefined, opts?.intent),
+        get: async (pathOrDocid, opts) => internal.findDocument(pathOrDocid, opts),
+        getDocumentBody: async (pathOrDocid, opts) => {
+            const result = internal.findDocument(pathOrDocid, { includeBody: false });
+            if ("error" in result)
+                return null;
+            return internal.getDocumentBody(result, opts?.fromLine, opts?.maxLines);
+        },
+        multiGet: async (pattern, opts) => internal.findDocuments(pattern, opts),
+        // Collection Management — write to SQLite + write-through to YAML/inline if configured
+        addCollection: async (name, opts) => {
+            upsertStoreCollection(db, name, { path: opts.path, pattern: opts.pattern, ignore: opts.ignore });
+            if (hasYamlConfig || options.config) {
+                collectionsAddCollection(name, opts.path, opts.pattern);
+            }
+        },
+        removeCollection: async (name) => {
+            const result = deleteStoreCollection(db, name);
+            if (hasYamlConfig || options.config) {
+                collectionsRemoveCollection(name);
+            }
+            return result;
+        },
+        renameCollection: async (oldName, newName) => {
+            const result = renameStoreCollection(db, oldName, newName);
+            if (hasYamlConfig || options.config) {
+                collectionsRenameCollection(oldName, newName);
+            }
+            return result;
+        },
+        listCollections: async () => storeListCollections(db),
+        getDefaultCollectionNames: async () => {
+            const collections = storeListCollections(db);
+            return collections.filter(c => c.includeByDefault).map(c => c.name);
+        },
+        // Context Management — write to SQLite + write-through to YAML/inline if configured
+        addContext: async (collectionName, pathPrefix, contextText) => {
+            const result = updateStoreContext(db, collectionName, pathPrefix, contextText);
+            if (hasYamlConfig || options.config) {
+                collectionsAddContext(collectionName, pathPrefix, contextText);
+            }
+            return result;
+        },
+        removeContext: async (collectionName, pathPrefix) => {
+            const result = removeStoreContext(db, collectionName, pathPrefix);
+            if (hasYamlConfig || options.config) {
+                collectionsRemoveContext(collectionName, pathPrefix);
+            }
+            return result;
+        },
+        setGlobalContext: async (context) => {
+            setStoreGlobalContext(db, context);
+            if (hasYamlConfig || options.config) {
+                collectionsSetGlobalContext(context);
+            }
+        },
+        getGlobalContext: async () => getStoreGlobalContext(db),
+        listContexts: async () => getStoreContexts(db),
+        // Indexing — reads collections from SQLite
+        update: async (updateOpts) => {
+            const collections = getStoreCollections(db);
+            const filtered = updateOpts?.collections
+                ? collections.filter(c => updateOpts.collections.includes(c.name))
+                : collections;
+            internal.clearCache();
+            let totalIndexed = 0, totalUpdated = 0, totalUnchanged = 0, totalRemoved = 0;
+            for (const col of filtered) {
+                const result = await reindexCollection(internal, col.path, col.pattern || "**/*.md", col.name, {
+                    ignorePatterns: col.ignore,
+                    onProgress: updateOpts?.onProgress
+                        ? (info) => updateOpts.onProgress({ collection: col.name, ...info })
+                        : undefined,
+                });
+                totalIndexed += result.indexed;
+                totalUpdated += result.updated;
+                totalUnchanged += result.unchanged;
+                totalRemoved += result.removed;
+            }
+            return {
+                collections: filtered.length,
+                indexed: totalIndexed,
+                updated: totalUpdated,
+                unchanged: totalUnchanged,
+                removed: totalRemoved,
+                needsEmbedding: internal.getHashesNeedingEmbedding(),
+            };
+        },
+        embed: async (embedOpts) => {
+            return generateEmbeddings(internal, {
+                force: embedOpts?.force,
+                model: embedOpts?.model,
+                onProgress: embedOpts?.onProgress,
+            });
         },
-        removeCollection: (name) => collectionsRemoveCollection(name),
-        renameCollection: (oldName, newName) => collectionsRenameCollection(oldName, newName),
-        listCollections: () => storeListCollections(internal.db),
-        // Context Management
-        addContext: (collectionName, pathPrefix, contextText) => collectionsAddContext(collectionName, pathPrefix, contextText),
-        removeContext: (collectionName, pathPrefix) => collectionsRemoveContext(collectionName, pathPrefix),
-        setGlobalContext: (context) => collectionsSetGlobalContext(context),
-        getGlobalContext: () => collectionsGetGlobalContext(),
-        listContexts: () => collectionsListAllContexts(),
         // Index Health
-        getStatus: () => internal.getStatus(),
-        getIndexHealth: () => internal.getIndexHealth(),
+        getStatus: async () => internal.getStatus(),
+        getIndexHealth: async () => internal.getIndexHealth(),
         // Lifecycle
-        close: () => {
+        close: async () => {
+            await llm.dispose();
             internal.close();
-            setConfigSource(undefined); // Reset config source
+            if (hasYamlConfig || options.config) {
+                setConfigSource(undefined); // Reset config source
+            }
         },
     };
     return store;

package/dist/llm.d.ts

@@ -212,6 +212,7 @@ export type LlamaCppConfig = {
     disposeModelsOnInactivity?: boolean;
 };
 export declare class LlamaCpp implements LLM {
+    private readonly _ciMode;
     private llama;
     private embedModel;
     private embedContexts;
@@ -373,6 +374,11 @@ export declare class SessionReleasedError extends Error {
  * ```
  */
 export declare function withLLMSession<T>(fn: (session: ILLMSession) => Promise<T>, options?: LLMSessionOptions): Promise<T>;
+/**
+ * Execute a function with a scoped LLM session using a specific LlamaCpp instance.
+ * Unlike withLLMSession, this does not use the global singleton.
+ */
+export declare function withLLMSessionForLlm<T>(llm: LlamaCpp, fn: (session: ILLMSession) => Promise<T>, options?: LLMSessionOptions): Promise<T>;
 /**
  * Check if idle unload is safe (no active sessions or operations).
  * Used internally by LlamaCpp idle timer.

package/dist/llm.js

@@ -47,7 +47,7 @@ export function formatDocForEmbedding(text, title, modelUri) {
 // =============================================================================
 // HuggingFace model URIs for node-llama-cpp
 // Format: hf:<user>/<repo>/<file>
-// Override via QMD_EMBED_MODEL env var (e.g. hf:Qwen/Qwen3-Embedding-0.6B-GGUF/qwen3-embedding-0.6b-q8_0.gguf)
+// Override via QMD_EMBED_MODEL env var (e.g. hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf)
 const DEFAULT_EMBED_MODEL = process.env.QMD_EMBED_MODEL ?? "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
 const DEFAULT_RERANK_MODEL = "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf";
 // const DEFAULT_GENERATE_MODEL = "hf:ggml-org/Qwen3-0.6B-GGUF/Qwen3-0.6B-Q8_0.gguf";
@@ -164,6 +164,7 @@ function resolveExpandContextSize(configValue) {
     return parsed;
 }
 export class LlamaCpp {
+    _ciMode = !!process.env.CI;
     llama = null;
     embedModel = null;
     embedContexts = [];
@@ -575,6 +576,8 @@ export class LlamaCpp {
      * Uses Promise.all for parallel embedding - node-llama-cpp handles batching internally
      */
     async embedBatch(texts) {
+        if (this._ciMode)
+            throw new Error("LLM operations are disabled in CI (set CI=true)");
         // Ping activity at start to keep models alive during this operation
         this.touchActivity();
         if (texts.length === 0)
@@ -626,6 +629,8 @@ export class LlamaCpp {
         }
     }
     async generate(prompt, options = {}) {
+        if (this._ciMode)
+            throw new Error("LLM operations are disabled in CI (set CI=true)");
         // Ping activity at start to keep models alive during this operation
         this.touchActivity();
         // Ensure model is loaded
@@ -677,6 +682,8 @@ export class LlamaCpp {
     // High-level abstractions
     // ==========================================================================
     async expandQuery(query, options = {}) {
+        if (this._ciMode)
+            throw new Error("LLM operations are disabled in CI (set CI=true)");
         // Ping activity at start to keep models alive during this operation
         this.touchActivity();
         const llama = await this.ensureLlama();
@@ -764,6 +771,8 @@ export class LlamaCpp {
     static RERANK_TEMPLATE_OVERHEAD = 200;
     static RERANK_TARGET_DOCS_PER_CONTEXT = 10;
     async rerank(query, documents, options = {}) {
+        if (this._ciMode)
+            throw new Error("LLM operations are disabled in CI (set CI=true)");
         // Ping activity at start to keep models alive during this operation
         this.touchActivity();
         const contexts = await this.ensureRerankContexts();
@@ -1065,6 +1074,20 @@ export async function withLLMSession(fn, options) {
         session.release();
     }
 }
+/**
+ * Execute a function with a scoped LLM session using a specific LlamaCpp instance.
+ * Unlike withLLMSession, this does not use the global singleton.
+ */
+export async function withLLMSessionForLlm(llm, fn, options) {
+    const manager = new LLMSessionManager(llm);
+    const session = new LLMSession(manager, options);
+    try {
+        return await fn(session);
+    }
+    finally {
+        session.release();
+    }
+}
 /**
  * Check if idle unload is safe (no active sessions or operations).
  * Used internally by LlamaCpp idle timer.

package/dist/maintenance.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Maintenance - Database cleanup operations for QMD.
+ *
+ * Wraps low-level store operations that the CLI needs for housekeeping.
+ * Takes an internal Store in the constructor — allowed to access DB directly.
+ */
+import type { Store } from "./store.js";
+export declare class Maintenance {
+    private store;
+    constructor(store: Store);
+    /** Run VACUUM on the SQLite database to reclaim space */
+    vacuum(): void;
+    /** Remove content rows that are no longer referenced by any document */
+    cleanupOrphanedContent(): number;
+    /** Remove vector embeddings for content that no longer exists */
+    cleanupOrphanedVectors(): number;
+    /** Clear the LLM response cache (query expansion, reranking) */
+    clearLLMCache(): number;
+    /** Delete documents marked as inactive (removed from filesystem) */
+    deleteInactiveDocs(): number;
+    /** Clear all vector embeddings (forces re-embedding) */
+    clearEmbeddings(): void;
+}