v2.5.3

## [2.5.3] - 2026-05-28

### Features

- `qmd get` now accepts a `:from:count` suffix on a path or docid (e.g.
  `qmd get "#abc123:120:40"` reads 40 lines starting at line 120). Explicit
  `--from`/`-l` flags still override the suffix. The MCP `get` tool accepts the
  same suffix.
- `qmd get` and `qmd multi-get` are now **line-numbered by default** and print
  the document's `#docid` and `qmd://` path in the output header. Disable line
  numbers with `--no-line-numbers`. The MCP `get`/`multi_get` tools default
  `lineNumbers` to `true` to match.
- `qmd multi-get` now includes the `#docid` in every output format
  (`--md`, `--json`, `--csv`, `--xml`, `--files`, and the default CLI view),
  consistent with `qmd search`.
- `qmd get` and `qmd multi-get` accept `--full-path`, which replaces the
  `qmd://` path + `#docid` with the document's on-disk filesystem path (handy for
  piping into `Read`/`Edit`/an editor). Falls back to the canonical `qmd://` +
  docid header when the file no longer exists on disk.
- `qmd search` / `qmd query` now show a clearer hit identifier: the default CLI
  view (and the new `**file:**` line in `--md` output) always prints the full
  `qmd://collection/path` URI so you can pipe it straight back into `qmd get`.
- `qmd search` / `qmd query` accept `--full-path` with the same semantics as
  `qmd get`: the result label becomes the file's on-disk path — `./`-prefixed
  relative path when the file lives in a subfolder of `$PWD`, absolute realpath
  otherwise — and the per-result `#docid` is dropped because the path is the
  identifier. The leading `./` is intentional so the output is unambiguously a
  filesystem path. Applies to all output formats.
- `qmd get` and `qmd multi-get` now also use the `./`-prefixed convention when
  `--full-path` renders a path under `$PWD`, matching `search`/`query`.
- New `--format <kind>` flag selects the output format (`cli` | `json` | `csv` |
  `md` | `xml` | `files`) for `search`, `query`, and `multi-get`. The legacy
  boolean aliases (`--json`/`--csv`/`--md`/`--xml`/`--files`) still work but are
  no longer in `--help`; prefer `--format`.

### Fixes

- Launcher: source-mode runner selection now prefers Node + tsx over Bun when
  both `package-lock.json` and `bun.lock` are present in the package root,
  mirroring the dist-mode "npm priority" rule. Fixes pnpm-global installs that
  copy the entire working tree (including `.git` and `bun.lock`) into the
  install dir and previously routed through Bun, causing ABI mismatches with
  the Node-built `better-sqlite3` / `sqlite-vec` native modules.
