@wei840222/qmd 2026.8.28 → 2026.9.25

package/CHANGELOG.md

@@ -2,9 +2,27 @@
 
 ## [Unreleased]
 
+## [2026.9.25] - 2026-09-26
+
+### Changed
+
+- Replace `better-sqlite3` with Node.js built-in `node:sqlite`, preventing SQLite runtime symbol collisions when QMD is embedded alongside other `node:sqlite` consumers. The minimum supported Node.js version is now 22.16.0.
+- Upgraded `@node-rs/jieba` to `2.0.3` and synchronized bundled Traditional Chinese dictionary assets (`zh-dict.txt`) with upstream `sysprog21/zhtw-mcp`.
+- Relocated repository release management skill to `.agents/skills/release`.
+
 ### Added
 
+- Added Oxlint lint fence.
+- Document metadata and metadata filtering. Markdown documents can opt into typed metadata through a namespaced frontmatter block (`qmd.metadata` with strings, numbers, booleans, or flat homogeneous arrays), and every search surface — CLI `search`/`vsearch`/`query` via `--filter <json>`, the SDK's `filter` option on `search()`/`searchLex()`/`searchVector()`, the MCP `query` tool, and HTTP `POST /query` and `/search` — accepts one shared recursive filter AST discriminated by `operator`: `and`/`or`/`not` logical groups, `eq`/`ne`/`gt`/`gte`/`lt`/`lte` comparisons, `in`/`nin`/`all` membership, and `exists` presence. Every returned result satisfies the filter (applied before RRF fusion and reranking); like collection filtering, highly selective filters remain best-effort for top-K completeness. Frontmatter stays ordinary searchable content — no chunking, embedding, snippet, or line-number changes — and documents without `qmd.metadata` behave exactly as before. JSON/SDK/MCP/HTTP results now include each document's indexed metadata, and `qmd status` reports how many documents still need metadata extraction (a normal `qmd update` backfills existing indexes).
 - **Disable HyDE Expansion Control**: Added `--no-hyde` CLI option for `qmd query` and `qmd vsearch`, `includeHyde` parameter to SDK (`store.search`, `store.expandQuery`) and MCP `query` tool, allowing users to disable generating hypothetical document embeddings during query expansion.
+- Added `typesafe-ai` skill to `.agents/skills/typesafe-ai`.
+
+### Fixed
+
+- Embedding generation and legacy fingerprint adoption now tokenize documents
+  with the store-selected embedding model instead of the global default. This
+  keeps chunk boundaries aligned with the model that creates and verifies the
+  stored vectors without initializing an unrelated provider.
 
 ## [2026.8.23-1] - 2026-08-23
 

package/README.md

@@ -132,7 +132,7 @@ runs in a container and a liveness probe connects from a non-loopback address.
 
 The HTTP server exposes two endpoints:
 - `POST /mcp` — MCP Streamable HTTP (JSON responses, stateless)
