@wei840222/qmd 2026.8.23 → 2026.8.24

package/CHANGELOG.md

@@ -2,32 +2,68 @@
 
 ## [Unreleased]
 
+## [2026.8.23-1] - 2026-08-23
+
 ### Added
 
-- Added Oxlint lint fence.
-- Added a bundled Traditional Chinese Jieba dictionary that deterministically
-  combines the node-rs base dictionary, APCLab's Taiwan dictionary, and
-  zhtw-mcp technical terms. `pnpm dict:sync` verifies pinned source hashes;
-  `pnpm dict:sync --update-pins` refreshes the upstream pins.
-- Added CJK-aware lexical retrieval with independent character, Jieba word, and
-  bigram FTS5 channels, versioned rank fusion and explain traces. The bundled
-  reviewed Traditional Chinese technical dictionary records its pinned source
-  and MIT attribution in `THIRD_PARTY_NOTICES.md`.
-- Added typed local/OpenAI embedding providers, provider-qualified vector
-  identities, resumable chunk persistence, build leases, remote preflight and
-  acknowledgement, request-purpose guards, safe OpenAI errors, and additive
-  diagnostics in CLI, SDK, and MCP. Local embedding remains the default.
-- Added `OPENAI_BASE_URL` for routing OpenAI-compatible embedding requests
-  through a self-hosted proxy while retaining the existing remote-consent flow.
-- Added the native `@node-rs/jieba` dependency and package smoke coverage for its
-  Node/Bun runtime loading and packaged dictionary data.
+- **Pure Node.js + pnpm Standardized Toolchain**: Completely standardized the project on
+  Node.js (>=22) and pnpm (`pnpm@11.15.1`). Removed all Bun-specific runtime abstractions,
+  lockfile heuristics, and dual-runtime test preloads.
+- **Oxlint & Code Quality Fences**: Added Oxlint static analysis rules (`oxlint`) and anti-slop
+  guardrails across the codebase.
+- **CJK 3-Way Lexical Retrieval**: Added CJK-aware lexical retrieval with independent character,
+  Jieba word, and bigram FTS5 shadow channels, versioned reciprocal rank fusion (RRF), and
+  explain traces.
+- **Bundled Traditional Chinese Jieba Dictionary**: Added a bundled Traditional Chinese dictionary
+  deterministically combining `@node-rs/jieba` (`2.0.2`), APCLab's Taiwan dictionary, and
+  `sysprog21/zhtw-mcp` technical terms. Pinned sources and hashes are recorded in
+  `src/search/zh-dict.sources.json` and `THIRD_PARTY_NOTICES.md`.
+- **Custom User Dictionary Support**: Added `user_dict` configuration supporting custom
+  user dictionaries with automatic analyzer fingerprint updates.
+- **Typed Remote OpenAI-Compatible Embedding Provider**: Added typed `OpenAIEmbeddingProvider`,
+  provider-qualified vector identities, resumable chunk persistence, build leases, remote
+  preflight, chunk byte budgeting, and safe OpenAI error handling.
+- **Remote LLM Query Expansion & Chat Reranking**: Supported OpenAI-compatible
+  `/v1/chat/completions` API endpoints for remote query expansion and reranking with XML-structured
+  prompts and current timestamp injection.
+- **Vector Table Collection Column**: Added `collection` column to vector indexes with automatic
+  schema migration and collection-scoped filtering.
+- **Single-Item Batch Embedding Fallback**: Added single-item fallback to gracefully handle and
+  recover from oversized batch chunks during embedding and vector repair.
+- **Agent Skill Query Syntax Reference**: Added `skills/qmd/references/query-syntax.md` detailing
+  formal EBNF grammar, search operators, and structured MCP JSON payloads, linked directly from
+  `skills/qmd/SKILL.md`.
+- **Automated Jules PR Code Reviews**: Integrated Google Jules PR review GitHub Actions workflow
+  (`.github/workflows/jules-pr-review.yml`) with automatic `git diff` fallback for large diffs (>20k lines).
+- **Trivy Vulnerability Scanner & Fast CI Checks**: Integrated Trivy filesystem and dependency security
+  scanner, TypeScript type checking (`pnpm run test:types`), and Tree-sitter WASM grammars smoke
+  (`pnpm run smoke:package-grammars`) in `.github/workflows/ci.yml`.
 
 ### Changed
 
-- Chat-completions reranking now prioritizes explicit query constraints such as
-  entities, locations, versions, time, and negations. Valid empty rerank results
-  no longer fall back to neutral scores, and parsed chat rerank output is sorted
-  by descending relevance score.
+- **Runtime Standardization & Bun Deprecation**: Standardized database layer on `better-sqlite3`
+  and `sqlite-vec`. Streamlined `bin/qmd` launcher to a pure Node.js / `tsx` trampoline.
+  Replaced all `bun` / `bunx` scripts with `node`, `pnpm`, `tsx`, and `npx`.
+- **Unified `models` Configuration Block**: Replaced disjointed embedding and expand configurations
+  with a unified `models:` configuration block supporting `embed`, `generate`, and `rerank`
+  endpoints/models.
+- **Generic MCP Client Documentation**: Generalized MCP server configuration instructions across
+  `README.md` and `skills/qmd/references/mcp-setup.md` to support all MCP-compatible clients
+  (Cursor, Claude Desktop, Zed, OpenClaw, etc.).
+- **Standardized Multi-Holder MIT License**: Updated `LICENSE` to the standard multi-holder copyright
+  formatting (Tobi Lutke and Wan, Jiun Wei) for full compatibility with automated license scanners.
+- **Test Suite Semver Suffix Support**: Updated CLI `--version` test in `test/esm-ambiguous-module.test.ts`
+  to support Semver prerelease/build suffixes (e.g. `2026.8.23-1`).
+- **Remote LLM Prompt Architecture & Hardening**: Remote query expansion and chat-completions
+  reranking now use consistent XML prompt structures, escape untrusted prompt data, preserve
+  cross-language technical terms, and discard low-confidence chat rerank scores below `0.1`.
+- **Direct Remote Authorization**: Streamlined remote embedding and execution by removing
+  legacy interactive remote consent prompts while enforcing strict identity fingerprinting.
+- **Database Performance Optimizations**: Skipped redundant database write transactions when
+  configuration state remains unchanged.
+- **Dependency Upgrades**: Upgraded `@node-rs/jieba` to `2.0.2` and updated package scope to
+  `@wei840222/qmd`.
+
 - Remote query expansion and chat-completions reranking now use a consistent
   Gemini-style XML prompt structure in both system and user messages, separating
   role, instructions, constraints, output format, context, task, and final
@@ -102,6 +138,18 @@
   reopen, keep CLI update/include settings synchronized, and use atomic durable
   YAML replacement.
 