- Darwin Metal: llama-using commands (`query`, `vsearch`, `embed`) no longer
  dump a multi-kB GGML/Metal backtrace at process exit even when output
  succeeded. The libggml-metal static `ggml_metal_device` destructor asserts
  `[rsets->data count] == 0` during `__cxa_finalize_ranges`, but the
  buffer-free path never calls the symmetric `ggml_metal_device_rsets_rm`
  to remove released rsets from the device collection (upstream
  ggml-org/llama.cpp#22593, one-line fix open as PR #22595). The assertion
  only fires when `process.exit()` skips Node's `beforeExit` hook, which is
  what node-llama-cpp uses to auto-dispose Metal contexts. Primary fix:
  `finishSuccessfulCliCommand` now sets `process.exitCode = 0` and returns
  instead of calling `process.exit(0)`, so `beforeExit` fires and the native
  binding cleans up before libc's static destructor runs. Defense-in-depth:
  the launcher (`bin/qmd`) and the npm test driver (`scripts/test-all.mjs`
  + the `test:bun` / `test:unit` package.json scripts) also set
  `GGML_METAL_NO_RESIDENCY=1` on darwin before spawning node/bun, covering
  error paths and tests that still terminate via `process.exit()`. The env
  var must be set before node/bun start — libggml-metal reads it via libc
  `getenv` at module-load time, and Bun does not propagate `process.env`
  mutations to libc `setenv` — so it lives in the launcher rather than in
  test-preload. Residency sets give no measurable speedup for QMD's
  short-lived CLI workflow (benchmarked on M3 Pro). Opt back in with
  `QMD_METAL_KEEP_RESIDENCY=1` for long-lived qmd processes (e.g. the MCP
  daemon may benefit on hot reload) or to triage the upstream fix.
  `qmd doctor` reports the mitigation state. Minimal reproduction:
  `scripts/repro-metal-rsets-crash.mjs`.

### Docs

- qmd skill: emphasize reading line ranges with `get`'s built-in
  `:from:count` suffix / `--from`/`-l` flags instead of piping through
  `sed`/`head`/`tail`; cite the docid and line numbers now present in retrieval
  output; and author structured `intent:`/`lex:`/`vec:`/`hyde:` queries yourself
  rather than relying on built-in query expansion.

## [2.5.2] - 2026-05-22

### Fixes

- Launcher: Rewrite `bin/qmd` as a Node-based shebang polyglot to fix global npm installation execution failures on Windows (#668 / #452), while supporting seamless fallback to Bun in Node-less environments.


## [2.5.1] - 2026-05-20

### Changes

- Release: publish from GitHub Actions via npm Trusted Publishing/OIDC instead of a long-lived `NPM_TOKEN` secret.

## [2.5.0] - 2026-05-19

### Changes

- Dependencies: update core SQLite/config/chunking packages (`better-sqlite3`, `yaml`, `web-tree-sitter`, `tree-sitter-go`, and `tree-sitter-python`) while keeping incompatible `zod`, `tsx`, and `vitest` majors pinned.
- Agent skills: add `qmd skills list|get|path` to serve version-matched runtime skill instructions from the installed CLI, and make `qmd skill install` write a stable discovery stub so installed agent skills do not go stale after QMD upgrades.
- CLI: add `qmd doctor` for index/runtime diagnostics, including SQLite/sqlite-vec versions, embedding fingerprint freshness, mixed-fingerprint detection, safe legacy fingerprint adoption, and content-hash sampling.

### Fixes

- Launcher: prefer runnable TypeScript source in git checkouts even when ignored `dist/` artifacts exist, while packaged installs continue to run `dist/`.
- GPU: keep node-llama-cpp's documented `gpu: "auto"` initialization as the primary path, then perform no-build packaged CUDA/Vulkan/Metal probes only if auto falls back to CPU.
- CLI: move GPU/CPU runtime diagnostics out of `qmd status`; use `qmd doctor` for device probing and related environment guidance.
- CLI: point unexpected command/setup failures toward `qmd doctor` so diagnostics are the default next step when QMD behaves incorrectly.
- Doctor: explicitly warn when `content_vectors` contains multiple non-empty embedding fingerprint names, with the per-fingerprint document/chunk breakdown.
- Embed: make the TTY progress line label byte-based input progress explicitly, show embedded chunks as a count, and shorten the displayed model name.
- Embed: retain per-chunk failure details, retry failed chunks after later successful embeds and again when no other chunks remain, clear recovered errors, and cap retries to avoid endless loops.
- Tests: expand the container smoke harness to cover npm-global, npx-style, and Bun-global install scenarios, always checking auto and `QMD_FORCE_CPU=1` doctor modes, with opt-in tiny `qmd embed` and GPU probe runs for supported container runtimes.
- Embedding: fingerprint vector metadata using the active embedding model and formatting/chunking parameters so stale vectors are treated as pending after search semantics change. Legacy `content_vectors` columns are migrated lazily on first vector-health/write use to preserve fast QMD startup.

- Skill: expand the packaged QMD skill with retrieval-first workflows, structured query examples, wiki/source collection guidance, and safe fallbacks when model-backed search is unavailable.
- Tests: make `bun run test` execute the local unit suite under both Node/Vitest and Bun (`test:node` + `test:bun`) so runtime-specific regressions are caught before CI.
- Model config: centralize embedding/rerank/generation model resolution so `qmd embed`, `status`, `query`, `vsearch`, `pull`, SDK vector search, and `bench` use the same active `.qmd/index.yaml` model hints and environment fallbacks.
- GPU/status: `qmd status` now uses the same embedding model identity as `qmd embed` when computing pending embeddings, so URI-backed embeddings are not incorrectly reported as pending under the legacy `embeddinggemma` alias.
- GPU status: `qmd status` now always shows GPU mode/configuration without unsafe native probing, and CPU-fallback warnings point to `QMD_STATUS_DEVICE_PROBE=1 qmd status` for an actual backend probe. The no-GPU warning is emitted once per process instead of once per LLM instance during benchmarks.
- GPU: add `QMD_FORCE_CPU=1` / `--no-gpu` to bypass CUDA/Vulkan/Metal probing entirely, and route native llama.cpp stdout noise to stderr so JSON output stays parseable during search/query commands.
- Snippet line numbers: `qmd_query` (MCP), HTTP `/query`, and `qmd query`
  (CLI JSON output and snippet headers) now return absolute source-file
  line numbers instead of chunk-local ones, so the `line` field can be
  passed back to `qmd_get` as `fromLine` without a separate lookup.
  Snippet selection remains scoped to the best matching chunk
  (preserves #149).
- CLI: `qmd query --full` now emits the full document body in all output
  formats (json, csv, md, xml), restoring the documented behavior of the
  flag. Previously it returned only the best matching chunk (~3.6KB max
  per result). Output payload for `--full` queries is now proportional
  to total document size.
- macOS Metal: `qmd query --json` now flushes successful JSON output and uses a safe immediate-exit path on Darwin to avoid ggml Metal finalizer aborts; other commands still dispose LLM contexts/models before the llama runtime. #368
- Embedding: require complete chunk coverage before treating a document as
  embedded, remove partial vectors when chunk/session failures leave a
  document incomplete, and keep `qmd status` pending counts honest after
  interrupted long embed runs. #637 #378
- Embedding: `qmd embed -c <collection>` now scopes pending-doc selection
  to the requested collection instead of embedding global pending work.
  Scoped `--force` clears only collection-owned vectors, preserves shared
  hashes referenced by sibling collections, and drops `vectors_vec` only
  when the scoped clear empties all vectors.
- Hybrid search: weight RRF lists by query type so original FTS and original vector evidence get the intended 2x boost, instead of accidentally boosting the first lexical expansion. #591
- MCP: seed llama.cpp/GGML quiet env vars before launching `qmd mcp` so native logs cannot pollute stdio JSON-RPC framing. #593
- CLI: remove CommonJS `require()` calls from ESM index path normalization so `qmd --index <path>` no longer crashes with `ERR_AMBIGUOUS_MODULE_SYNTAX` on Node 22+. #634
- Windows CUDA: serialize llama.cpp embedding/reranking contexts by default to avoid intermittent `ggml-cuda.cu:98` crashes in `qmd query`; set `QMD_EMBED_PARALLELISM` to opt back into parallel contexts if your driver is stable. #519
- MCP: make `qmd mcp --index <name>` use the selected index for both foreground and daemon HTTP servers instead of falling back to the default store. #343
- Embedding: respect `QMD_EMBED_MODEL` consistently for vector indexing and vector-backed search, with default-model fallback when unset.
- Config: use one home-directory resolver for YAML config and the default SQLite cache path, avoiding Windows CLI/MCP split-brain when `HOME` is unset.
- GPU: respect explicit `QMD_LLAMA_GPU=metal|vulkan|cuda` backend overrides instead of always using auto GPU selection. #529
- Fix: preserve original filename case in `handelize()`. The previous
  `.toLowerCase()` call made indexed paths unreachable on case-sensitive
  filesystems (Linux). `qmd update` automatically migrates legacy
  lowercase paths without re-embedding.
- CLI: make `qmd status` skip native `node-llama-cpp` device probing by
  default so status stays safe on machines with broken or unsupported GPU
  drivers. Set `QMD_STATUS_DEVICE_PROBE=1` to opt in.
- CLI: lazy-load `node-llama-cpp` so lightweight commands such as
  `qmd status` do not import native ML dependencies or trigger llama.cpp
  builds on ARM/no-GPU machines. #491
- Store: keep content rows referenced by inactive documents during orphan
  cleanup so `qmd update` preserves soft-deleted tombstones for removed
  files. #585
- Packaging: install AST grammar WASM packages as required dependencies so
  Bun global installs include TypeScript/TSX/JavaScript grammars, and add a
  `smoke:package-grammars` verification command. #595
- Launcher: add wrapper smoke coverage for scoped package, npm/npx,
  Homebrew/Linuxbrew, Bun global symlink layouts, and `$BUN_INSTALL`
  false-positive runtime selection regressions. #351 #353 #354 #356 #358 #359