@tobilu/qmd 2.0.0 → 2.1.0

package/dist/cli/qmd.js

@@ -3,13 +3,15 @@ import { openDatabase } from "../db.js";
 import fastGlob from "fast-glob";
 import { execSync, spawn as nodeSpawn } from "child_process";
 import { fileURLToPath } from "url";
-import { dirname, join as pathJoin } from "path";
+import { dirname, join as pathJoin, relative as relativePath } from "path";
 import { parseArgs } from "util";
-import { readFileSync, realpathSync, statSync, existsSync, unlinkSync, writeFileSync, openSync, closeSync, mkdirSync } from "fs";
-import { getPwd, getRealPath, homedir, resolve, enableProductionMode, searchFTS, extractSnippet, getContextForFile, getContextForPath, listCollections, removeCollection, renameCollection, findSimilarFiles, findDocumentByDocid, isDocid, matchFilesByGlob, getHashesNeedingEmbedding, getHashesForEmbedding, clearAllEmbeddings, insertEmbedding, getStatus, hashContent, extractTitle, formatDocForEmbedding, chunkDocumentByTokens, clearCache, getCacheKey, getCachedResult, setCachedResult, getIndexHealth, parseVirtualPath, buildVirtualPath, isVirtualPath, resolveVirtualPath, toVirtualPath, insertContent, insertDocument, findActiveDocument, updateDocumentTitle, updateDocument, deactivateDocument, getActiveDocumentPaths, cleanupOrphanedContent, deleteLLMCache, deleteInactiveDocuments, cleanupOrphanedVectors, vacuumDatabase, getCollectionsWithoutContext, getTopLevelPathsWithoutContext, handelize, hybridQuery, vectorSearchQuery, structuredSearch, addLineNumbers, DEFAULT_EMBED_MODEL, DEFAULT_RERANK_MODEL, DEFAULT_GLOB, DEFAULT_MULTI_GET_MAX_BYTES, createStore, getDefaultDbPath, reindexCollection, generateEmbeddings, syncConfigToDb, } from "../store.js";
-import { disposeDefaultLlamaCpp, getDefaultLlamaCpp, withLLMSession, pullModels, DEFAULT_EMBED_MODEL_URI, DEFAULT_GENERATE_MODEL_URI, DEFAULT_RERANK_MODEL_URI, DEFAULT_MODEL_CACHE_DIR } from "../llm.js";
+import { readFileSync, realpathSync, statSync, existsSync, unlinkSync, writeFileSync, openSync, closeSync, mkdirSync, lstatSync, rmSync, symlinkSync, readlinkSync } from "fs";
+import { createInterface } from "readline/promises";
+import { getPwd, getRealPath, homedir, resolve, enableProductionMode, searchFTS, extractSnippet, getContextForFile, getContextForPath, listCollections, removeCollection, renameCollection, findSimilarFiles, findDocumentByDocid, isDocid, matchFilesByGlob, getHashesNeedingEmbedding, clearAllEmbeddings, insertEmbedding, getStatus, hashContent, extractTitle, formatDocForEmbedding, chunkDocumentByTokens, clearCache, getCacheKey, getCachedResult, setCachedResult, getIndexHealth, parseVirtualPath, buildVirtualPath, isVirtualPath, resolveVirtualPath, toVirtualPath, insertContent, insertDocument, findActiveDocument, updateDocumentTitle, updateDocument, deactivateDocument, getActiveDocumentPaths, cleanupOrphanedContent, deleteLLMCache, deleteInactiveDocuments, cleanupOrphanedVectors, vacuumDatabase, getCollectionsWithoutContext, getTopLevelPathsWithoutContext, handelize, hybridQuery, vectorSearchQuery, structuredSearch, addLineNumbers, DEFAULT_EMBED_MODEL, DEFAULT_EMBED_MAX_BATCH_BYTES, DEFAULT_EMBED_MAX_DOCS_PER_BATCH, DEFAULT_RERANK_MODEL, DEFAULT_GLOB, DEFAULT_MULTI_GET_MAX_BYTES, createStore, getDefaultDbPath, reindexCollection, generateEmbeddings, syncConfigToDb, } from "../store.js";
+import { disposeDefaultLlamaCpp, getDefaultLlamaCpp, setDefaultLlamaCpp, LlamaCpp, withLLMSession, pullModels, DEFAULT_EMBED_MODEL_URI, DEFAULT_GENERATE_MODEL_URI, DEFAULT_RERANK_MODEL_URI, DEFAULT_MODEL_CACHE_DIR } from "../llm.js";
 import { formatSearchResults, formatDocuments, escapeXml, escapeCSV, } from "./formatter.js";
 import { getCollection as getCollectionFromYaml, listCollections as yamlListCollections, getDefaultCollectionNames, addContext as yamlAddContext, removeContext as yamlRemoveContext, removeCollection as yamlRemoveCollectionFn, renameCollection as yamlRenameCollectionFn, setGlobalContext, listAllContexts, setConfigIndexName, loadConfig, } from "../collections.js";
