@wei840222/qmd 2026.9.6 → 2026.9.27

package/CHANGELOG.md

@@ -2,13 +2,45 @@
 
 ## [Unreleased]
 
+### Fixed
+
+- Metadata extraction error retry: `isDocumentMetadataCurrent` now requires an error-free extraction, allowing `qmd update` to automatically re-attempt extraction on documents that previously failed without requiring manual edits.
+- Non-QMD frontmatter tolerance: Markdown documents whose leading frontmatter has formatting quirks (such as unquoted colons in titles) but does not declare `qmd:` are no longer treated as extraction failures or excluded from filtered search.
+- Relative temporal query expansion bypass and conjunctive lexical dilution: Relative temporal queries (e.g. "昨天", "前天", "yesterday") now bypass the BM25 strong-signal expansion skip, ensuring that archival documents containing relative words cannot preempt target date resolution. In addition, lexical expansion prompts now instruct models to keep search terms minimal without appending generic synonyms (such as "日誌", "行程", "活動") that inadvertently eliminate valid documents under QMD's conjunctive (AND) FTS5 matching.
+
+### Added
+
+- TypeSafe Jev provider (`src/remote-jev.ts`) supporting System One-based candidate reranking via Noul judgments and query expansion intent classification via Choice and Noul gating. Passes query expansion context to Jev state for contextual intent classification.
+- Refactored `HybridLLM` into `Hybrid` (`src/hybrid.ts`) supporting 3-way provider fallback: `RemoteJev` → `RemoteLLM` → `LlamaCpp`.
+- Added `models.jev_api_key`, `models.jev_api_model`, and `models.jev_base_url` configuration options with `TYPESAFE_API_KEY`, `TYPESAFE_DEFAULT_MODEL`, and `TYPESAFE_BASE_URL` environment variable fallbacks.
+- Added TypeSafe Jev provider diagnostic check to `qmd doctor`.
+- Detailed metadata extraction error reporting: `qmd status` and `qmd doctor` now list pending/errored document paths with error hints, and `qmd update` outputs specific files and causes when frontmatter extraction errors occur.
+- Document file path and title metadata in candidate reranking: candidate documents for chat-based and remote rerankers now retain document file paths and titles, enabling rerankers to evaluate provenance and temporal references.
+- Relative temporal resolution in query expansion: `expandQuery` prompts now instruct models to calculate exact ISO dates from relative time expressions (e.g. "yesterday", "昨天", "today", "last week") against current local time for lexical and vector search.
+- Added file, title, and current local time to TypeSafe Jev candidate reranking and intent classification states, with temporal constraint guidance.
+- Search intent playbook and guidance for query expansion: Added `JEV_STRATEGY_PLAYBOOK` mapping Jev intent classifications (`code_search`, `concept_search`, `factual_lookup`, `broad_exploration`) to concrete lexical and vector search guidance passed to downstream expansion LLMs in dedicated `<search_intent>` XML blocks, keeping untrusted context separate.
+
+## [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,6 +995,7 @@ 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)
@@ -1022,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": "672da2e",
-  "builtAt": "2026-09-06T06:45:32.394Z"
+  "commit": "ffd0c56",
+  "builtAt": "2026-09-27T09:25:17.053Z"
 }

package/dist/cli/qmd.js

@@ -10,10 +10,13 @@ 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, getDocumentsPendingMetadata } 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";
-import { HybridLLM } from "../hybrid-llm.js";
+import { Hybrid } from "../hybrid.js";
+import { RemoteJev } from "../remote-jev.js";
 import { EmbeddingConfigError, OPENAI_EMBEDDING_MODEL, readCanonicalEmbeddingConfig, resolveEmbeddingConfig, writeCanonicalEmbeddingConfig, } from "../embedding/config.js";
 import { OpenAIEmbeddingProvider, UnavailableOpenAIEmbeddingProvider, } from "../embedding/openai.js";
 import { createCliEmbeddingProviderOwner } from "./embedding-owner.js";
@@ -131,8 +134,19 @@ function getStore() {
                 rerankApiKey: config?.models?.rerank_api_key,
             })
             : undefined;