-- `POST /query` (alias `/search`) — structured search without the MCP protocol
+- `POST /query` (alias `/search`) — structured search without the MCP protocol. Accepts the same optional `filter` object as the `query` tool (invalid filters return `400`); see [Metadata Filtering](#metadata-filtering)
 - `GET /health` — liveness check with uptime
 
 
@@ -170,8 +170,10 @@ Point any MCP client at `http://localhost:8181/mcp` to connect.
 | `query` | `searches` | array | Typed sub-queries (`lex`/`vec`/`hyde`), 1–10. Mutually exclusive with `query`; exactly one is required. First gets 2x weight. |
 | `query` | `expansion` | string | Plain-query policy: `auto` (default), `force`, or `skip`. Ignored when `searches` is used. |
 | `query` | `collections` | string[] | Filter by collection names (OR). **Array only** — singular `collection` is silently ignored. |
+| `query` | `filter` | object | Metadata filter (recursive `operator`-discriminated JSON AST; see [Metadata Filtering](#metadata-filtering)) |
 | `query` | `expansionContext` | string | Additional context used only to generate `lex` / `vec` / `hyde` query expansions. |
 | `query` | `rerankContext` | string | Additional context used only for reranking and snippet/chunk selection. |
+| `query` | `intent` | string | Disambiguation context (alias for expansionContext & rerankContext; does not search on its own) |
 | `query` | `limit` | number | Max results (default 10) |
 | `query` | `minScore` | number | Minimum relevance 0–1 (default 0) |
 | `query` | `candidateLimit` | number | Max candidates to rerank (default 40) |
@@ -279,6 +281,20 @@ const results3 = await store.search({
 
 // Skip reranking for faster results
 const fast = await store.search({ query: "auth", rerank: false })
+
+// Metadata filter — every returned result satisfies it (also available on
+// searchLex() and searchVector()); results expose indexed metadata via
+// r.metadata. See "Metadata Filtering" for the full grammar.
+const published = await store.search({
+  query: "authentication flow",
+  filter: {
+    operator: "and",
+    operands: [
+      { key: "topics", operator: "all", value: ["typescript"] },
+      { key: "status", operator: "ne", value: "draft" },
+    ],
+  },
+})
 ```
 
 For simple queries, explicit `force` or `skip` overrides `auto`. Under `auto`, CJK
@@ -979,10 +995,10 @@ and `deep-search` (→ `query`).
 --full             # Show full document content
 --line-numbers     # Add line numbers to output
 --explain          # Include retrieval score traces (query, JSON/CLI output)
+--filter <json>    # Metadata filter (recursive JSON AST; see Metadata Filtering)
 --index <name>     # Use named index
 --intent "<text>"  # Legacy CLI alias for rerank context (e.g. "web page load times")
 --no-rerank        # Skip LLM reranking (RRF scores only; faster on CPU)
---no-hyde          # Disable HyDE in query expansion (only lex and vec expansions)
 -C, --candidate-limit <n>  # Max candidates to rerank (default: 40)
 --full-path        # Emit on-disk filesystem paths instead of qmd:// URIs
                    # (a result whose file has moved or been deleted since
@@ -1023,6 +1039,72 @@ explicitly with `-c`.
 > lexical and vector candidate cutoff. Matching candidates from the selected
 > collections are then ranked together.
 
+### Metadata Filtering
+
+Documents can opt into typed metadata through a namespaced frontmatter block. A document without `qmd.metadata` behaves exactly as before, and the frontmatter stays ordinary searchable content (no chunking, embedding, or line-number changes):
+
+```markdown
+---
+qmd:
+  metadata:
+    topics:
+      - typescript
+      - programming
+    status: published
+    priority: 3
+    reviewed: true
+---
+
+# Document body starts here
+```
+
+Supported values are strings, numbers, booleans, and flat homogeneous arrays of one of those. Nested objects, nulls, empty arrays, and mixed-type arrays are rejected (the document still indexes; it is excluded from filtered search until corrected). Metadata keys are user-defined data — `tags`, `topics`, and `labels` are all ordinary keys with no special semantics.
+
+Every search surface (CLI, SDK, MCP, HTTP) accepts the same recursive filter, a JSON AST discriminated by `operator`:
+
+```sh
+# One condition
+qmd search "authentication" \
+  --filter '{"key":"status","operator":"eq","value":"published"}'
+
+# Composed conditions — works with search, vsearch, and query
+qmd query "dependency injection" --filter '{
+  "operator": "and",
+  "operands": [
+    { "key": "topics", "operator": "all", "value": ["typescript", "programming"] },
+    { "key": "status", "operator": "nin", "value": ["draft", "archived"] },
+    { "operator": "or", "operands": [
+      { "key": "priority", "operator": "gte", "value": 3 },
+      { "key": "reviewed", "operator": "eq", "value": true }
+    ] },
+    { "operator": "not", "operand": { "key": "audience", "operator": "eq", "value": "internal" } }
+  ]
+}'
+```
+
+| Node | Shape |
+|------|-------|
+| Logical group | `{ "operator": "and" \| "or", "operands": […] }` |
+| Negation | `{ "operator": "not", "operand": {…} }` |
+| Comparison | `{ "key", "operator": "eq" \| "ne" \| "gt" \| "gte" \| "lt" \| "lte", "value" }` |
+| Membership | `{ "key", "operator": "in" \| "nin" \| "all", "value": […] }` |
+| Presence | `{ "key", "operator": "exists", "value": true \| false }` |
+
+Semantics:
+
+- Matching is typed and exact — no string/number/boolean coercion, and a type mismatch never matches (including `ne` and `nin`).
+- Array-valued metadata is a set: a condition matches when any element satisfies it, `all` requires every filter value to be present.
+- Missing keys do not match `ne`/`nin`; combine with `{ "operator": "exists", "value": false }` in an `or` group to include them.
+- Multiple conditions require an explicit `and` group — there is no implicit AND, and no `$`-prefixed shorthand.
+
+Guarantees and limits:
+
+- Every returned result satisfies the filter, before RRF fusion and reranking.
+- Like collection filtering, highly selective filters are best-effort for top-K completeness: backends over-fetch and post-filter, so a very selective filter can return fewer than `limit` results.
+- Filtered search only considers documents whose metadata has been extracted (run `qmd update` after upgrading; `qmd status` shows the pending count).
+
+JSON output (`--format json`), the SDK, MCP structured results, and the HTTP endpoints include each result's indexed metadata.
+
 ### Output Format
 
 Default output is colorized CLI format (respects `NO_COLOR` env).

package/dist/cli/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "7cbc570",
-  "builtAt": "2026-08-28T11:16:06.495Z"
+  "commit": "5e88f52",
+  "builtAt": "2026-09-25T22:32:39.272Z"
 }

package/dist/cli/qmd.js

@@ -10,6 +10,8 @@ import { parseArgs } from "util";
 import { readFileSync, readdirSync, realpathSync, statSync, existsSync, unlinkSync, writeFileSync, openSync, closeSync, mkdirSync, lstatSync, rmSync, symlinkSync, readlinkSync, copyFileSync } from "fs";
 import { createInterface } from "readline/promises";
 import { getPwd, getRealPath, isPathInsideDir, homedir, resolve, enableProductionMode, searchFTS, extractSnippet, getContextForFile, getContextForPath, listCollections, findSimilarFiles, findDocument, resolveCommaListName, matchFilesByGlob, getHashesNeedingEmbedding, clearAllEmbeddings, insertEmbedding, getStatus, hashContent, extractTitle, formatDocForEmbedding, getEmbeddingFingerprint, chunkDocumentByTokens, clearCache, getCacheKey, getCachedResult, setCachedResult, getIndexHealth, parseVirtualPath, buildVirtualPath, isVirtualPath, isDocid, resolveVirtualPath, toVirtualPath, insertContent, insertDocument, insertDocumentWithContent, findActiveDocument, findOrMigrateLegacyDocument, updateDocumentTitle, updateDocument, updateDocumentWithContent, deactivateDocument, getActiveDocumentPaths, cleanupOrphanedContent, countOrphanedVectors, previewCleanup, runCleanup, getCollectionsWithoutContext, getTopLevelPathsWithoutContext, handelize, escapeLikePattern, hybridQuery, vectorSearchQuery, structuredSearch, addLineNumbers, DEFAULT_EMBED_MODEL, DEFAULT_EMBED_MAX_BATCH_BYTES, DEFAULT_EMBED_MAX_DOCS_PER_BATCH, DEFAULT_RERANK_MODEL, DEFAULT_QUERY_MODEL, DEFAULT_GLOB, splitGlobMask, DEFAULT_MULTI_GET_MAX_BYTES, createStore, getDefaultDbPath, reindexCollection, generateEmbeddings, getPendingEmbeddingDocsReadOnly, syncConfigToDb, } from "../store.js";
+import { syncDocumentMetadata, countDocumentsPendingMetadata } from "../metadata-store.js";
+import { parseMetadataFilter } from "../metadata-filter.js";
 import { disposeDefaultLlamaCpp, getDefaultLlamaCpp, setDefaultLlamaCpp, LlamaCpp, withLLMSession, pullModels, DEFAULT_MODEL_CACHE_DIR, resolveEmbedModel, resolveGenerateModel, resolveRerankModel, resolveModels, inspectGgufFile, isDarwinMetalMitigationActive } from "../llm.js";
 import { rebuildCjkLexicalIndex } from "../search/cjk-index.js";
 import { RemoteLLM } from "../remote-llm.js";
@@ -137,12 +139,16 @@ function getStore() {
     }
     return store;
 }
-function getDoctorStore() {
+function getDoctorStore(options = {}) {
     if (!store) {
         const dbPath = getDbPath();
+        const shouldReconcile = existsSync(dbPath) && options.reconcileConfig !== undefined;
         store = existsSync(dbPath)
-            ? createStore(dbPath, { readOnly: true })
+            ? createStore(dbPath, { readOnly: !shouldReconcile })
             : createStore(":memory:");
+        if (shouldReconcile) {
+            syncConfigToDb(store.db, options.reconcileConfig);
+        }
     }
     return store;
 }
@@ -215,11 +221,16 @@ function mcpDaemonPaths() {
 }
 function setIndexName(name) {
     let normalizedName = name;
-    // Normalize relative paths to prevent malformed database paths
-    if (name && name.includes('/')) {
-        const absolutePath = pathResolve(process.cwd(), name);
-        // Replace path separators with underscores to create a valid filename
-        normalizedName = absolutePath.replace(/\//g, '_').replace(/^_/, '');
+    // Normalize relative paths to prevent malformed database paths. Windows
+    // absolute paths (C:\..., \\server\share) are already absolute -- skip
+    // pathResolve() for those and sanitize `:` and `\` alongside `/`.
+    if (name) {
+        const isWindowsAbsolute = /^[a-zA-Z]:[\\/]/.test(name) || /^\\/.test(name);
+        if (isWindowsAbsolute || /[\\/]/.test(name)) {
+            const absolutePath = isWindowsAbsolute ? name : pathResolve(process.cwd(), name);
+            // Replace path separators with underscores to create a valid filename
+            normalizedName = absolutePath.replace(/[:\\/]+/g, '_').replace(/^_+/, '');
+        }
     }
     currentIndexName = normalizedName || "index";
     storeDbPathOverride = normalizedName ? getDefaultDbPath(normalizedName) : undefined;
@@ -542,6 +553,10 @@ async function showStatus() {
     if (needsEmbedding > 0) {
         console.log(`  ${c.yellow}Pending:  ${needsEmbedding} need embedding${c.reset} (run 'qmd embed')`);
     }
+    const pendingMetadata = countDocumentsPendingMetadata(db);
+    if (pendingMetadata > 0) {
+        console.log(`  ${c.yellow}Metadata: ${pendingMetadata} need extraction${c.reset} (run 'qmd update'; excluded from --filter searches)`);
+    }
     if (mostRecent.latest) {
         const lastUpdate = new Date(mostRecent.latest);
         console.log(`  Updated:  ${formatTimeAgo(lastUpdate)}`);
@@ -950,6 +965,7 @@ async function updateCollections() {
         progress.clear();
         console.log(`\nIndexed: ${result.indexed} new, ${result.updated} updated, ${result.unchanged} unchanged, ${result.removed} removed`);
         reportSkippedReads(result.skippedFiles);
+        reportMetadataErrors(result.metadataErrors);
         if (result.orphanedCleaned > 0) {
             console.log(`Cleaned up ${result.orphanedCleaned} orphaned content hash(es)`);
         }
@@ -1854,7 +1870,7 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
         console.log("No files found matching pattern.");
         // Continue so the deactivation pass can mark previously indexed docs as inactive.
     }
-    let indexed = 0, updated = 0, unchanged = 0, processed = 0;
+    let indexed = 0, updated = 0, unchanged = 0, processed = 0, metadataErrors = 0;
     const skippedFiles = [];
     const seenPaths = new Set();
     // Literal paths of every file in this scan. Passed to the legacy-path
@@ -1892,8 +1908,12 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
         const title = extractTitle(content, relativeFile);
         // Check if document exists (also migrates legacy lowercase paths)
         const existing = findOrMigrateLegacyDocument(db, collectionName, path, livePaths);
+        let documentId;
+        let contentChanged = true;
         if (existing) {
+            documentId = existing.id;
             if (existing.hash === hash) {
+                contentChanged = false;
                 // Hash unchanged, but check if title needs updating
                 if (existing.title !== title) {
                     updateDocumentTitle(db, existing.id, title, now);
@@ -1914,8 +1934,12 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
             // New document - insert content and document
             indexed++;
             const stat = statSync(filepath);
-            insertDocumentWithContent(db, hash, content, now, collectionName, path, title, stat ? new Date(stat.birthtime).toISOString() : now, stat ? new Date(stat.mtime).toISOString() : now);
+            documentId = insertDocumentWithContent(db, hash, content, now, collectionName, path, title, stat ? new Date(stat.birthtime).toISOString() : now, stat ? new Date(stat.mtime).toISOString() : now);
         }
+        // Unchanged content still backfills missing or stale extraction state.
+        const extraction = syncDocumentMetadata(db, documentId, content, path, contentChanged ? undefined : { onlyIfStale: true });
+        if (extraction?.error)
+            metadataErrors++;
         processed++;
         progress.set((processed / total) * 100);
         const elapsed = (Date.now() - startTime) / 1000;
@@ -1941,6 +1965,7 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
     progress.clear();
     console.log(`\nIndexed: ${indexed} new, ${updated} updated, ${unchanged} unchanged, ${removed} removed`);
     reportSkippedReads(skippedFiles);
+    reportMetadataErrors(metadataErrors);
     if (orphanedContent > 0) {
         console.log(`Cleaned up ${orphanedContent} orphaned content hash(es)`);
     }
@@ -1958,6 +1983,11 @@ function fsErrorCode(err) {
     }
     return "ERROR";
 }
+function reportMetadataErrors(metadataErrors) {
+    if (metadataErrors === 0)
+        return;
+    console.warn(`⚠ ${metadataErrors} file(s) have invalid qmd.metadata frontmatter and are excluded from filtered search`);
+}
 function reportSkippedReads(skippedFiles) {
     if (skippedFiles.length === 0)
         return;
@@ -2371,6 +2401,7 @@ function outputResults(results, query, opts) {
                 line: snippetInfo.line,
                 title: row.title,
                 ...(row.context && { context: row.context }),
+                ...(row.metadata && Object.keys(row.metadata).length > 0 && { metadata: row.metadata }),
                 ...(body && { body }),
                 ...(snippet && { snippet }),
                 ...(opts.explain && row.explain && { explain: row.explain }),
@@ -2620,14 +2651,46 @@ export function parseStructuredQuery(query) {
     }
     return typed.length > 0 ? { searches: typed, intent } : null;
 }
+// Parse and validate a --filter JSON string; exits with an actionable
+// message on malformed JSON or an invalid filter AST.
+function parseCliMetadataFilter(rawFilter) {
+    if (rawFilter === undefined)
+        return undefined;
+    let filterJson;
+    try {
+        filterJson = JSON.parse(String(rawFilter));
+    }
+    catch (err) {
+        console.error(`Invalid --filter JSON: ${err instanceof Error ? err.message : String(err)}`);
+        console.error(`Example: --filter '{"key":"status","operator":"eq","value":"published"}'`);
+        process.exit(1);
+    }
+    try {
+        return parseMetadataFilter(filterJson);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+}
+// Filtered search excludes documents without current metadata extraction;
+// tell the user when that makes results incomplete.
+function warnPendingMetadata(db) {
+    const pendingMetadata = countDocumentsPendingMetadata(db);
+    if (pendingMetadata === 0)
+        return;
+    process.stderr.write(`${c.yellow}Warning: ${pendingMetadata} document(s) lack current metadata extraction and are excluded from filtered results. Run 'qmd update'.${c.reset}\n`);
+}
 function search(query, opts) {
     const db = getDb();
     // Validate collection filter (supports multiple -c flags)
     // Use default collections if none specified
     const collectionNames = resolveCollectionFilter(opts.collection, true);
+    if (opts.filter)
+        warnPendingMetadata(db);
     // Use large limit for --all, otherwise fetch more than needed and let outputResults filter
     const fetchLimit = opts.all ? 100000 : Math.max(50, opts.limit * 2);
-    const results = searchFTS(db, query, fetchLimit, collectionNames);
+    const results = searchFTS(db, query, fetchLimit, collectionSearchFilter(collectionNames), opts.filter);
     // Add context to results
     const resultsWithContext = results.map(r => ({
         file: r.filepath,
@@ -2638,6 +2701,7 @@ function search(query, opts) {
         context: getContextForFile(db, r.filepath),
         hash: r.hash,
         docid: r.docid,
+        metadata: r.metadata,
     }));
     closeDb();
     if (resultsWithContext.length === 0) {
@@ -2668,9 +2732,12 @@ async function vectorSearch(query, opts, _model = DEFAULT_EMBED_MODEL) {
     // Use default collections if none specified
     const collectionNames = resolveCollectionFilter(opts.collection, true);
     checkIndexHealth(store.db);
+    if (opts.filter)
+        warnPendingMetadata(store.db);
     await withLLMSession(async () => {
         const results = await vectorSearchQuery(store, query, {
-            collection: collectionNames,
+            collection: collectionSearchFilter(collectionNames),
+            filter: opts.filter,
             limit: opts.all ? 500 : (opts.limit || 10),
             minScore: opts.minScore || 0.3,
             expansionContext: opts.intent,
@@ -2695,6 +2762,7 @@ async function vectorSearch(query, opts, _model = DEFAULT_EMBED_MODEL) {
             score: r.score,
             context: r.context,
             docid: r.docid,
+            metadata: r.metadata,
         })), query, { ...opts, limit: results.length });
     }, { maxDuration: 10 * 60 * 1000, name: 'vectorSearch' });
 }
@@ -2704,6 +2772,8 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
     // Use default collections if none specified
     const collectionNames = resolveCollectionFilter(opts.collection, true);
     checkIndexHealth(store.db);
+    if (opts.filter)
+        warnPendingMetadata(store.db);
     // Check for structured query syntax (lex:/vec:/hyde:/intent: prefixes)
     const parsed = parseStructuredQuery(query);
     // Intent can come from --intent flag or from intent: line in query document
@@ -2731,6 +2801,7 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
             process.stderr.write(`${c.dim}└─ Searching...${c.reset}\n`);
             results = await structuredSearch(store, structuredQueries, {
                 collections: collectionNames.length > 0 ? collectionNames : undefined,
+                filter: opts.filter,
                 limit: opts.all ? 500 : (opts.limit || 10),
                 minScore: opts.minScore || 0,
                 candidateLimit: opts.candidateLimit,
@@ -2760,6 +2831,8 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
             // Standard hybrid query with automatic expansion
             results = await hybridQuery(store, query, {
                 collections: collectionNames.length > 0 ? collectionNames : undefined,
+                collection: collectionSearchFilter(collectionNames),
+                filter: opts.filter,
                 limit: opts.all ? 500 : (opts.limit || 10),
                 minScore: opts.minScore || 0,
                 candidateLimit: opts.candidateLimit,
@@ -2826,6 +2899,7 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
             score: r.score,
             context: r.context,
             docid: r.docid,
+            metadata: r.metadata,
             explain: r.explain,
         })), displayQuery, { ...opts, limit: results.length });
     }, { maxDuration: 10 * 60 * 1000, name: 'querySearch' });
@@ -2862,6 +2936,7 @@ function parseCLI() {
             json: { type: "boolean" },
             explain: { type: "boolean" },
             collection: { type: "string", short: "c", multiple: true }, // Filter by collection(s)
+            filter: { type: "string" }, // Metadata filter (JSON AST) for search/vsearch/query
             // Collection options
             name: { type: "string" }, // collection name
             mask: { type: "string" }, // glob pattern
@@ -3458,6 +3533,8 @@ function showHelp() {
     console.log("  --explain                  - Include retrieval score traces (query, CLI/--format json)");
     console.log("  --format <kind>            - Output format: cli (default) | json | csv | md | xml | files");
     console.log("  -c, --collection <name>    - Filter by one or more collections");
+    console.log("  --filter <json>            - Metadata filter (recursive JSON AST; search/vsearch/query)");
+    console.log("                                e.g. '{\"key\":\"status\",\"operator\":\"eq\",\"value\":\"published\"}'");
     console.log("");
     console.log("Embed/query options:");
     console.log("  --chunk-strategy <auto|regex> - Chunking mode (default: regex; auto uses AST for code files)");
@@ -3916,10 +3993,6 @@ async function runDoctorDeviceChecks(nextSteps) {
     }
 }
 async function showDoctor() {
-    const storeInstance = getDoctorStore();
-    const db = storeInstance.db;
-    const pkg = readPackageJson();
-    const activeModels = resolveModelsForCli();
     let doctorConfig;
     try {
         doctorConfig = loadConfig();
@@ -3928,6 +4001,9 @@ async function showDoctor() {
         // The dedicated index-config check below reports parse errors. Keep the
         // remaining diagnostics available by falling back to DB/default config.
     }
+    const storeInstance = getDoctorStore({ reconcileConfig: doctorConfig });
+    const db = storeInstance.db;
+    const activeModels = resolveModelsForCli();
     const doctorEmbedding = resolveEmbeddingConfig({
         config: doctorConfig,
         dbConfig: readCanonicalEmbeddingConfig(db),
@@ -3938,7 +4014,7 @@ async function showDoctor() {
     const nextSteps = [];
     console.log(`${c.bold}QMD Doctor${c.reset}\n`);
     console.log(`Index: ${getDbPath()}`);
-    console.log(`Runtime: better-sqlite3`);
+    console.log(`Runtime: node:sqlite`);
     try {
         const row = db.prepare(`SELECT sqlite_version() AS version`).get();
         doctorCheck("SQLite runtime", true, row.version);
@@ -3946,8 +4022,7 @@ async function showDoctor() {
     catch (error) {
         doctorCheck("SQLite runtime", false, error instanceof Error ? error.message : String(error));
     }
-    const betterSqliteVersion = pkg.dependencies?.["better-sqlite3"] ?? pkg.devDependencies?.["better-sqlite3"] ?? "not declared";
-    doctorCheck("better-sqlite3 package", true, String(betterSqliteVersion));
+    doctorCheck("node:sqlite", true, process.versions.node);
     try {
         loadSqliteVec(db);
         const row = db.prepare(`SELECT vec_version() AS version`).get();
@@ -4530,6 +4605,7 @@ if (isMain) {
                 console.error("Usage: qmd search [options] <query>");
                 process.exit(1);
             }
+            cli.opts.filter = parseCliMetadataFilter(cli.values.filter);
             search(cli.query, cli.opts);
             break;
         case "vsearch":
@@ -4542,6 +4618,7 @@ if (isMain) {
             if (!cli.values["min-score"]) {
                 cli.opts.minScore = 0.3;
             }
+            cli.opts.filter = parseCliMetadataFilter(cli.values.filter);
             await resolveLocalConfigTrust();
             await vectorSearch(cli.query, cli.opts);
             break;
@@ -4551,6 +4628,7 @@ if (isMain) {
                 console.error("Usage: qmd query [options] <query>");
                 process.exit(1);
             }
+            cli.opts.filter = parseCliMetadataFilter(cli.values.filter);
             await resolveLocalConfigTrust();
             await querySearch(cli.query, cli.opts);
             break;

package/dist/collections.js

@@ -41,11 +41,16 @@ export function setConfigSource(source) {
  * Config file will be ~/.config/qmd/{indexName}.yml
  */
 export function setConfigIndexName(name) {
-    // Resolve relative paths to absolute paths and sanitize for use as filename
-    if (name.includes('/')) {
-        const absolutePath = resolve(process.cwd(), name);
+    // Resolve relative paths to absolute paths and sanitize for use as filename.
+    // Windows absolute paths (C:\..., \\server\share) are already absolute --
+    // skip resolve() for those (POSIX path.resolve doesn't recognize a drive
+    // letter as absolute and would wrongly prefix it with cwd) and sanitize
+    // `:` and `\` alongside `/` so the derived filename is valid on Windows.
+    const isWindowsAbsolute = /^[a-zA-Z]:[\\/]/.test(name) || /^\\/.test(name);
+    if (isWindowsAbsolute || /[\\/]/.test(name)) {
+        const absolutePath = isWindowsAbsolute ? name : resolve(process.cwd(), name);
         // Replace path separators with underscores to create a valid filename
-        currentIndexName = absolutePath.replace(/\//g, '_').replace(/^_/, '');
+        currentIndexName = absolutePath.replace(/[:\\/]+/g, '_').replace(/^_+/, '');
     }
     else {
         currentIndexName = name;

package/dist/db.d.ts

@@ -1,39 +1,26 @@
 /**
  * db.ts - SQLite database connection and extension management
  *
- * Provides Database export and connection management using better-sqlite3
- * and sqlite-vec.
+ * Provides a synchronous node:sqlite connection with QMD's transaction helper
+ * and sqlite-vec extension loading.
  */
-import BetterSqlite3 from "better-sqlite3";
+import { DatabaseSync, type StatementSync } from "node:sqlite";
 export type SQLiteValue = string | number | bigint | Buffer | Uint8Array | Float32Array | null;
 export type SQLiteParams = readonly SQLiteValue[];
-/**
- * Open a SQLite database using better-sqlite3.
- *
- * `better-sqlite3` defaults `busy_timeout` to 0, so concurrent writers throw
- * `SQLITE_BUSY` instead of waiting. WAL improves read-while-write concurrency
- * but does not serialise writers. Setting the timeout at connection open makes
- * parallel processes queue at batch boundaries instead of failing on contact.
- *
- * WAL is enabled here too (with a bounded retry) so connection-level pragmas
- * live in one place and the cold-database journal migration survives concurrent
- * opens.
- *
- * Default 120_000 ms outlasts the worst-case batch commit on a multi-GB
- * index. Override with `QMD_SQLITE_BUSY_TIMEOUT` (value in milliseconds; `0`
- * restores the upstream fail-fast behaviour).
- */
+export type Transaction<TArgs extends unknown[], TResult> = ((...args: TArgs) => TResult) & {
+    deferred: (...args: TArgs) => TResult;
+    immediate: (...args: TArgs) => TResult;
+    exclusive: (...args: TArgs) => TResult;
+};
+/** Synchronous SQLite connection with QMD-compatible transactions. */
+export declare class Database extends DatabaseSync {
+    transaction<TArgs extends unknown[], TResult>(operation: (...args: TArgs) => TResult): Transaction<TArgs, TResult>;
+}
+/** Statement type used throughout QMD. */
+export type Statement<T extends SQLiteParams = SQLiteParams> = StatementSync;
+/** Open a writable QMD database using Node's built-in SQLite runtime. */
 export declare function openDatabase(path: string): Database;
 /** Open an existing database without changing journal mode, schema, or user data. */
 export declare function openReadOnlyDatabase(path: string): Database;
-/**
- * Database and Statement types used throughout QMD.
- */
-export type Database = BetterSqlite3.Database;
-export type Statement<T extends SQLiteParams = SQLiteParams> = BetterSqlite3.Statement<T>;
-/**
- * Load the sqlite-vec extension into a database.
- *
- * Throws with fix instructions when the extension is unavailable.
- */
+/** Load the sqlite-vec extension into a database. */
 export declare function loadSqliteVec(db: Database): void;