+### Removed
+
+- Removed Nix flake configurations (`flake.nix`, `flake.lock`) and related CI jobs.
+- Removed `bun.lock`, `src/test-preload.ts`, and `test/launcher-detection.test.sh`.
+- Removed legacy interactive remote embedding consent workflows in favor of direct configuration-based authorization.
+
+### Security
+
+- Added Trivy filesystem and dependency security scanning in CI workflows.
+- Bound MCP HTTP server explicitly to `127.0.0.1`.
+- Sanitized remote LLM error handling to prevent leaking credentials or headers.
+
 ### Compatibility
 
 - `vectors_vec` still supports one embedding dimension at a time. Switching

package/LICENSE

@@ -1,29 +1,6 @@
 MIT License
 
 Copyright (c) 2024-2026 Tobi Lutke
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
----
-
-MIT License
-
 Copyright (c) 2026 Wan, Jiun Wei
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

package/README.md

@@ -28,14 +28,13 @@ You can read more about QMD's progress in the [CHANGELOG](CHANGELOG.md).
 ## Quick Start (Local Embedding Default)
 
 ```sh
-# Install globally (Node or Bun)
+# Install globally
 npm install -g @wei840222/qmd
 # or
-bun install -g @wei840222/qmd
+pnpm add -g @wei840222/qmd
 
 # Or run directly
 npx @wei840222/qmd ...
-bunx @wei840222/qmd ...
 
 # Create collections for your notes, docs, and meeting transcripts
 qmd collection add ~/notes --name notes
@@ -96,27 +95,9 @@ Although the tool works perfectly fine when you just tell your agent to use it o
 - `multi_get` — Batch retrieve by glob pattern, comma-separated list, or docids
 - `status` — Index health and collection info
 
-**Claude Desktop configuration** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+#### Stdio Transport (Default)
 
-```json
-{
-  "mcpServers": {
-    "qmd": {
-      "command": "qmd",
-      "args": ["mcp"]
-    }
-  }
-}
-```
-
-**Claude Code** — Install the plugin (recommended):
-
-```bash
-claude plugin marketplace add tobi/qmd
-claude plugin install qmd@qmd
-```
-
-Or configure MCP manually in `~/.claude/settings.json`:
+Add QMD to your MCP client configuration (e.g. Cursor, Claude Desktop, Zed, or other MCP-compatible clients):
 
 ```json
 {
@@ -211,7 +192,7 @@ results seem unscoped. The HTTP `/query` and `/search` endpoints return
 
 ### SDK / Library Usage
 
-Use QMD as a library in your own Node.js or Bun applications.
+Use QMD as a library in your own Node.js applications.
 
 #### Installation
 
@@ -552,7 +533,6 @@ The `query` command uses **Reciprocal Rank Fusion (RRF)** with position-aware bl
 ### System Requirements
 
 - **Node.js** >= 22
-- **Bun** >= 1.0.0
 - **macOS**: Homebrew SQLite (for extension support)
   ```sh
   brew install sqlite
@@ -729,16 +709,16 @@ Review the resulting pin and dictionary diff before committing an update.
 ```sh
 npm install -g @wei840222/qmd
 # or
-bun install -g @wei840222/qmd
+pnpm add -g @wei840222/qmd
 ```
 
 ### Development
 
 ```sh
-git clone https://github.com/tobi/qmd
+git clone https://github.com/wei840222/qmd
 cd qmd
-bun install
-bun link
+pnpm install
+npm link
 ```
 
 ## Usage
@@ -811,7 +791,7 @@ opt in. Run `qmd status` to verify which grammars are available.
 
 > **Note:** Tree-sitter grammars are optional dependencies. If they are not
 > installed, `--chunk-strategy auto` falls back to regex-only chunking
-> automatically. Tested on both Node.js and Bun.
+> automatically.
 
 ### Context Management
 

package/THIRD_PARTY_NOTICES.md

@@ -4,9 +4,9 @@
 
 The bundled Traditional Chinese Jieba dictionary combines the following MIT-licensed sources:
 
-- `@node-rs/jieba` 2.0.1 (`dict.txt`), Copyright (c) LongYinan.
+- `@node-rs/jieba` 2.0.2 (`dict.txt`), Copyright (c) LongYinan.
 - `APCLab/jieba-tw` (`jieba/dict.txt`) at commit `2bd4c0913cdadc865879b21a00c78e28ef1ba2c5`, Copyright (c) 2013 Sun Junyi.
-- `sysprog21/zhtw-mcp` (`assets/ruleset.json`) at commit `2e0f4e4912a8ffdacf7fa3a155cb20c29cba043b`, Copyright (c) 2026 National Cheng Kung University, Taiwan.
+- `sysprog21/zhtw-mcp` (`assets/ruleset.json`) at commit `40e669a769bfcafc5f21f9ca6e2f5152b54c8831`, Copyright (c) 2026 National Cheng Kung University, Taiwan.
 
 The source pins and content fingerprints are recorded in `src/search/zh-dict.sources.json` in the qmd source distribution. qmd has no runtime source dependency on these upstream repositories.
 

package/bin/qmd

@@ -1,19 +1,16 @@
 #!/usr/bin/env node
-// 2>/dev/null; if command -v node >/dev/null 2>&1; then exec node "$0" "$@"; else exec bun "$0" "$@"; fi
+// 2>/dev/null; exec node "$0" "$@"
 // Cross-platform launcher for qmd.
 //
-// Previously this was a POSIX shell script with `#!/bin/sh`, which meant npm
-// on Windows generated shims that tried to route through `/bin/sh` — a path
-// that doesn't exist on Windows, so `qmd` failed immediately after a global
-// install. Rewriting the launcher in Node.js lets npm generate native
+// Rewriting the launcher in Node.js lets npm/pnpm generate native
 // cmd/ps1/sh shims that invoke `node` directly on every platform.
 
-import { spawn, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-// Resolve symlinks so global installs (npm link / npm install -g) can find
+// Resolve symlinks so global installs (npm link / npm install -g / pnpm add -g) can find
 // the actual package directory instead of the global bin directory.
 const self = realpathSync(fileURLToPath(import.meta.url));
 const pkgDir = resolve(dirname(self), "..");
@@ -22,7 +19,7 @@ const tsEntry = resolve(pkgDir, "src/cli/qmd.ts");
 
 // MCP stdio reserves stdout exclusively for JSON-RPC frames. node-llama-cpp
 // / llama.cpp / ggml can write native logs directly to stdout before JS-level
-// log handlers are attached, so seed the native quiet env before Node/Bun imports
+// log handlers are attached, so seed the native quiet env before Node imports
 // the CLI and its LLM modules. Preserve explicit user values when provided.
 if (process.argv[2] === "mcp") {
   process.env.LLAMA_LOG_LEVEL = process.env.LLAMA_LOG_LEVEL || "error";
@@ -36,145 +33,49 @@ if (process.argv[2] === "mcp") {
 // residency set is empty (ggml-org/llama.cpp#22593); the keep_alive hasn't
 // expired by exit, so the assertion fails and ggml_abort dumps a multi-kB
 // stack trace to stderr even when the user-visible results were already
-// emitted correctly. No JS-side dispose can prevent it because the static
-// destructor runs in __cxa_finalize_ranges, after every JS-reachable cleanup.
+// emitted correctly.
 //
 // For QMD's short-lived CLI workflow, residency sets provide no observable
-// performance benefit (subsequent requests don't reuse the warm mapping —
-// measured: identical wall time with and without on M3 Pro), so disable them
-// by default on darwin. The env var must be set BEFORE the native llama.cpp
-// binding loads, which is why it lives here in the launcher rather than in
-// the JS entry point. Opt back in with QMD_METAL_KEEP_RESIDENCY=1 if you
-// run long-lived qmd processes (the MCP daemon may benefit on hot reload)
-// or are triaging an upstream Metal teardown fix.
+// performance benefit, so disable them by default on darwin.
 if (process.platform === "darwin" && process.env.QMD_METAL_KEEP_RESIDENCY !== "1") {
   process.env.GGML_METAL_NO_RESIDENCY = process.env.GGML_METAL_NO_RESIDENCY || "1";
 }
 
-function hasBun() {
-  try {
-    const res = spawnSync("bun", ["--version"], { stdio: "ignore", shell: process.platform === "win32" });
-    return res.status === 0;
-  } catch {
-    return false;
-  }
-}
-
 // In published packages, bin/qmd must run dist/. In a git checkout, however,
 // dist/ is often ignored and can be stale after git reset or branch switches.
 // Prefer source mode only for checkouts so ./bin/qmd reflects the checked-out
 // source without changing packaged/runtime behavior.
-//
-// Critical: source-mode detection must NOT trigger when a package manager
-// installed us. `pnpm install -g .` (and `npm install -g .`) copy the entire
-// working tree — including .git/, bun.lock, package-lock.json, src/, and even
-// node_modules/ — into <prefix>/node_modules/@tobilu/qmd/, so .git and a
-// lockfile being present is not a reliable "this is a working tree" signal.
-// What IS reliable: a package-manager install always lands the package
-// directory inside a `node_modules/` segment; a bare working-tree checkout
-// (with `bun link` or a direct path invocation) does not. Gate source mode
-// on that. Allow QMD_SOURCE_MODE=1 / =0 as an explicit override for the
-// rare case where the heuristic disagrees with the user.
 const sourceOverride = process.env.QMD_SOURCE_MODE;
 const looksInstalled = pkgDir.split("/").includes("node_modules");
 const sourceAllowed = sourceOverride === "1"
   || (sourceOverride !== "0" && !looksInstalled);
 
 let useSourceMode = false;
-let sourceRunner = null;
-let sourceArgs = [];
+let runnerArgs = [];
 
 if (sourceAllowed && existsSync(resolve(pkgDir, ".git")) && existsSync(tsEntry)) {
-  // Lockfile-driven runner selection — mirror the dist-mode logic below so
-  // source mode picks the same runtime the user's deps were installed for.
-  // package-lock.json wins over bun.lock when both are present: pnpm/npm
-  // installs ship the Node-ABI native modules (better-sqlite3, sqlite-vec),
-  // and running Bun against them produces ABI mismatches. This also fixes
-  // pnpm-global installs, which copy the whole working tree — including .git
-  // and bun.lock — into the install dir and used to route through Bun even
-  // when the user installed via npm/pnpm.
-  const hasNpmLock = existsSync(resolve(pkgDir, "package-lock.json"));
-  const hasBunLock = existsSync(resolve(pkgDir, "bun.lock")) || existsSync(resolve(pkgDir, "bun.lockb"));
   const tsxEntry = resolve(pkgDir, "node_modules/tsx/dist/cli.mjs");
-  const tsxAvailable = existsSync(tsxEntry);
-
-  if (hasNpmLock && tsxAvailable) {
-    useSourceMode = true;
-    sourceRunner = "node";
-    sourceArgs = [tsxEntry, tsEntry, ...process.argv.slice(2)];
-  } else if (hasBunLock && hasBun()) {
+  if (existsSync(tsxEntry)) {
     useSourceMode = true;
-    sourceRunner = "bun";
-    sourceArgs = [tsEntry, ...process.argv.slice(2)];
-  } else if (tsxAvailable) {
-    useSourceMode = true;
-    sourceRunner = "node";
-    sourceArgs = [tsxEntry, tsEntry, ...process.argv.slice(2)];
+    runnerArgs = [tsxEntry, tsEntry, ...process.argv.slice(2)];
   }
 }
 
 if (!useSourceMode && !existsSync(jsEntry)) {
   console.error(`qmd is not built: missing ${jsEntry}`);
-  console.error("Run: bun install && bun run build");
+  console.error("Run: pnpm install && pnpm run build");
   console.error("Or:  npm install && npm run build");
   console.error("After building, run: qmd doctor");
   process.exit(1);
 }
 
-// Detect the package manager that installed dependencies by checking lockfiles.
-// $BUN_INSTALL is intentionally NOT checked — it only indicates that bun exists
-// on the system, not that it was used to install this package (see #361).
-//
-// package-lock.json takes priority: if it exists, npm installed the native
-// modules for Node. The repo ships bun.lock, so without this check, source
-// builds that use npm would be incorrectly routed to bun, causing ABI
-// mismatches with better-sqlite3 / sqlite-vec (see #381).
-//
-// Package-manager installs keep their lockfile at the install root, above
-// node_modules/ — never inside the package directory itself. A bun global
-// install writes $BUN_INSTALL/install/global/bun.lock while the package
-// lands in .../install/global/node_modules/@tobilu/qmd/, so the package-dir
-// checks below can't match and qmd would run under whatever node is first
-// on PATH. The native modules were built by the installing runtime; after
-// the next Node major upgrade they fail to load (ERR_DLOPEN_FAILED,
-// NODE_MODULE_VERSION mismatch). Apply the same npm-priority rule at the
-// install root when the package directory itself has no lockfile.
-const pathParts = pkgDir.split(sep);
-const nodeModulesIndex = pathParts.lastIndexOf("node_modules");
-const installRoot = nodeModulesIndex === -1 ? null : pathParts.slice(0, nodeModulesIndex).join(sep);
-const hasRootNpmLock = installRoot !== null && existsSync(resolve(installRoot, "package-lock.json"));
-const hasRootBunLock = installRoot !== null
-  && (existsSync(resolve(installRoot, "bun.lock")) || existsSync(resolve(installRoot, "bun.lockb")));
-
-let runnerName = "node";
-if (existsSync(resolve(pkgDir, "package-lock.json"))) {
-  runnerName = "node";
-} else if (existsSync(resolve(pkgDir, "bun.lock")) || existsSync(resolve(pkgDir, "bun.lockb"))) {
-  runnerName = "bun";
-} else if (hasRootNpmLock) {
-  runnerName = "node";
-} else if (hasRootBunLock) {
-  runnerName = "bun";
-} else {
-  runnerName = "node";
-}
-
-const selected = useSourceMode ? sourceRunner : (runnerName === "node" ? "node" : "bun");
 // Pin Node to the binary that launched this trampoline. Native addons
-// (better-sqlite3) are compiled for that install's ABI; spawning PATH
-// `node` picks up nvm/fnm/mise shims in the project directory and fails
-// with NODE_MODULE_VERSION / ERR_DLOPEN_FAILED (leftover from #577; #319).
-// If the trampoline itself is running under bun (`bun bin/qmd`), keep
-// PATH `node` so we don't load Node-ABI addons into bun.
-const runner = selected === "node" && typeof process.versions.bun !== "string"
-  ? process.execPath
-  : selected;
-const args = useSourceMode ? sourceArgs : [jsEntry, ...process.argv.slice(2)];
-const needsShell = (runner === "bun") && process.platform === "win32";
+// (better-sqlite3) are compiled for that install's ABI.
+const runner = process.execPath;
+const args = useSourceMode ? runnerArgs : [jsEntry, ...process.argv.slice(2)];
 
 const child = spawn(runner, args, {
   stdio: "inherit",
-  shell: needsShell,
 });
 
 child.on("exit", (code, signal) => {
@@ -186,7 +87,6 @@ child.on("exit", (code, signal) => {
 });
 
 child.on("error", (err) => {
-  const name = useSourceMode ? sourceRunner : runnerName;
-  console.error(`qmd: failed to launch ${name}: ${err.message}`);
+  console.error(`qmd: failed to launch node: ${err.message}`);
   process.exit(1);
 });

package/dist/ast.js

@@ -58,7 +58,7 @@ export function formatGrammarLoadError(language, err) {
     const grammar = GRAMMAR_MAP[language];
     const detail = err instanceof Error ? err.message : String(err);
     return `${grammar.pkg}/${grammar.wasm} failed to load (${detail}); falling back to regex chunking. ` +
-        `Repair a broken global install with: bun add ${grammar.pkg}@${grammar.version}`;
+        `Repair a broken global install with: pnpm add ${grammar.pkg}@${grammar.version}`;
 }
 // =============================================================================
 // Per-Language Query Definitions

package/dist/cli/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "f7e2cfc",
-  "builtAt": "2026-08-23T03:21:48.505Z"
+  "commit": "1e728bc",
+  "builtAt": "2026-08-23T06:13:30.733Z"
 }

package/dist/cli/qmd.d.ts

@@ -37,7 +37,7 @@ type FinishSuccessfulCliCommandOptions = {
  * order, and the process exits cleanly. The `GGML_METAL_NO_RESIDENCY=1` env
  * var that `bin/qmd` exports is a defense-in-depth safety net for paths
  * that still call `process.exit()` after loading the native binding
- * (signal handlers, error paths, `bun test`).
+ * (signal handlers, error paths, test runners).
  *
  * If the caller passes an explicit `exit` for testability, we honor it —
  * the lifecycle tests verify the legacy flush → cleanup → exit ordering.

package/dist/cli/qmd.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { isBun, openDatabase, loadSqliteVec } from "../db.js";
+import { openDatabase, loadSqliteVec } from "../db.js";
 import fastGlob from "fast-glob";
 import { spawn as nodeSpawn } from "child_process";
 import { isQmdMcpPid, mcpDaemonStateFiles } from "./mcp-pid.js";
@@ -270,7 +270,7 @@ async function flushWritable(stream) {
  * order, and the process exits cleanly. The `GGML_METAL_NO_RESIDENCY=1` env
  * var that `bin/qmd` exports is a defense-in-depth safety net for paths
  * that still call `process.exit()` after loading the native binding
- * (signal handlers, error paths, `bun test`).
+ * (signal handlers, error paths, test runners).
  *
  * If the caller passes an explicit `exit` for testability, we honor it —
  * the lifecycle tests verify the legacy flush → cleanup → exit ordering.
@@ -3933,7 +3933,7 @@ async function showDoctor() {
     const nextSteps = [];
     console.log(`${c.bold}QMD Doctor${c.reset}\n`);
     console.log(`Index: ${getDbPath()}`);
-    console.log(`Runtime: ${isBun ? "bun:sqlite" : "better-sqlite3"}`);
+    console.log(`Runtime: better-sqlite3`);
     try {
         const row = db.prepare(`SELECT sqlite_version() AS version`).get();
         doctorCheck("SQLite runtime", true, row.version);
@@ -4632,11 +4632,8 @@ if (isMain) {
                     const selfPath = fileURLToPath(import.meta.url);
                     const indexArgs = cli.values.index ? ["--index", String(cli.values.index)] : [];
                     const hostArgs = host ? ["--host", host] : [];
-                    const isBunRuntime = typeof process.versions.bun === "string";
                     const spawnArgs = selfPath.endsWith(".ts")
-                        ? isBunRuntime
-                            ? [selfPath, ...indexArgs, "mcp", "--http", "--port", String(port), ...hostArgs]
-                            : ["--import", pathJoin(dirname(selfPath), "..", "..", "node_modules", "tsx", "dist", "esm", "index.mjs"), selfPath, ...indexArgs, "mcp", "--http", "--port", String(port), ...hostArgs]
+                        ? ["--import", pathJoin(dirname(selfPath), "..", "..", "node_modules", "tsx", "dist", "esm", "index.mjs"), selfPath, ...indexArgs, "mcp", "--http", "--port", String(port), ...hostArgs]
                         : [selfPath, ...indexArgs, "mcp", "--http", "--port", String(port), ...hostArgs];
                     const child = nodeSpawn(process.execPath, spawnArgs, {
                         stdio: ["ignore", logFd, logFd],

package/dist/db.d.ts

@@ -1,27 +1,19 @@
 /**
- * db.ts - Cross-runtime SQLite compatibility layer
+ * db.ts - SQLite database connection and extension management
  *
- * Provides a unified Database export that works under both Bun (bun:sqlite)
- * and Node.js (better-sqlite3). The APIs are nearly identical — the main
- * difference is the import path.
- *
- * On macOS, Apple's system SQLite is compiled with SQLITE_OMIT_LOAD_EXTENSION,
- * which prevents loading native extensions like sqlite-vec. When running under
- * Bun we call Database.setCustomSQLite() to swap in Homebrew's full-featured
- * SQLite build before creating any database instances.
+ * Provides Database export and connection management using better-sqlite3
+ * and sqlite-vec.
  */
-export declare const isBun: boolean;
+import BetterSqlite3 from "better-sqlite3";
 export type SQLiteValue = string | number | bigint | Buffer | Uint8Array | Float32Array | null;
 export type SQLiteParams = readonly SQLiteValue[];
 /**
- * Open a SQLite database. Works with both bun:sqlite and better-sqlite3.
+ * Open a SQLite database using better-sqlite3.
  *
- * `bun:sqlite` and `better-sqlite3` both default `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 (e.g. an `update` or
- * `query` racing a long `embed`, or a first-open schema migration racing any
- * routine command) queue at batch boundaries instead of failing on contact.
+ * `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
@@ -29,37 +21,19 @@ export type SQLiteParams = readonly SQLiteValue[];
  *
  * 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). See
- * https://bun.sh/docs/api/sqlite#busy-timeout.
+ * restores the upstream fail-fast behaviour).
  */
 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;
 /**
- * Common subset of the Database interface used throughout QMD.
+ * Database and Statement types used throughout QMD.
  */
-export interface Database {
-    exec(sql: string): void;
-    prepare(sql: string): Statement;
-    loadExtension(path: string): void;
-    transaction<T extends (...args: SQLiteValue[]) => unknown>(fn: T): T & {
-        immediate: T;
-    };
-    close(): void;
-}
-export interface Statement {
-    run(...params: SQLiteValue[]): {
-        changes: number;
-        lastInsertRowid: number | bigint;
-    };
-    get<T = unknown>(...params: SQLiteValue[]): T | undefined;
-    all<T = unknown>(...params: SQLiteValue[]): T[];
-    iterate<T = unknown>(...params: SQLiteValue[]): IterableIterator<T>;
-}
+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 platform-specific fix instructions when the extension is
- * unavailable.
+ * Throws with fix instructions when the extension is unavailable.
  */
 export declare function loadSqliteVec(db: Database): void;

package/dist/db.js

@@ -1,57 +1,11 @@
 /**
- * db.ts - Cross-runtime SQLite compatibility layer
+ * db.ts - SQLite database connection and extension management
  *
- * Provides a unified Database export that works under both Bun (bun:sqlite)
- * and Node.js (better-sqlite3). The APIs are nearly identical — the main
- * difference is the import path.
- *
- * On macOS, Apple's system SQLite is compiled with SQLITE_OMIT_LOAD_EXTENSION,
- * which prevents loading native extensions like sqlite-vec. When running under
- * Bun we call Database.setCustomSQLite() to swap in Homebrew's full-featured
- * SQLite build before creating any database instances.
+ * Provides Database export and connection management using better-sqlite3
+ * and sqlite-vec.
  */
-export const isBun = "Bun" in globalThis;
-let _Database;
-let _sqliteVecLoad;
-if (isBun) {
-    // Dynamic string prevents tsc from resolving bun:sqlite on Node.js builds
-    const bunSqlite = "bun:" + "sqlite";
-    const BunDatabase = (await import(/* @vite-ignore */ bunSqlite)).Database;
-    // See: https://bun.com/docs/runtime/sqlite#setcustomsqlite
-    if (process.platform === "darwin") {
-        const homebrewPaths = [
-            "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib", // Apple Silicon
-            "/usr/local/opt/sqlite/lib/libsqlite3.dylib", // Intel
-        ];
-        for (const p of homebrewPaths) {
-            try {
-                BunDatabase.setCustomSQLite(p);
-                break;
-            }
-            catch { }
-        }
-    }
-    _Database = BunDatabase;
-    // setCustomSQLite may have silently failed — test that extensions actually work.
-    try {
-        const { getLoadablePath } = await import("sqlite-vec");
-        const vecPath = getLoadablePath();
-        const testDb = new BunDatabase(":memory:");
-        testDb.loadExtension(vecPath);
-        testDb.close();
-        _sqliteVecLoad = (db) => db.loadExtension(vecPath);
-    }
-    catch {
-        // Vector search won't work, but BM25 and other operations are unaffected.
-        _sqliteVecLoad = null;
-    }
-}
-else {
-    // Dual-runtime: better-sqlite3 matches Database at runtime; published types do not share an interface with bun:sqlite.
-    _Database = (await import("better-sqlite3")).default;
-    const sqliteVec = await import("sqlite-vec");
-    _sqliteVecLoad = (db) => sqliteVec.load(db);
-}
+import BetterSqlite3 from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
 function isBusyError(err) {
     if (typeof err !== "object" || err === null)
         return false;
@@ -86,14 +40,12 @@ function enableWal(db, budgetMs) {
     }
 }
 /**
- * Open a SQLite database. Works with both bun:sqlite and better-sqlite3.
+ * Open a SQLite database using better-sqlite3.
  *
- * `bun:sqlite` and `better-sqlite3` both default `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 (e.g. an `update` or
- * `query` racing a long `embed`, or a first-open schema migration racing any
- * routine command) queue at batch boundaries instead of failing on contact.
+ * `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
@@ -101,11 +53,10 @@ function enableWal(db, budgetMs) {
  *
  * 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). See
- * https://bun.sh/docs/api/sqlite#busy-timeout.
+ * restores the upstream fail-fast behaviour).
  */
 export function openDatabase(path) {
-    const db = new _Database(path);
+    const db = new BetterSqlite3(path);
     const raw = process.env.QMD_SQLITE_BUSY_TIMEOUT;
     const parsed = raw !== undefined && raw !== "" ? Number(raw) : Number.NaN;
     const busyTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 120_000;
@@ -115,10 +66,8 @@ export function openDatabase(path) {
 }
 /** Open an existing database without changing journal mode, schema, or user data. */
 export function openReadOnlyDatabase(path) {
-    const options = isBun
-        ? { readonly: true, create: false }
-        : { readonly: true, fileMustExist: true };
-    const db = new _Database(path, options);
+    const options = { readonly: true, fileMustExist: true };
+    const db = new BetterSqlite3(path, options);
     const raw = process.env.QMD_SQLITE_BUSY_TIMEOUT;
     const parsed = raw !== undefined && raw !== "" ? Number(raw) : Number.NaN;
     const busyTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 120_000;
@@ -128,16 +77,14 @@ export function openReadOnlyDatabase(path) {
 /**
  * Load the sqlite-vec extension into a database.
  *
- * Throws with platform-specific fix instructions when the extension is
- * unavailable.
+ * Throws with fix instructions when the extension is unavailable.
  */
 export function loadSqliteVec(db) {
-    if (!_sqliteVecLoad) {
-        const hint = isBun && process.platform === "darwin"
-            ? "On macOS with Bun, install Homebrew SQLite: brew install sqlite\n" +
-                "Or install qmd with npm instead: npm install -g @wei840222/qmd"
-            : "Ensure the sqlite-vec native module is installed correctly.";
-        throw new Error(`sqlite-vec extension is unavailable. ${hint}`);
+    try {
+        sqliteVec.load(db);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`sqlite-vec extension is unavailable. Ensure the sqlite-vec native module is installed correctly: ${message}`);
     }
-    _sqliteVecLoad(db);
 }

package/dist/search/zh-dict.txt

@@ -46617,6 +46617,7 @@ c++ 3 nz
 來歷不明 5 Vi
 來歸 4 Vi
 來源 1909 N
+來源位置 1000000 nz
 來源國 18 N
 來源地 3 N
 來源場 4 N
@@ -53444,7 +53445,7 @@ c++ 3 nz
 停養 5 Vt
 停養區 1 N
 停餐 18 N
-停駐 45 Vi
+停駐 1000000 nz
 停駕 6 Vi
 停駛 271 Vi
 停驗 2 Vt
@@ -151253,6 +151254,7 @@ c++ 3 nz
 多鹽 1 N
 多麗 1 N
 多麼 338 ADV
+多點傳送 1000000 nz
 多黨 19 N
 多黨制 1 N
 夛 198 zg
@@ -181443,6 +181445,7 @@ c++ 3 nz
 封前朝 2 nr
 封包 1000000 nz
 封包交換 1000000 nz
+封包遺失 1000000 nz
 封华歆 2 nr
 封博望 3 nr
 封博陵 2 nr
@@ -223286,6 +223289,7 @@ c++ 3 nz
 快反 22 v
 快取 1000000 nz
 快取記憶體 1000000 nz
+快取項目 1000000 nz
 快咬 3 v
 快嘴 11 N
 快嘴利舌 3 i
@@ -327168,7 +327172,7 @@ c++ 3 nz
 比容 7 n
 比对 88 d
 比对法 3 n
-比對 811 Vt
+比對 1000000 nz
 比對市 1 N
 比對戰 1 N
 比小孔 2 nr
@@ -345178,7 +345182,7 @@ c++ 3 nz
 流离颠疐 3 i
 流离颠顿 3 i
 流移失所 3 i
-流程 780 N
+流程 1000000 nz
 流程再造 1000000 nz
 流程化 4 n
 流程图 18 n
@@ -386962,6 +386966,7 @@ c++ 3 nz
 生命觀 2 N
 生命诚可贵 3 i
 生命财产 3 l
+生命週期 1000000 nz
 生命體 10 N
 生員 3 N
 生唐 2 t
@@ -402286,7 +402291,7 @@ c++ 3 nz
 相究 1 Vt
 相空间 3 n
 相竞 16 v
-相符 220 Vi
+相符 1000000 nz
 相符合 3 nr
 相等 18 Vi
 相等于 3 l
@@ -448252,6 +448257,7 @@ c++ 3 nz
 群憤 1 Vi
 群戲 1 N
 群批 1 N
+群播 1000000 nz
 群擋球 1 N
 群攀 1 N
 群攻 1 Vt
@@ -456405,7 +456411,7 @@ c++ 3 nz
 背日 3 n
 背日性 3 n
 背旮旯儿 3 z
-背景 1419 N
+背景 1000000 nz
 背景值 15 N
 背景光 1 N
 背景噪声 10 n
@@ -501378,7 +501384,7 @@ c++ 3 nz
 註消 1 N
 註生娘娘 44 N
 註腳 10 N
-註解 58 N
+註解 1000000 nz
 註記 184 N
 註語 1 N
 註載 1 N
@@ -542725,7 +542731,7 @@ c++ 3 nz
 遮空蔽日 3 i
 遮簷 2 N
 遮簾 1 N
-遮罩 3 N
+遮罩 1000000 nz
 遮羞 14 Vi
 遮羞布 37 N
 遮羞費 18 N

package/dist/store.js

@@ -3018,7 +3018,7 @@ export function countOrphanedVectors(db) {
  * Returns the number of orphaned embedding chunks deleted.
  */
 export function cleanupOrphanedVectors(db) {
-    // sqlite-vec may not be loaded (e.g. Bun's bun:sqlite lacks loadExtension).
+    // sqlite-vec may not be loaded if extension failed to initialize.
     // The vectors_vec virtual table can appear in sqlite_master from a prior
     // session, but querying it without the vec0 module loaded will crash (#380).
     if (!isSqliteVecAvailable()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wei840222/qmd",
-  "version": "2026.8.23",
+  "version": "2026.8.24",
   "packageManager": "pnpm@11.15.1",
   "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
   "type": "module",
@@ -34,17 +34,15 @@
     "lint": "oxlint",
     "test": "node scripts/test-all.mjs",
     "test:types": "node ./node_modules/typescript/bin/tsc -p tsconfig.build.json --noEmit",
-    "test:node": "bun scripts/test-runtime.mjs node",
-    "test:bun": "bun scripts/test-runtime.mjs bun",
-    "test:models:node": "bun scripts/test-runtime.mjs node --models-only",
-    "test:models:bun": "bun scripts/test-runtime.mjs bun --models-only",
-    "test:unit": "CI=true node ./node_modules/vitest/vitest.mjs run --reporter=verbose --testTimeout 60000 test/ && CI=true bun test --timeout 60000 --preload ./src/test-preload.ts test/",
+    "test:models": "node scripts/test-runtime.mjs",
+    "test:models:only": "node scripts/test-runtime.mjs --models-only",
+    "test:unit": "CI=true node ./node_modules/vitest/vitest.mjs run --reporter=verbose --testTimeout 60000 test/",
     "test:quality": "node ./node_modules/vitest/vitest.mjs run --reporter=verbose test/eval-cjk.test.ts",
     "test:package": "node scripts/package-smoke.mjs",
     "smoke:package-grammars": "node scripts/check-package-grammars.mjs",
     "dict:sync": "node scripts/sync-zh-dict.mjs",
-    "measure:cjk": "bun scripts/measure-cjk.ts",
-    "inspector": "bunx @modelcontextprotocol/inspector tsx src/cli/qmd.ts mcp",
+    "measure:cjk": "tsx scripts/measure-cjk.ts",
+    "inspector": "npx @modelcontextprotocol/inspector tsx src/cli/qmd.ts mcp",
     "release": "./scripts/release.sh",
     "qmd": "tsx src/cli/qmd.ts",
     "index": "tsx src/cli/qmd.ts index",
@@ -52,7 +50,7 @@
     "search": "tsx src/cli/qmd.ts search",
     "vsearch": "tsx src/cli/qmd.ts vsearch",
     "rerank": "tsx src/cli/qmd.ts rerank",
-    "bench": "bun src/cli/qmd.ts bench"
+    "bench": "tsx src/cli/qmd.ts bench"
   },
   "publishConfig": {
     "access": "public"
@@ -67,7 +65,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
-    "@node-rs/jieba": "2.0.1",
+    "@node-rs/jieba": "2.0.2",
     "better-sqlite3": "^13.0.3",
     "fast-glob": "3.3.3",
     "node-llama-cpp": "3.20.0",
@@ -112,7 +110,7 @@
     "vite": "7.3.5"
   },
   "peerDependencies": {
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3 || ^6.0.0-0"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -134,6 +132,6 @@
     "local-ai",
     "llm"
   ],
-  "author": "Tobi Lutke <tobi@lutke.com>",
+  "author": "Wan, Jiun Wei <wei840222@gmail.com>",
   "license": "MIT"
 }

package/scripts/check-package-grammars.mjs

@@ -24,6 +24,6 @@ for (const grammar of grammars) {
 }
 
 if (!ok) {
-  console.error("\nAST grammar package smoke check failed. Run `bun install` locally or repair a broken global install with the matching `bun add tree-sitter-...@<version>` command shown by `qmd status`.");
+  console.error("\nAST grammar package smoke check failed. Run `pnpm install` locally or repair a broken global install with the matching `pnpm add tree-sitter-...@<version>` command shown by `qmd status`.");
   process.exit(1);
 }

package/scripts/package-smoke.mjs

@@ -99,12 +99,6 @@ assertPath("THIRD_PARTY_NOTICES.md", "third-party notices");
 run("compiled CLI under Node", process.execPath, ["dist/cli/qmd.js", "--help"], { quiet: true });
 run("package wrapper", "sh", ["bin/qmd", "--help"], { quiet: true });
 
-if (process.env.QMD_SKIP_BUN_SMOKE === "1") {
-  console.log("==> compiled CLI under Bun (skipped by QMD_SKIP_BUN_SMOKE=1)");
-} else {
-  run("compiled CLI under Bun", "bun", ["dist/cli/qmd.js", "--help"], { quiet: true });
-}
-
 const packageSmokeRoot = process.env.QMD_PACKAGE_SMOKE_TMPDIR || join(root, ".tmp");
 mkdirSync(packageSmokeRoot, { recursive: true });
 const packageSmokeDir = mkdtempSync(join(packageSmokeRoot, "qmd-package-smoke-"));
@@ -129,9 +123,9 @@ try {
     `${JSON.stringify({ private: true, type: "module" }, null, 2)}\n`,
   );
   run(
-    "install packed tarball with Bun",
-    "bun",
-    ["add", "--ignore-scripts", join(packageSmokeDir, tarballName)],
+    "install packed tarball with npm",
+    "npm",
+    ["install", "--ignore-scripts", "--no-package-lock", join(packageSmokeDir, tarballName)],
     { cwd: consumerDir, quiet: true },
   );
 
@@ -179,14 +173,6 @@ try {
     ["--input-type=module", "--eval", jiebaSmoke],
     { cwd: consumerDir, env: smokeEnv, quiet: true },
   );
-  if (process.env.QMD_SKIP_BUN_SMOKE !== "1") {
-    run(
-      "packed jieba capability under Bun",
-      "bun",
-      ["--eval", jiebaSmoke],
-      { cwd: consumerDir, env: smokeEnv, quiet: true },
-    );
-  }
 } finally {
   rmSync(packageSmokeDir, { recursive: true, force: true });
 }

package/scripts/test-all.mjs

@@ -41,5 +41,4 @@ function run(label, command, args, options = {}) {
 
 run("TypeScript build typecheck", process.execPath, [join(root, "node_modules", "typescript", "bin", "tsc"), "-p", "tsconfig.build.json", "--noEmit"]);
 run("Vitest suite under Node", process.execPath, [join(root, "node_modules", "vitest", "vitest.mjs"), "run", "--reporter=verbose", "--testTimeout", "60000", "test/"], { env: { CI: "true" } });
-run("Bun test suite", "bun", ["test", "--timeout", "60000", "--preload", "./src/test-preload.ts", "test/"], { env: { CI: "true" } });
 run("Package smoke", process.execPath, ["scripts/package-smoke.mjs"]);

package/skills/qmd/SKILL.md

@@ -4,8 +4,8 @@ description: Search local markdown knowledge bases, notes, docs, and wikis with
 license: MIT
 compatibility: Requires qmd CLI or MCP server. Install via `npm install -g @wei840222/qmd`.
 metadata:
-  author: tobi
-  version: "2.6.3"
+  author: wei840222
+  version: 2026.8.23-1
 allowed-tools: Bash(qmd:*), mcp__qmd__*
 ---
 
@@ -209,8 +209,14 @@ When using the MCP server, prefer structured searches:
 {
   "searches": [
     { "type": "lex", "query": "cockpit OKR Goodhart" },
-    { "type": "vec", "query": "data informed not metric driven product judgment" },
-    { "type": "hyde", "query": "A concept note explains that metrics are useful as instruments, but leaders should not let OKRs or dashboards replace judgment." }
+    {
+      "type": "vec",
+      "query": "data informed not metric driven product judgment"
+    },
+    {
+      "type": "hyde",
+      "query": "A concept note explains that metrics are useful as instruments, but leaders should not let OKRs or dashboards replace judgment."
+    }
   ],
   "intent": "Find the concept note about using metrics as instruments without becoming metric-driven.",
   "collections": ["concepts"],
@@ -245,6 +251,8 @@ qmd query $'intent: Find the customer proximity concept, not generic customer de
 qmd search "six-week cadence WhatsApp merchant relationships Shawn Ryan" -c sources -n 10
 ```
 
+For the complete EBNF grammar, search operators, and JSON payload specifications, see [Query Syntax Reference](references/query-syntax.md).
+
 ## Setup and maintenance
 
 Only mutate indexes when the user asked for setup or maintenance. Searching and
@@ -264,17 +272,17 @@ Configure models and custom endpoints in `~/.config/qmd/index.yml` under the `mo
 ```yaml
 models:
   embed: hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf
-  embed_api_url: https://api.example.com/v1   # Both embed_api_url and embed_api_model enable remote embeddings
-  embed_api_model: text-embedding-3-small     # or text-embedding-3-large
-  embed_dimension: 1536                       # Optional: expected vector dimension; validates local output
+  embed_api_url: https://api.example.com/v1 # Both embed_api_url and embed_api_model enable remote embeddings
+  embed_api_model: text-embedding-3-small # or text-embedding-3-large
+  embed_dimension: 1536 # Optional: expected vector dimension; validates local output
 
   # Optional: Remote LLM Query Expansion (aliases: generate_url, generate_base_url, generate_api_url)
-  generate_api_url: https://api.example.com/v1    # Base URL (appends /chat/completions) or full endpoint
-  generate_api_model: qwen3-7b-instruct           # or your-model-name
+  generate_api_url: https://api.example.com/v1 # Base URL (appends /chat/completions) or full endpoint
+  generate_api_model: qwen3-7b-instruct # or your-model-name
 
   # Optional: Remote Reranking (supports rerank_url / rerank_base_url / rerank_api_url)
   rerank_api_url: https://api.example.com/v1/chat/completions # Supports both /v1/rerank and /v1/chat/completions LLM endpoints
-  rerank_api_model: bge-reranker-v2-m3        # or gpt-4o-mini / qwen3-7b-instruct
+  rerank_api_model: bge-reranker-v2-m3 # or gpt-4o-mini / qwen3-7b-instruct
 
 # Optional: Custom User Dictionary for CJK segmentation
 dictionary: ~/.config/qmd/dictionary.txt

package/skills/qmd/references/mcp-setup.md

@@ -10,30 +10,14 @@ qmd embed
 
 ## Configure MCP Client
 
-**Claude Code** (`~/.claude/settings.json`):
-```json
-{
-  "mcpServers": {
-    "qmd": { "command": "qmd", "args": ["mcp"] }
-  }
-}
-```
+Add QMD to your MCP client configuration (e.g. Cursor, Claude Desktop, Zed, OpenClaw, or other MCP-compatible clients):
 
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 ```json
 {
   "mcpServers": {
-    "qmd": { "command": "qmd", "args": ["mcp"] }
-  }
-}
-```
-
-**OpenClaw** (`~/.openclaw/openclaw.json`):
-```json
-{
-  "mcp": {
-    "servers": {
-      "qmd": { "command": "qmd", "args": ["mcp"] }
+    "qmd": {
+      "command": "qmd",
+      "args": ["mcp"]
     }
   }
 }

package/skills/qmd/references/query-syntax.md

@@ -0,0 +1,158 @@
+# QMD Query Syntax Reference
+
+QMD queries are structured documents composed of typed sub-queries. Each line specifies a search type and query text. The hybrid retrieval engine combines results via Reciprocal Rank Fusion (RRF) and reranks them.
+
+## Grammar
+
+```ebnf
+query          = policy_query | query_document ;
+policy_query   = [ policy_prefix ] text ;
+policy_prefix  = "lex:" | "expand:" ;
+query_document = [ intent_line ] { typed_line } ;
+intent_line    = "intent:" text newline ;
+typed_line     = type ":" text newline ;
+type           = "lex" | "vec" | "hyde" ;
+text           = quoted_phrase | plain_text ;
+quoted_phrase  = '"' { character } '"' ;
+plain_text     = { character } ;
+newline        = "\n" ;
+```
+
+## Query Types
+
+| Type | Method | Best For | Description |
+|------|--------|----------|-------------|
+| `lex` | BM25 (FTS5) | Exact terms, identifiers, code, titles | Keyword search with prefix, phrase, and negation support |
+| `vec` | Vector | Natural language concepts | Semantic similarity search using local/remote embeddings |
+| `hyde` | Vector | Complex conceptual questions | Hypothetical Document Embedding (generate expected passage) |
+
+## Default Policy & Expansion Behavior
+
+A query is either a single policy query or a multi-line query document:
+- **`auto` (Default)**: CJK queries and strong lexical matches automatically bypass model expansion. Other plain queries expand into `lex`, `vec`, and `hyde` variants.
+- **`expand:` / `--expand` (`force`)**: Explicitly forces expansion even if bypass heuristics apply.
+- **`lex:` (`skip`)**: Explicitly disables expansion and performs direct BM25 search.
+
+```bash
+# Automatic policy:
+qmd query "how does authentication work"
+
+# Force expansion:
+qmd query "expand: how does authentication work"
+# or: qmd query --expand "資料庫同步"
+
+# Explicitly skip expansion:
+qmd query "lex: authentication"
+```
+
+## Lexical Search Syntax (`lex:`)
+
+Lex queries support powerful search operators:
+
+| Syntax | Meaning | Example | Notes |
+|--------|---------|---------|-------|
+| `word` | Prefix match | `perf` | Matches "performance", "perform", etc. |
+| `"phrase"` | Exact phrase match | `"rate limiter"` | Terms must appear consecutively in order |
+| `-word` | Exclude term | `-sports` | Documents containing this word are excluded |
+| `-"phrase"` | Exclude phrase | `-"test data"` | Documents containing this phrase are excluded |
+
+### Examples
+
+```
+lex: CAP theorem consistency
+lex: "machine learning" -"deep learning"
+lex: auth -oauth -saml
+```
+
+## Vector Search Syntax (`vec:`)
+
+Natural language questions or descriptive phrases:
+
+```
+vec: how does the rate limiter handle burst traffic
+vec: what is the tradeoff between consistency and availability
+```
+
+## Hypothetical Document Embeddings (`hyde:`)
+
+A 50–100 word hypothetical answer passage representing what the target document likely says:
+
+```
+hyde: The rate limiter uses a sliding window counter algorithm with a 60-second window. When a client exceeds 100 requests per minute, subsequent requests return 429 Too Many Requests.
+```
+
+## Multi-Line Structured Queries
+
+Combine multiple sub-query types for optimal retrieval. The first sub-query receives **2x weight** during Reciprocal Rank Fusion:
+
+```
+lex: rate limiter algorithm
+vec: how does rate limiting work in the API
+hyde: The API implements rate limiting using a token bucket algorithm...
+```
+
+## Disambiguating with `intent:`
+
+An optional `intent:` line provides background context to disambiguate ambiguous queries. It steers query expansion, reranking, and snippet selection without generating search vectors itself:
+
+- At most one `intent:` line per query document.
+- Must be combined with at least one `lex:`, `vec:`, or `hyde:` line.
+- Can also be passed via the `--intent` CLI flag or MCP `intent` parameter.
+
+```
+intent: web page load times and Core Web Vitals
+lex: performance
+vec: how to improve performance
+```
+
+## Collection Scoping
+
+Scope search to specific collections using `-c` (CLI) or `collections` (MCP/SDK):
+
+```bash
+# CLI:
+qmd query -c docs "how does auth work"
+qmd query -c docs -c notes $'lex: auth\nvec: authentication flow'
+```
+
+## MCP Tool Call Payloads
+
+When calling the `qmd` MCP server's `query` tool, provide a structured `searches` array:
+
+### Standard Multi-Modal Query
+
+```json
+{
+  "searches": [
+    { "type": "lex", "query": "CAP theorem" },
+    { "type": "vec", "query": "consistency vs availability tradeoffs in distributed storage" }
+  ],
+  "collections": ["docs"],
+  "limit": 10
+}
+```
+
+### Query with Disambiguating Intent
+
+```json
+{
+  "searches": [
+    { "type": "lex", "query": "performance metrics" },
+    { "type": "vec", "query": "page load and network latency optimization" }
+  ],
+  "intent": "Front-end web performance and Core Web Vitals optimization",
+  "collections": ["frontend", "notes"],
+  "limit": 5
+}
+```
+
+### Plain Query with Policy Control & Explain Trace
+
+```json
+{
+  "query": "CAP theorem consistency",
+  "expansion": "auto",
+  "explain": true,
+  "collections": ["docs"]
+}
+```