+        const jevApiKey = config?.models?.jev_api_key?.trim() || process.env.TYPESAFE_API_KEY?.trim();
+        const jevBaseUrl = config?.models?.jev_base_url?.trim() || process.env.TYPESAFE_BASE_URL?.trim();
+        const jevModel = config?.models?.jev_api_model?.trim() || process.env.TYPESAFE_DEFAULT_MODEL?.trim() || "jev-1.13";
+        const remoteJev = jevApiKey
+            ? new RemoteJev({
+                apiKey: jevApiKey,
+                baseUrl: jevBaseUrl,
+                model: jevModel,
+                timeoutMs: 30000,
+            })
+            : undefined;
         if (cliLlama) {
-            store.llm = remoteLlm ? new HybridLLM(cliLlama, remoteLlm) : cliLlama;
+            store.llm = (remoteLlm || remoteJev) ? new Hybrid(cliLlama, remoteLlm, remoteJev) : cliLlama;
         }
     }
     return store;
@@ -219,11 +233,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;
@@ -546,6 +565,18 @@ 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)`);
+        const pendingDocs = getDocumentsPendingMetadata(db, 3);
+        for (const doc of pendingDocs) {
+            const errHint = doc.error ? `: ${doc.error.split("\n")[0]}` : "";
+            console.log(`    ${c.dim}• qmd://${doc.collection}/${doc.path}${errHint}${c.reset}`);
+        }
+        if (pendingMetadata > pendingDocs.length) {
+            console.log(`    ${c.dim}... and ${pendingMetadata - pendingDocs.length} more${c.reset}`);
+        }
+    }
     if (mostRecent.latest) {
         const lastUpdate = new Date(mostRecent.latest);
         console.log(`  Updated:  ${formatTimeAgo(lastUpdate)}`);
@@ -954,6 +985,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, result.metadataErrorFiles);
         if (result.orphanedCleaned > 0) {
             console.log(`Cleaned up ${result.orphanedCleaned} orphaned content hash(es)`);
         }
@@ -1858,8 +1890,9 @@ 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 metadataErrorFiles = [];
     const seenPaths = new Set();
     // Literal paths of every file in this scan. Passed to the legacy-path
     // migration so it never adopts a row that still belongs to a live file.
@@ -1896,8 +1929,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);
@@ -1918,7 +1955,13 @@ 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++;
+            metadataErrorFiles.push({ file: relativeFile, error: extraction.error });
         }
         processed++;
         progress.set((processed / total) * 100);
@@ -1945,6 +1988,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, metadataErrorFiles);
     if (orphanedContent > 0) {
         console.log(`Cleaned up ${orphanedContent} orphaned content hash(es)`);
     }
@@ -1962,6 +2006,20 @@ function fsErrorCode(err) {
     }
     return "ERROR";
 }
+function reportMetadataErrors(metadataErrors, errorFiles) {
+    if (metadataErrors === 0)
+        return;
+    console.warn(`⚠ ${metadataErrors} file(s) have invalid qmd.metadata frontmatter and are excluded from filtered search`);
+    if (errorFiles && errorFiles.length > 0) {
+        const displayFiles = errorFiles.slice(0, 5);
+        for (const errFile of displayFiles) {
+            console.warn(`  • ${errFile.file}: ${errFile.error}`);
+        }
+        if (errorFiles.length > displayFiles.length) {
+            console.warn(`  ...and ${errorFiles.length - displayFiles.length} more`);
+        }
+    }
+}
 function reportSkippedReads(skippedFiles) {
     if (skippedFiles.length === 0)
         return;
@@ -2375,6 +2433,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 }),
@@ -2624,14 +2683,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,
@@ -2642,6 +2733,7 @@ function search(query, opts) {
         context: getContextForFile(db, r.filepath),
         hash: r.hash,
         docid: r.docid,
+        metadata: r.metadata,
     }));
     closeDb();
     if (resultsWithContext.length === 0) {
@@ -2672,9 +2764,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,
@@ -2699,6 +2794,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' });
 }
@@ -2708,6 +2804,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
@@ -2735,6 +2833,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,
@@ -2764,6 +2863,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,
@@ -2830,6 +2931,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' });
@@ -2866,6 +2968,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
@@ -3462,6 +3565,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)");
@@ -4030,6 +4135,12 @@ async function showDoctor() {
         const rerankModel = configModels.rerank_api_model ?? activeModels.rerank;
         doctorCheck("reranking model", true, `${rerankModel} (endpoint: ${rerankEndpoint})`);
     }