+import { getEmbeddedQmdSkillContent, getEmbeddedQmdSkillFiles } from "../embedded-skills.js";
 // Enable production mode - allows using default database path
 // Tests must set INDEX_PATH or use createStore() with explicit path
 enableProductionMode();
@@ -25,6 +27,13 @@ function getStore() {
         try {
             const config = loadConfig();
             syncConfigToDb(store.db, config);
+            if (config.models) {
+                setDefaultLlamaCpp(new LlamaCpp({
+                    embedModel: config.models.embed,
+                    generateModel: config.models.generate,
+                    rerankModel: config.models.rerank,
+                }));
+            }
         }
         catch {
             // Config may not exist yet — that's fine, DB works without it
@@ -259,6 +268,34 @@ async function showStatus() {
             context: ctx.context
         });
     }
+    // AST chunking status
+    try {
+        const { getASTStatus } = await import("../ast.js");
+        const ast = await getASTStatus();
+        console.log(`\n${c.bold}AST Chunking${c.reset}`);
+        if (ast.available) {
+            const ok = ast.languages.filter(l => l.available).map(l => l.language);
+            const fail = ast.languages.filter(l => !l.available);
+            console.log(`  Status:   ${c.green}active${c.reset}`);
+            console.log(`  Languages: ${ok.join(", ")}`);
+            if (fail.length > 0) {
+                for (const f of fail) {
+                    console.log(`  ${c.yellow}Unavailable: ${f.language} (${f.error})${c.reset}`);
+                }
+            }
+        }
+        else {
+            console.log(`  Status:   ${c.yellow}unavailable${c.reset} (falling back to regex chunking)`);
+            for (const l of ast.languages) {
+                if (l.error)
+                    console.log(`  ${c.dim}${l.language}: ${l.error}${c.reset}`);
+            }
+        }
+    }
+    catch {
+        console.log(`\n${c.bold}AST Chunking${c.reset}`);
+        console.log(`  Status:   ${c.dim}not available${c.reset}`);
+    }
     if (collections.length > 0) {
         console.log(`\n${c.bold}Collections${c.reset}`);
         for (const col of collections) {
@@ -785,7 +822,7 @@ function getDocument(filename, fromLine, maxLines, lineNumbers) {
 function multiGet(pattern, maxLines, maxBytes = DEFAULT_MULTI_GET_MAX_BYTES, format = "cli") {
     const db = getDb();
     // Check if it's a comma-separated list or a glob pattern
-    const isCommaSeparated = pattern.includes(',') && !pattern.includes('*') && !pattern.includes('?');
+    const isCommaSeparated = pattern.includes(',') && !pattern.includes('*') && !pattern.includes('?') && !pattern.includes('{');
     let files;
     if (isCommaSeparated) {
         // Comma-separated list of files (can be virtual paths or relative paths)
@@ -1365,26 +1402,51 @@ function renderProgressBar(percent, width = 30) {
     const bar = "█".repeat(filled) + "░".repeat(empty);
     return bar;
 }
-async function vectorIndex(model = DEFAULT_EMBED_MODEL, force = false) {
+function parseEmbedBatchOption(name, value) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return parsed;
+}
+function parseChunkStrategy(value) {
+    if (value === undefined)
+        return undefined;
+    const s = String(value);
+    if (s === "auto" || s === "regex")
+        return s;
+    throw new Error(`--chunk-strategy must be "auto" or "regex" (got "${s}")`);
+}
+async function vectorIndex(model = DEFAULT_EMBED_MODEL_URI, force = false, batchOptions) {
     const storeInstance = getStore();
     const db = storeInstance.db;
     if (force) {
         console.log(`${c.yellow}Force re-indexing: clearing all vectors...${c.reset}`);
     }
     // Check if there's work to do before starting
-    const hashesToEmbed = getHashesForEmbedding(db);
-    if (hashesToEmbed.length === 0 && !force) {
+    const hashesToEmbed = getHashesNeedingEmbedding(db);
+    if (hashesToEmbed === 0 && !force) {
         console.log(`${c.green}✓ All content hashes already have embeddings.${c.reset}`);
         closeDb();
         return;
     }
     console.log(`${c.dim}Model: ${model}${c.reset}\n`);
+    if (batchOptions?.maxDocsPerBatch !== undefined || batchOptions?.maxBatchBytes !== undefined) {
+        const maxDocsPerBatch = batchOptions.maxDocsPerBatch ?? DEFAULT_EMBED_MAX_DOCS_PER_BATCH;
+        const maxBatchBytes = batchOptions.maxBatchBytes ?? DEFAULT_EMBED_MAX_BATCH_BYTES;
+        console.log(`${c.dim}Batch: ${maxDocsPerBatch} docs / ${formatBytes(maxBatchBytes)}${c.reset}\n`);
+    }
     cursor.hide();
     progress.indeterminate();
     const startTime = Date.now();
     const result = await generateEmbeddings(storeInstance, {
         force,
         model,
+        maxDocsPerBatch: batchOptions?.maxDocsPerBatch,
+        maxBatchBytes: batchOptions?.maxBatchBytes,
+        chunkStrategy: batchOptions?.chunkStrategy,
         onProgress: (info) => {
             if (info.totalBytes === 0)
                 return;
@@ -1511,6 +1573,45 @@ function printEmptySearchResults(format, reason = "no_results") {
     }
     console.log("No results found.");
 }
+const DEFAULT_EDITOR_URI_TEMPLATE = "vscode://file/{path}:{line}:{col}";
+function encodePathForEditorUri(absolutePath) {
+    return encodeURI(absolutePath)
+        .replace(/\?/g, "%3F")
+        .replace(/#/g, "%23");
+}
+function getEditorUriTemplate() {
+    const envTemplate = process.env.QMD_EDITOR_URI?.trim();
+    if (envTemplate)
+        return envTemplate;
+    try {
+        const config = loadConfig();
+        const configTemplate = (config.editor_uri
+            || config.editor_uri_template
+            || config.editorUri
+            || (typeof config["editor-uri"] === "string" ? config["editor-uri"] : undefined))?.trim();
+        if (configTemplate)
+            return configTemplate;
+    }
+    catch {
+        // Ignore config parsing issues and use default template.
+    }
+    return DEFAULT_EDITOR_URI_TEMPLATE;
+}
+export function buildEditorUri(template, absolutePath, line, col) {
+    const safeLine = Number.isFinite(line) && line > 0 ? Math.floor(line) : 1;
+    const safeCol = Number.isFinite(col) && col > 0 ? Math.floor(col) : 1;
+    const encodedPath = encodePathForEditorUri(absolutePath);
+    return template
+        .replace(/\{path\}/g, encodedPath)
+        .replace(/\{line\}/g, String(safeLine))
+        .replace(/\{col\}/g, String(safeCol))
+        .replace(/\{column\}/g, String(safeCol));
+}
+export function termLink(text, url, isTTY = !!process.stdout.isTTY) {
+    if (!isTTY)
+        return text;
+    return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
 function outputResults(results, query, opts) {
     const filtered = results.filter(r => r.score >= opts.minScore).slice(0, opts.limit);
     if (filtered.length === 0) {
@@ -1553,6 +1654,8 @@ function outputResults(results, query, opts) {
         }
     }
     else if (opts.format === "cli") {
+        const editorUriTemplate = getEditorUriTemplate();
+        const linkDb = getDb();
         for (let i = 0; i < filtered.length; i++) {
             const row = filtered[i];
             if (!row)
@@ -1560,13 +1663,25 @@ function outputResults(results, query, opts) {
             const { line, snippet } = extractSnippet(row.body, query, 500, row.chunkPos, undefined, opts.intent);
             const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : undefined);
             // Line 1: filepath with docid
-            const path = toQmdPath(row.displayPath);
+            const virtualPath = row.file.startsWith("qmd://") ? row.file : toQmdPath(row.displayPath);
+            const parsed = parseVirtualPath(virtualPath);
+            const absolutePath = resolveVirtualPath(linkDb, virtualPath);
+            const legacyPath = toQmdPath(row.displayPath);
+            const displayPath = parsed?.path || row.displayPath;
             // Only show :line if we actually found a term match in the snippet body (exclude header line).
             const snippetBody = snippet.split("\n").slice(1).join("\n").toLowerCase();
             const hasMatch = query.toLowerCase().split(/\s+/).some(t => t.length > 0 && snippetBody.includes(t));
             const lineInfo = hasMatch ? `:${line}` : "";
             const docidStr = docid ? ` ${c.dim}#${docid}${c.reset}` : "";
-            console.log(`${c.cyan}${path}${c.dim}${lineInfo}${c.reset}${docidStr}`);
+            if (process.stdout.isTTY && absolutePath && parsed?.path) {
+                const linkLine = hasMatch ? line : 1;
+                const linkTarget = buildEditorUri(editorUriTemplate, absolutePath, linkLine, 1);
+                const clickable = termLink(`${displayPath}${lineInfo}`, linkTarget);
+                console.log(`${c.cyan}${clickable}${c.reset}${docidStr}`);
+            }
+            else {
+                console.log(`${c.cyan}${legacyPath}${c.dim}${lineInfo}${c.reset}${docidStr}`);
+            }
             // Line 2: Title (if available)
             if (row.title) {
                 console.log(`${c.bold}Title: ${row.title}${c.reset}`);
@@ -1865,8 +1980,10 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
                 limit: opts.all ? 500 : (opts.limit || 10),
                 minScore: opts.minScore || 0,
                 candidateLimit: opts.candidateLimit,
+                skipRerank: opts.skipRerank,
                 explain: !!opts.explain,
                 intent,
+                chunkStrategy: opts.chunkStrategy,
                 hooks: {
                     onEmbedStart: (count) => {
                         process.stderr.write(`${c.dim}Embedding ${count} ${count === 1 ? 'query' : 'queries'}...${c.reset}`);
@@ -1892,8 +2009,10 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
                 limit: opts.all ? 500 : (opts.limit || 10),
                 minScore: opts.minScore || 0,
                 candidateLimit: opts.candidateLimit,
+                skipRerank: opts.skipRerank,
                 explain: !!opts.explain,
                 intent,
+                chunkStrategy: opts.chunkStrategy,
                 hooks: {
                     onStrongSignal: (score) => {
                         process.stderr.write(`${c.dim}Strong BM25 signal (${score.toFixed(2)}) — skipping expansion${c.reset}\n`);
@@ -1969,6 +2088,8 @@ function parseCLI() {
             help: { type: "boolean", short: "h" },
             version: { type: "boolean", short: "v" },
             skill: { type: "boolean" },
+            global: { type: "boolean" },
+            yes: { type: "boolean" },
             // Search options
             n: { type: "string" },
             "min-score": { type: "string" },
@@ -1986,6 +2107,8 @@ function parseCLI() {
             mask: { type: "string" }, // glob pattern
             // Embed options
             force: { type: "boolean", short: "f" },
+            "max-docs-per-batch": { type: "string" },
+            "max-batch-mb": { type: "string" },
             // Update options
             pull: { type: "boolean" }, // git pull before update
             refresh: { type: "boolean" },
@@ -1996,7 +2119,10 @@ function parseCLI() {
             "line-numbers": { type: "boolean" }, // add line numbers to output
             // Query options
             "candidate-limit": { type: "string", short: "C" },
+            "no-rerank": { type: "boolean", default: false },
             intent: { type: "string" },
+            // Chunking options
+            "chunk-strategy": { type: "string" }, // "regex" (default) or "auto" (AST for code files)
             // MCP HTTP transport options
             http: { type: "boolean" },
             daemon: { type: "boolean" },
@@ -2036,8 +2162,10 @@ function parseCLI() {
         collection: values.collection,
         lineNumbers: !!values["line-numbers"],
         candidateLimit: values["candidate-limit"] ? parseInt(String(values["candidate-limit"]), 10) : undefined,
+        skipRerank: !!values["no-rerank"],
         explain: !!values.explain,
         intent: values.intent,
+        chunkStrategy: parseChunkStrategy(values["chunk-strategy"]),
     };
     return {
         command: positionals[0] || "",
@@ -2047,19 +2175,116 @@ function parseCLI() {
         values,
     };
 }
+function getSkillInstallDir(globalInstall) {
+    return globalInstall
+        ? resolve(homedir(), ".agents", "skills", "qmd")
+        : resolve(getPwd(), ".agents", "skills", "qmd");
+}
+function getClaudeSkillLinkPath(globalInstall) {
+    return globalInstall
+        ? resolve(homedir(), ".claude", "skills", "qmd")
+        : resolve(getPwd(), ".claude", "skills", "qmd");
+}
+function pathExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function removePath(path) {
+    const stat = lstatSync(path);
+    if (stat.isDirectory() && !stat.isSymbolicLink()) {
+        rmSync(path, { recursive: true, force: true });
+    }
+    else {
+        unlinkSync(path);
+    }
+}
 function showSkill() {
-    const scriptDir = dirname(fileURLToPath(import.meta.url));
-    const relativePath = pathJoin("skills", "qmd", "SKILL.md");
-    const skillPath = pathJoin(scriptDir, "..", "..", relativePath);
-    console.log(`QMD Skill (${relativePath})`);
-    console.log(`Location: ${skillPath}`);
+    console.log("QMD Skill (embedded)");
     console.log("");
-    if (!existsSync(skillPath)) {
-        console.error("SKILL.md not found. If you built from source, ensure skills/qmd/SKILL.md exists.");
+    const content = getEmbeddedQmdSkillContent();
+    process.stdout.write(content.endsWith("\n") ? content : content + "\n");
+}
+function writeEmbeddedSkill(targetDir, force) {
+    if (pathExists(targetDir)) {
+        if (!force) {
+            throw new Error(`Skill already exists: ${targetDir} (use --force to replace it)`);
+        }
+        removePath(targetDir);
+    }
+    mkdirSync(targetDir, { recursive: true });
+    for (const file of getEmbeddedQmdSkillFiles()) {
+        const destination = resolve(targetDir, file.relativePath);
+        mkdirSync(dirname(destination), { recursive: true });
+        writeFileSync(destination, file.content, "utf-8");
+    }
+}
+function ensureClaudeSymlink(linkPath, targetDir, force) {
+    const parentDir = dirname(linkPath);
+    if (pathExists(parentDir)) {
+        const resolvedTargetDir = realpathSync(dirname(targetDir));
+        const resolvedLinkParent = realpathSync(parentDir);
+        // If .claude/skills already resolves to the same directory as .agents/skills,
+        // the skill is already visible to Claude and creating qmd -> qmd would loop.
+        if (resolvedTargetDir === resolvedLinkParent) {
+            return false;
+        }
+    }
+    const linkTarget = relativePath(parentDir, targetDir) || ".";
+    mkdirSync(parentDir, { recursive: true });
+    if (pathExists(linkPath)) {
+        const stat = lstatSync(linkPath);
+        if (stat.isSymbolicLink() && readlinkSync(linkPath) === linkTarget) {
+            return true;
+        }
+        if (!force) {
+            throw new Error(`Claude skill path already exists: ${linkPath} (use --force to replace it)`);
+        }
+        removePath(linkPath);
+    }
+    symlinkSync(linkTarget, linkPath, "dir");
+    return true;
+}
+async function shouldCreateClaudeSymlink(linkPath, autoYes) {
+    if (autoYes) {
+        return true;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.log(`Tip: create a Claude symlink manually at ${linkPath}`);
+        return false;
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = await rl.question(`Create a symlink in ${linkPath}? [y/N] `);
+        const normalized = answer.trim().toLowerCase();
+        return normalized === "y" || normalized === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+async function installSkill(globalInstall, force, autoYes) {
+    const installDir = getSkillInstallDir(globalInstall);
+    writeEmbeddedSkill(installDir, force);
+    console.log(`✓ Installed QMD skill to ${installDir}`);
+    const claudeLinkPath = getClaudeSkillLinkPath(globalInstall);
+    if (!(await shouldCreateClaudeSymlink(claudeLinkPath, autoYes))) {
         return;
     }
-    const content = readFileSync(skillPath, "utf-8");
-    process.stdout.write(content.endsWith("\n") ? content : content + "\n");
+    const linked = ensureClaudeSymlink(claudeLinkPath, installDir, force);
+    if (linked) {
+        console.log(`✓ Linked Claude skill at ${claudeLinkPath}`);
+    }
+    else {
+        console.log(`✓ Claude already sees the skill via ${dirname(claudeLinkPath)}`);
+    }
 }
 function showHelp() {
     console.log("qmd — Quick Markdown Search");
@@ -2074,7 +2299,9 @@ function showHelp() {
     console.log("  qmd vsearch <query>           - Vector similarity only");
     console.log("  qmd get <file>[:line] [-l N]  - Show a single document, optional line slice");
     console.log("  qmd multi-get <pattern>       - Batch fetch via glob or comma-separated list");
+    console.log("  qmd skill show/install        - Show or install the packaged QMD skill");
     console.log("  qmd mcp                       - Start the MCP server (stdio transport for AI agents)");
+    console.log("  qmd bench <fixture.json>      - Run search quality benchmarks against a fixture file");
     console.log("");
     console.log("Collections & context:");
     console.log("  qmd collection add/list/remove/rename/show   - Manage indexed folders");
@@ -2085,6 +2312,8 @@ function showHelp() {
     console.log("  qmd status                    - View index + collection health");
     console.log("  qmd update [--pull]           - Re-index collections (optionally git pull first)");
     console.log("  qmd embed [-f]                - Generate/refresh vector embeddings");
+    console.log("    --max-docs-per-batch <n>    - Cap docs loaded into memory per embedding batch");
+    console.log("    --max-batch-mb <n>          - Cap UTF-8 MB loaded into memory per embedding batch");
     console.log("  qmd cleanup                   - Clear caches, vacuum DB");
     console.log("");
     console.log("Query syntax (qmd query):");
@@ -2123,11 +2352,14 @@ function showHelp() {
     console.log("");
     console.log("AI agents & integrations:");
     console.log("  - Run `qmd mcp` to expose the MCP server (stdio) to agents/IDEs.");
-    console.log("  - `qmd --skill` prints the packaged skills/qmd/SKILL.md (path + contents).");
+    console.log("  - `qmd skill install` installs the QMD skill into ./.agents/skills/qmd.");
+    console.log("  - Use `qmd skill install --global` for ~/.agents/skills/qmd.");
+    console.log("  - `qmd --skill` is kept as an alias for `qmd skill show`.");
     console.log("  - Advanced: `qmd mcp --http ...` and `qmd mcp --http --daemon` are optional for custom transports.");
     console.log("");
     console.log("Global options:");
     console.log("  --index <name>             - Use a named index (default: index)");
+    console.log("  QMD_EDITOR_URI             - Editor link template for clickable TTY search output");
     console.log("");
     console.log("Search options:");
     console.log("  -n <num>                   - Max results (default 5, or 20 for --files/--json)");
@@ -2135,11 +2367,15 @@ function showHelp() {
     console.log("  --min-score <num>          - Minimum similarity score");
     console.log("  --full                     - Output full document instead of snippet");
     console.log("  -C, --candidate-limit <n>  - Max candidates to rerank (default 40, lower = faster)");
+    console.log("  --no-rerank                - Skip LLM reranking (use RRF scores only, much faster on CPU)");
     console.log("  --line-numbers             - Include line numbers in output");
     console.log("  --explain                  - Include retrieval score traces (query --json/CLI)");
     console.log("  --files | --json | --csv | --md | --xml  - Output format");
     console.log("  -c, --collection <name>    - Filter by one or more collections");
     console.log("");
+    console.log("Embed/query options:");
+    console.log("  --chunk-strategy <auto|regex> - Chunking mode (default: regex; auto uses AST for code files)");
+    console.log("");
     console.log("Multi-get options:");
     console.log("  -l <num>                   - Maximum lines per file");
     console.log("  --max-bytes <num>          - Skip files larger than N bytes (default 10240)");
@@ -2178,6 +2414,19 @@ if (isMain) {
         showSkill();
         process.exit(0);
     }
+    if (cli.values.help && cli.command === "skill") {
+        console.log("Usage: qmd skill <show|install> [options]");
+        console.log("");
+        console.log("Commands:");
+        console.log("  show                 Print the packaged QMD skill");
+        console.log("  install              Install into ./.agents/skills/qmd");
+        console.log("");
+        console.log("Options:");
+        console.log("  --global             Install into ~/.agents/skills/qmd");
+        console.log("  --yes                Also create the .claude/skills/qmd symlink");
+        console.log("  -f, --force          Replace existing install or symlink");
+        process.exit(0);
+    }
     if (!cli.command || cli.values.help) {
         showHelp();
         process.exit(cli.values.help ? 0 : 1);
@@ -2416,7 +2665,20 @@ if (isMain) {
             await updateCollections();
             break;
         case "embed":
-            await vectorIndex(DEFAULT_EMBED_MODEL, !!cli.values.force);
+            try {
+                const maxDocsPerBatch = parseEmbedBatchOption("maxDocsPerBatch", cli.values["max-docs-per-batch"]);
+                const maxBatchMb = parseEmbedBatchOption("maxBatchBytes", cli.values["max-batch-mb"]);
+                const embedChunkStrategy = parseChunkStrategy(cli.values["chunk-strategy"]);
+                await vectorIndex(DEFAULT_EMBED_MODEL_URI, !!cli.values.force, {
+                    maxDocsPerBatch,
+                    maxBatchBytes: maxBatchMb === undefined ? undefined : maxBatchMb * 1024 * 1024,
+                    chunkStrategy: embedChunkStrategy,
+                });
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+                process.exit(1);
+            }
             break;
         case "pull": {
             const refresh = cli.values.refresh === undefined ? false : Boolean(cli.values.refresh);
@@ -2464,6 +2726,23 @@ if (isMain) {
             }
             await querySearch(cli.query, cli.opts);
             break;
+        case "bench": {
+            const fixturePath = cli.args[0];
+            if (!fixturePath) {
+                console.error("Usage: qmd bench <fixture.json> [--json] [-c collection]");
+                console.error("");
+                console.error("Run search quality benchmarks against a fixture file.");
+                console.error("See src/bench/fixtures/example.json for the fixture format.");
+                process.exit(1);
+            }
+            const { runBenchmark } = await import("../bench/bench.js");
+            const benchCollection = cli.opts.collection;
+            await runBenchmark(fixturePath, {
+                json: !!cli.opts.json,
+                collection: Array.isArray(benchCollection) ? benchCollection[0] : benchCollection,
+            });
+            break;
+        }
         case "mcp": {
             const sub = cli.args[0]; // stop | status | undefined
             // Cache dir for PID/log files — same dir as the index
@@ -2546,6 +2825,44 @@ if (isMain) {
             }
             break;
         }
+        case "skill": {
+            const subcommand = cli.args[0];
+            switch (subcommand) {
+                case "show": {
+                    showSkill();
+                    break;
+                }
+                case "install": {
+                    try {
+                        await installSkill(Boolean(cli.values.global), Boolean(cli.values.force), Boolean(cli.values.yes));
+                    }
+                    catch (error) {
+                        console.error(error instanceof Error ? error.message : String(error));
+                        process.exit(1);
+                    }
+                    break;
+                }
+                case "help":
+                case undefined: {
+                    console.log("Usage: qmd skill <show|install> [options]");
+                    console.log("");
+                    console.log("Commands:");
+                    console.log("  show                 Print the packaged QMD skill");
+                    console.log("  install              Install into ./.agents/skills/qmd");
+                    console.log("");
+                    console.log("Options:");
+                    console.log("  --global             Install into ~/.agents/skills/qmd");
+                    console.log("  --yes                Also create the .claude/skills/qmd symlink");
+                    console.log("  -f, --force          Replace existing install or symlink");
+                    process.exit(0);
+                }
+                default:
+                    console.error(`Unknown subcommand: ${subcommand}`);
+                    console.error("Run 'qmd skill help' for usage");
+                    process.exit(1);
+            }
+            break;
+        }
         case "cleanup": {
             const db = getDb();
             // 1. Clear llm_cache

package/dist/collections.d.ts

@@ -21,12 +21,23 @@ export interface Collection {
     update?: string;
     includeByDefault?: boolean;
 }
+/**
+ * Model configuration for embedding, reranking, and generation
+ */
+export interface ModelsConfig {
+    embed?: string;
+    rerank?: string;
+    generate?: string;
+}
 /**
  * The complete configuration file structure
  */
 export interface CollectionConfig {
     global_context?: string;
+    editor_uri?: string;
+    editor_uri_template?: string;
     collections: Record<string, Collection>;
+    models?: ModelsConfig;
 }
 /**
  * Collection with its name (for return values)

package/dist/db.d.ts

@@ -4,6 +4,11 @@
  * 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.
  */
 export declare const isBun: boolean;
 /**
@@ -29,5 +34,8 @@ export interface Statement {
 }
 /**
  * Load the sqlite-vec extension into a database.
+ *
+ * Throws with platform-specific fix instructions when the extension is
+ * unavailable.
  */
 export declare function loadSqliteVec(db: Database): void;