+    const isJevConfigured = Boolean(configModels?.jev_api_key || process.env.TYPESAFE_API_KEY);
+    if (isJevConfigured) {
+        const jevModel = configModels?.jev_api_model ?? process.env.TYPESAFE_DEFAULT_MODEL ?? "jev-1.13";
+        const jevEndpoint = configModels?.jev_base_url ?? process.env.TYPESAFE_BASE_URL ?? "https://api.typesafe.ai";
+        doctorCheck("typesafe jev", true, `${jevModel} (endpoint: ${jevEndpoint})`);
+    }
     await runDoctorDeviceChecks(nextSteps);
     const diagnostics = inspectIndexDiagnostics(db, {
         fallbackModel: embedModel,
@@ -4070,6 +4181,22 @@ async function showDoctor() {
     catch (error) {
         doctorCheck("embedding freshness", false, error instanceof Error ? error.message : String(error));
     }
+    try {
+        const pendingMetadata = countDocumentsPendingMetadata(db);
+        if (pendingMetadata === 0) {
+            doctorCheck("metadata extraction", true, "all active documents have current metadata");
+        }
+        else {
+            const pendingDocs = getDocumentsPendingMetadata(db, 3);
+            const fileHints = pendingDocs.map(d => `${d.collection}/${d.path}`).join(", ");
+            const extraHint = pendingMetadata > pendingDocs.length ? ` and ${pendingMetadata - pendingDocs.length} more` : "";
+            doctorCheck("metadata extraction", false, `${formatCount(pendingMetadata)} active ${pendingMetadata === 1 ? "document lacks" : "documents lack"} valid metadata (${fileHints}${extraHint}). Next: \`qmd update\``);
+            nextSteps.push(`Inspect and fix frontmatter in ${formatCount(pendingMetadata)} documents, then run \`qmd update\`.`);
+        }
+    }
+    catch (error) {
+        doctorCheck("metadata extraction", false, error instanceof Error ? error.message : String(error));
+    }
     try {
         const rows = db.prepare(`
       SELECT model, embed_fingerprint AS fingerprint, COUNT(DISTINCT hash) AS docs, COUNT(*) AS chunks
@@ -4532,6 +4659,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":
@@ -4544,6 +4672,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;
@@ -4553,6 +4682,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.d.ts

@@ -44,6 +44,9 @@ export interface ModelsConfig {
     rerank_api_url?: string;
     rerank_api_model?: string;
     rerank_api_key?: string;
+    jev_api_key?: string;
+    jev_api_model?: string;
+    jev_base_url?: string;
 }
 /**
  * The complete configuration file structure

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/{hybrid-llm.d.ts → hybrid.d.ts}

@@ -1,9 +1,14 @@
-import type { LLM, EmbedOptions, EmbeddingResult, GenerateOptions, GenerateResult, ModelInfo, Queryable, RerankDocument, RerankOptions, RerankResult } from "./llm.js";
+import type { LLM, EmbedOptions, EmbeddingResult, GenerateOptions, GenerateResult, ModelInfo, Queryable, RerankDocument, RerankOptions, RerankResult, SearchIntentGuidance } from "./llm.js";
 import type { RemoteLLM } from "./remote-llm.js";
-export declare class HybridLLM implements LLM {
+import type { RemoteJev } from "./remote-jev.js";
+export declare class Hybrid implements LLM {
     private readonly localLLM;
     private readonly remoteLLM?;
-    constructor(localLLM: LLM, remoteLLM?: RemoteLLM | undefined);
+    private readonly remoteJev?;
+    constructor(localLLM: LLM, remoteLLM?: RemoteLLM | undefined, remoteJev?: RemoteJev | undefined);
+    get jev(): RemoteJev | undefined;
+    get remote(): RemoteLLM | undefined;
+    get local(): LLM;
     get supportsExpand(): boolean;
     get supportsRerank(): boolean;
     embed(text: string, options?: EmbedOptions): Promise<EmbeddingResult | null>;
@@ -13,6 +18,7 @@ export declare class HybridLLM implements LLM {
         context?: string;
         includeLexical?: boolean;
         includeHyde?: boolean;
+        searchIntent?: SearchIntentGuidance;
     }): Promise<Queryable[]>;
     rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult>;
     dispose(): Promise<void>;