ko-qmd 2.8.3-ko.10

package/CHANGELOG.md

@@ -0,0 +1,1937 @@
+# Changelog
+
+## [Unreleased]
+
+## [2.8.3-ko.10] - 2026-10-15
+
+ko-qmd 2.8.3-ko.10 adds a shared working memory for agents: three MCP tools
+write provenance-tagged claims into a `mem` collection and read them back, so
+Claude Code, opencode and pi share one store through the same daemon.
+
+- MCP: `memory_store`, `memory_recall` and `memory_correct` over a collection
+  named `mem`. Every claim carries `actor`, `type` (fact · opinion · decision),
+  optional `source` and `project` frontmatter. A claim-lint gate (R1–R6) rejects
+  missing fields, facts or decisions without a locatable source, oversize
+  fields, out-of-range confidence and anything that looks like a secret before
+  a file is written. Corrections are append-only: `memory_correct`
+  writes a new file that `supersedes` the old one and stamps the old file with a
+  `superseded_by` footer. `memory_recall` searches `mem` and `kb` together,
+  narrows by actor or project, and marks a replaced claim with `superseded_by`.
+  Writes are lex-searchable at once; vectors follow on the next
+  `qmd embed -c mem`.
+- `memory_correct` path checks use the platform separator, so the
+  stay-inside-the-collection check no longer rejects every correction on
+  Windows.
+- Build: minification calls the esbuild JS API instead of spawning
+  `node_modules/.bin/esbuild.exe`, which npm never creates on Windows
+  (only `.cmd`/`.ps1` shims), so `npm install` fails there no more.
+
+- `qmd mcp --http --port` now validates the port: non-numeric or outside
+  1–65535 exits 1 with an error instead of silently falling back to 8181
+  (`--port 0`/`abc`) or crashing downstream on bind (`--port -1`).
+- SDK `addCollection` write-through no longer drops `ignore` (and preserves
+  `includeByDefault`/`update`/`context`): the YAML/inline entry is merged
+  instead of replaced, so `ignore` survives a close/reopen round-trip instead
+  of being nulled in the DB on resync.
+- Idle-unload guard now sees `withLLMSessionForLlm` sessions: per-instance
+  session managers are shared through a WeakMap and `canUnloadLLM(llm)` scopes
+  the verdict to that instance, so a live store session vetoes its own unload
+  (no more idle-timer dispose of a working context) while an unrelated
+  instance's session no longer pins it. No-arg `canUnloadLLM()` behavior on the
+  default path is unchanged.
+- `qmd update` no longer claims "✓ All collections updated." when trust-gated
+  collections were skipped: it prints `Updated N of M collection(s), skipped K`
+  and exits 1 so unattended runs can detect the partial update. No skips keeps
+  the success line and exit 0.
+
+- Reindex no longer aborts the whole `qmd update` when a file vanishes
+  between read and stat (ENOENT mid-pass, e.g. an update hook mutating the
+  tree): the `statSync` pair is guarded exactly like the #460 read guard —
+  skip + report via `skippedFiles`, rest of the pass completes.
+- `generateEmbeddings`: the 80%-error-rate abort now stops the whole run
+  instead of just the current 32-chunk window. Previously the outer
+  doc-batch loop kept going (re-warning per batch) and the post-batch
+  `retryFailedChunks(true)` immediately re-embedded the just-aborted
+  chunks, neutralizing the circuit breaker. The abort flag now breaks the
+  outer loop and skips the force-retry pass.
+- Rerank cascade head batch 15 → 8 (`RERANK_CASCADE_FIRST_BATCH`; `QMD_RERANK_FIRST_BATCH` /
+  `QMD_RERANK_MARGIN` overrides added for tuning). Cold hard-44 probe at
+  `candidateLimit` 40: rerank p50 2492 → 1267 ms, p90 2570 → 1352 ms, top-1
+  agreement 44/44; ko-vault seam gate holds (hard `full_r1`=0.6630, easy
+  `full_r5` +1 query).
+- Rerank input now strips a leading YAML frontmatter block over 350 chars
+  (`LONG_FRONTMATTER_CHARS` in `src/rerank-input.ts`) and no longer prepends
+  `# <title>` to the chunk. Third autoresearch loop (24 exps): train
+  `full_mrr` 0.6769 → 0.6880, held-out 0.7459 → 0.7572; ko-vault seam lines
+  byte-identical. ~90 notes carry up-to-2800-char `sources:` URL dumps that
+  filled the whole first chunk, so the reranker scored boilerplate.
+
+- Dependencies: `node-llama-cpp` 3.20.0 → **3.22.1**. ko-vault seam bench lines
+  are byte-identical before and after; Nix flake `qmd-node-modules` FOD hashes
+  refreshed for the new tree.
+
+## [2.8.3-ko.9] - 2026-10-10
+
+ko-qmd 2.8.3-ko.9 buys rank-1 accuracy and rerank latency at once. Per-document
+coverage weighting on relaxed lex lists takes hard `hybrid_r1` from 0.4444 to
+0.4778, and head-first rerank cascade halves rerank p50 with identical top-1
+answers. A load timeout (default 120 s) stops one stuck model load from hanging
+the query, as the scoring deadlines never covered the pre-ready wait.
+
+- `runWithDeadline` now bounds the model-load wait itself (`QMD_LLM_LOAD_TIMEOUT_MS`,
+  default 120 s, `0` = wait forever). The scoring deadlines never covered a load
+  that reports ready never: the pre-ready race hung with no timer, so one stuck
+  load hung the query. Past the load bound the stage is skipped exactly like a
+  scoring deadline (same `timeouts` entry, same RRF-order / original-query
+  fallback, same abandoned-run cache fill), and the bounded wait is reported as
+  the `load` stage. Listed in `qmd doctor`.
+- `QMD_RERANK_CASCADE=0` (or `false`/`off`/`no`) restores single-batch rerank.
+  Kill switch for measuring the cascade and for operations; unset cascades.
+  Listed in `qmd doctor`.
+- Rerank now cascades: the RRF head (15) is scored first, and the tail is
+  skipped with score 0 (RRF position order only) when the head's top-2 margin
+  reaches 0.08 (`RERANK_CASCADE_FIRST_BATCH`/`RERANK_CASCADE_MARGIN` in
+  `src/store.ts`). A contested top scores everything, as before; deadlines and
+  the rerank cache are unchanged (a skipped tail writes no cache entries).
+- `structuredSearch` and `hybridQuery` now weight a relaxed (any-word) lex list per
+  document by query coverage (`relaxedDocCoverage` in `src/store.ts`: 0.5 + 0.5 ×
+  matched units, mirroring the rerank chunk scorer's Hangul bigrams). A global
+  constant could not split the mirrored tie of `hmu-05` vs `sem-08` (2026-10-09
+  probe); both lead one list and take the same top-rank bonus, so only a per-doc
+  signal separates them. List weights are unchanged.
+## [2.8.3-ko.8] - 2026-10-09
+
+- `structuredSearch` (MCP `searches`, SDK `search({ queries })`) no longer lets a relaxed
+  (any-word) first lex list keep the 2x positional boost: it now counts 0.25 instead of 1.0.
+  Even halved, a relaxed rank 1 still tied a vector rank 1 against a lex rank 4 (`hmu-05`
+  probe), so the decoy sharing a few question words kept rank 1 on the `rerank:false` path.
+  On the ko-vault seam form, hard `hybrid_r1` goes 0.4111 → 0.4444 with `full_r1` unchanged at
+  0.6111; one easy query (`sem-08`) trades hybrid rank 1 for 2 while its `full` rank 1 and all
+  recall@5 lines hold. Non-first relaxed lists still count half, as before.
+- Hangul loanword table gains 11 entries mined from real query-log traffic (`지연` →
+  `latency`, `병렬` → `parallel`, `게이트` → `gate`, `가드` → `guard`, `패널` → `panel`,
+  `팔레트` → `palette`, `하네스` → `harness`, `옵시디언` → `obsidian`, `백링크` → `backlink`,
+  `포즈` → `pause`, `루프` → `loop`). Native words from the same logs (`색인`·`질의`·`요약`·`문서`
+  …) stay unbridged. Query-side only, no re-index; ko-vault bench lines are unchanged.
+- Negation routing stays strip-only by measurement: demoting X with lex `-term`s was tried
+  and reverted — the expected note often discusses X itself (`bm25-ranking.md` mentions TF-IDF),
+  so NOT removed the answer with the decoy (`hybrid_r1` 0.4111 → 0.3778). `stripHangulNegation`
+  now shares its parsing through an internal split helper; behavior is unchanged.
+
+## [2.8.3-ko.7] - 2026-10-02
+
+The query path is now observable and bounded. Every query-log row breaks its latency into
+stages, the daemon logs its heap once an hour, and expansion and rerank stop waiting past a
+deadline instead of holding a query for 85 s. The reranker also sees a note's first chunk by default.
+
+- `qmd mcp` (stdio and HTTP) no longer waits on a slow LLM stage without bound. Past
+  `QMD_EXPAND_DEADLINE_MS` (default 5 s) a query searches its original text alone, and past
+  `QMD_RERANK_DEADLINE_MS` (default 10 s) it answers in RRF order; `0` restores waiting. The clock
+  starts once the model is loaded, so a cold start or a reload after the idle unload is not a timeout;
+  the query log records that wait as a `load` stage. One MCP `query` with expansion and rerank took
+  85 s. The REST `/query` response and the MCP `query` tool say which stage timed out (`timeouts`),
+  the query log row lists it the same way, and a timed-out rerank reads `rerank: "timeout"` there.
+  A fallback does not apply `minScore` to its 1/rank scores. An abandoned expansion or rerank keeps
+  running and fills its cache; until it finishes, later queries skip that stage (logged once) instead
+  of queueing behind it. The CLI search commands and the SDK (`rerankDeadlineMs`, `expandDeadlineMs`
+  options) never set a deadline on their own.
+
+- The daemon's query log row now carries `stages`, the milliseconds spent in each stage of the
+  search: `refresh` (the pre-query re-index check), `expand`, `fts`, `embed`, `vec`, `chunk`,
+  `rerank` and `serialize`; a stage that did not run is absent. REST `rerank:false` queries had a p95 of 2.9–5.3 s
+  against a p50 of 0.2–0.5 s with no rerank in the path, and the single `ms` could not say which
+  stage the tail came from. Daemon log lines now start with a dated local ISO timestamp instead of
+  a UTC `HH:mm:ss.SSS`, so a slow line can be matched to its row.
+
+- The HTTP daemon logs a `health` line every hour: heap used and total, rss, and how many
+  `subscriptions/listen` and other `/mcp` requests have a handler still waiting on its response. A daemon that ran ten days died with
+  "Reached heap limit" after its heap crept to 3.8 GB under idle discover/cancelled traffic, and
+  nothing in the log showed the slope or what was holding memory. `QMD_HEALTH_LOG_INTERVAL_MS`
+  changes the interval; `0` turns it off.
+
+- `scripts/autoresearch/prepare.sh` builds the goldset from more than the collection folder and over
+  several runs. `AR_EXTRA_DIRS="outputs docs"` copies sibling folders of the collection into the corpus
+  (names only, so no vault path lands in git), `AR_RUN=N` writes `generated-N.json` from documents no
+  earlier run answered (`bench-vault-paraphrase.ts --dirs`, `--skip`), and `split` merges every run,
+  drops the query ids listed in `dropped.txt`, and splits only each run's new documents, so an earlier
+  train/held-out assignment never moves.
+
+- The reranker now gets a note's first chunk, its title and summary: the first chunk starts 16
+  points ahead in chunk selection (8 when an intent is given, so intent words can still pick a later
+  chunk). A later chunk needs 17 more points, about nine English words or seventeen Hangul syllable
+  pairs, so for a typical short query the first chunk is always sent. A second autoresearch loop found
+  this on a goldset of 320 train and 71 held-out queries drawn from four vault folders. Held-out full
+  MRR goes 0.7291 → 0.7459, ko-vault seam and hard lines are unchanged, and bm25, vector and hybrid
+  results are identical (`BASELINE.md` 2026-09-29).
+
+## [2.8.3-ko.6] - 2026-09-29
+
+Korean queries are handled better before and during reranking. A query written
+as "X 말고 Y" now searches for Y alone, and a Hangul query skips LLM expansion,
+which steadies hard-query results and cuts hybrid latency from about 1s to tens
+of ms per query. The reranker is now shown the chunk that best matches the
+query's Hangul syllable bigrams, led by the note title: held-out full MRR goes
+0.6589 → 0.7260 on a goldset generated from a real vault. Scoped vector search on
+small indexes runs one KNN (vector stage 250–1300ms → about 25ms). The README
+gains an English edition and an FAQ.
+
+- `QMD_RERANK_CACHE=<path>` keeps rerank scores in their own sqlite file instead of the index's
+  `llm_cache`, so a store over a rebuilt index reuses them. The key carries the query, the rerank
+  model, the doc-token cap and the chunk text, not the scoring code in `src/llm.ts`, so the file is
+  safe across index rebuilds with the same reranker code. It is not trimmed to 1000 rows. With it
+  set, a second `scripts/bench-ko.sh` run on ko-vault gives the same lines and its `full` backend
+  spends 3.7 s reranking instead of 300 s (the whole run drops from 5:17 to 0:56). Unset, nothing
+  changes. A fallback result (no rerank context could be created, every score 0.5) is no longer
+  cached in either place.
+
+- The reranker now sees a better chunk of a long Korean note. The chunk is chosen by the
+  two-syllable pairs of the query's Hangul words of three or more syllables, instead of whole
+  words, so `임베딩은` still finds a chunk about `임베딩`. Generic two-syllable words such as 방법
+  and 경우 no longer steer the choice. A query word with no Hangul (an English term, say) counts double. When the chosen chunk
+  does not contain the note title, `# <title>` is put in front of it. An autonomous loop
+  (`scripts/autoresearch/`) found this over 28 experiments on a goldset generated from a private
+  vault. The goldset's held-out split, which the loop never saw, goes from full MRR 0.6589 to
+  0.7260 (32 queries). ko-vault seam and hard lines are unchanged. The bm25, vector and hybrid
+  results do not read the rerank input and are identical on both sets (`BASELINE.md`
+  2026-09-28). An intent word now counts 1 point in chunk selection (was 0.5), keeping it at half a
+  query word now that a non-Hangul query word counts 2; no goldset carries intent, so no bench
+  number moves.
+
+- The reranker's input (the query string, which chunk of each candidate is sent and the document
+  text) is now built in `src/rerank-input.ts` for both `hybridQuery` and `structuredSearch`, which
+  had copied the chunk-scoring loop. Results are unchanged.
+
+- A Korean query of the form "X 말고 Y" now searches for Y alone. `hybridQuery` (CLI `qmd query`,
+  plain MCP `query`) and the `lex`/`vec` lines of `structuredSearch` (MCP `searches`, typed lines)
+  drop everything up to the last whitespace-separated 말고, 빼고, 제외하고 or 제외한. The rerank
+  query follows. `hyde` lines, `intent` and `qmd search`/`vsearch` stay as written. Before this
+  change every list also searched for X, the concept the user ruled out, so a note about X often
+  took rank 1. `아닌` and bare `제외` are not markers, because they also state conditions or act as
+  nouns. On the ko-vault seam form, the `neg` queries' full MRR goes 0.4500 → 0.6944. Hard
+  `full_r1` goes 0.5111 → 0.6111 and hard `full_mrr` 0.7472 → 0.8287. No query outside `neg`
+  changed its results, and that run is the gate's new reference (`BASELINE.md` 2026-09-27,
+  "a Korean negation clause is stripped before search").
+
+- `structuredSearch` (MCP `searches`, SDK `search({ queries })`, typed `lex:`/`vec:` lines) now
+  counts a relaxed lex list, one that matched only through the any-word retry, at half its slot's
+  weight, as `hybridQuery` already did. At a flat 2.0 for the first list, a lex line that matched
+  some of a Korean question's words outranked the vector list, and a decoy sharing those words took
+  rank 1. This one weight was the whole gap between the two paths on the Korean ko-vault queries:
+  re-fusing each path's lists with the other's weights reproduced its top 10 for 85 of 85 queries.
+  On the seam form, hard `hybrid_r1` goes 0.3111 → 0.3778 and `hybrid_r5` 0.8996 → 0.9211, with
+  `full_r1` unchanged at 0.5111, and that run is the gate's new reference (`BASELINE.md` 2026-09-27).
+
+- A query with any Hangul is no longer expanded by the LLM on the hybrid path (`hybridQuery`). That
+  path serves CLI `qmd query`, including an explicit `expand:` line, as well as a plain MCP `query`
+  and SDK `search({ query })`; `qmd vsearch` still expands. On the ko-vault goldset the
+  expansion model wrapped Korean questions in English sentence templates and stray Chinese, and its
+  sampling alone moved hard rank 1 by up to five of 30 queries between runs. Without it, hard
+  `hybrid_r1` reads 0.3778 (0.2611–0.3611 with expansion), `full_r1` holds at 0.5111, the easy
+  queries lose nothing, and the median hybrid query drops from about 1 s to 20 ms. The Korean
+  queries now return the same results on every run. English-only queries are still expanded, and a
+  caller who wants variants for a Korean question can pass its own `searches`
+  (`BASELINE.md` 2026-09-26).
+
+- `scripts/bench-ko.sh` benches the seam form by default. Every one-line goldset query reaches
+  `qmd bench` as `lex: <q>` + `vec: <q>`, the shape REST/MCP callers send, which skips LLM query
+  expansion. `KO_FORM=plain` keeps the old path, and the `RESULT-HARD` line now ends with
+  `form=<seam|plain>`. The `dogfood.sh` gate refuses a bench whose form differs from its baseline
+  line's form. On the seam form it gates hard `hybrid_r1` as well as `full_r1`, against a reference
+  line with `tol=0`, since the seam form gave the same lines in every run. The reason is the plain
+  form's hard wobble, which turned out to be the expansion sampler alone. Replaying recorded
+  expansions reproduces every query's top 10, and every query that moved between same-commit runs
+  had drawn a different expansion. The draw moved `hybrid_r1` by up to five of 30 queries and once
+  put `full_r1` 0.0007 above the old gate's floor (`BASELINE.md` 2026-09-26). The gate also runs
+  the bench with any exported `KO_BENCH`/`KO_CORPUS`/`KO_FORM` removed, and `bench-ko.sh` refuses a
+  `KO_BENCH` inside `tmp/bench-ko/`, where the run clears its outputs.
+
+- `scripts/bench-ko.sh` takes `KO_CORPUS` (a corpus directory holding `wiki/` and
+  `distractors/`) and `KO_BENCH` (a goldset) so an A/B runs through the same isolated harness
+  and stdout lines. Overrides resolve against the caller's cwd and are checked before the
+  previous run's output is removed. The first use settled a question: three everyday-language
+  question lines per document, decoys included, did not move hard rank 1 on the REST-shaped
+  goldset (hybrid_r1 0.3111 → 0.2778, full_r1 flat at 0.5111; hard hit@5 up 2 of 30). Index-time
+  summaries are therefore not being built. The same runs point the `hybrid_r1` wobble at LLM
+  query expansion rather than re-embedding (`BASELINE.md` 2026-09-25).
+- ko-vault goldset: 69 near-topic distractor documents and 30 hard queries (`sem-hard` /
+  `multi` / `neg`) join the fixture; `bench-ko.sh` indexes both directories (97 files) and
+  prints a `RESULT-HARD hybrid_r1=… full_r1=… n=30` line next to `RESULT`. The `dogfood.sh`
+  gate now also fails when the hard `full_r1` falls below the baseline minus the `tol=` recorded
+  on that baseline line, and fails closed when `RESULT-HARD` or its `tol=` goes missing.
+  `full_r1` is gated rather than `hybrid_r1` because it held one value across eight same-commit
+  runs, while `hybrid_r1` moved by about 3.5 queries of 30.
+  Fixture invariants (no title-term leakage, no excluded concept among expected files, no basename
+  collisions) are enforced by `test/ko-bench-fixture.test.ts`.
+
+- Collection- or filter-scoped vector search is faster on indexes of up to
+  4096 vectors. It now post-filters one sqlite-vec KNN over the whole table,
+  which is exact because vec0 KNN is a brute-force scan, instead of computing
+  `vec_distance_cosine` row by row. On the KB goldset (1047 of 3389 vectors,
+  M3 Max) the vector stage dropped from 250–1300ms to about 25ms, and a cold
+  capped query (cap 128, candidateLimit 15) went from p90 2000ms to 906ms with
+  identical rankings. Larger indexes keep the exact scan.
+
+## [2.8.3-ko.5] - 2026-09-24
+
+Rerank gets an input cap. Truncating each document to 128 tokens keeps KB
+goldset quality (Hit@5 0.97 / Recall@5 0.77) while cutting cold rerank p90 from
+3.6s to 0.9s on an M3 Max. The cap can be set daemon-wide
+(`QMD_RERANK_MAX_DOC_TOKENS`) or per request (`rerankMaxDocTokens` on REST
+`/query` and SDK `search()`). The README is now a Korean guide to ko-qmd itself,
+and the English reference lives in `docs/REFERENCE.md`.
+
+### Changes
+
+- README.md is rewritten in Korean around ko-qmd itself: what differs from
+  upstream, install, quick start, MCP/REST/SDK, environment variables and the
+  maintenance guide that used to live in `README.ko.md` (now removed). The
+  upstream-derived English reference (full CLI, MCP tool parameters, SDK API,
+  score fusion) moved to `docs/REFERENCE.md`, with install and import names
+  switched to `ko-qmd`.
+- REST `POST /query` and SDK `search()` take `rerankMaxDocTokens`, a
+  per-request rerank doc token cap. For that request it overrides the daemon's
+  `QMD_RERANK_MAX_DOC_TOKENS`, and it never raises the context budget. A caller
+  like the KB seam can then turn a capped rerank on for one machine without
+  changing the daemon's env. The rerank cache key follows the effective cap
+  (request, else env). Invalid values (non-integer, ≤ 0, strings) are ignored.
+- `QMD_RERANK_MAX_DOC_TOKENS` caps the tokens of each document sent to the
+  reranker, below the context budget. Unset keeps today's behaviour. On the KB
+  goldset (40 queries, candidateLimit 15), a cap of 128 keeps quality at
+  Hit@5 0.97 / Recall@5 0.77 against 0.95 / 0.76 uncapped. It cuts cold p90 from
+  3623ms to 897ms on an M3 Max and from 4720ms to 2192ms on another Apple Silicon
+  Mac. The cap is part of the rerank cache key, so capped and uncapped scores
+  never mix. Listed in `qmd doctor`.
+- `scripts/dogfood.sh` warms the embedding model with one vec query after
+  every daemon restart (deploy and `--restore`). A fresh daemon's first vec
+  query took 15.5s, so the first KB seam search after a restart hit its 20s
+  limit and fell back to rg. A failed warm-up is a warning, not a failed restart.
+- `scripts/dogfood.sh` waits for the *restarted* daemon. `launchctl kickstart -k`
+  returns while the old process is still shutting down and answering `/health`,
+  so the restart looked done ~9s before the new process listened. A `/health`
+  whose `uptime` predates the kickstart is now treated as the old process.
+
+## [2.8.3-ko.4] - 2026-09-24
+
+Korean documents are now chunked at their real token budget, and Hangul
+spellings of technical loanwords (`서치`, `웹 코어`) reach notes written in Latin
+script. This release also syncs tobi/qmd up to `04e4dbd` — metadata filtering,
+the oxlint fence and the REST JSON body guard — and adds `qmd grep`, `path`/
+`since`/`until` scoping on MCP and REST, and a daemon that keeps the text index
+fresh on its own. Existing indexes need one `qmd embed` run to pick up the new
+chunking, and SDK callers that passed `filter` for path/time scoping must rename
+it to `scope`.
+
+### Breaking
+
+- SDK: ko-qmd's path/time narrowing option is now `scope` (was `filter`) on
+  `search()`, `searchLex()` and `searchVector()`, and the trailing `scope`
+  parameter of `searchFTS`/`searchVec`. `filter` is upstream's metadata filter.
+  CLI `--path/--since/--until` and REST/MCP `path/since/until` are unchanged,
+  and a request may pass both — a result has to satisfy each.
+
+### Upstream sync
+
+- Merged tobi/qmd `main` up to `04e4dbd` (24 commits past v2.8.3): oxlint
+  fence (`bun run lint` is oxlint; the tsc check is `bun run test:types`),
+  metadata filtering, separator-aware FTS terms (quoted `"PIO-1384"` now
+  matches), REST JSON body guard, Windows index names, unreadable-gguf
+  diagnostics and the store-local embedding tokenizer. ko-qmd behaviour is
+  kept: the Hangul query branch runs ahead of the separator split, a metadata
+  filter gets the same anti-starvation scan as `--path`, and bm25 on the
+  ko-vault bench is identical per query.
+
+### Added
+
+- Added Oxlint lint fence.
+- Document metadata and metadata filtering. Markdown documents can opt into typed metadata through a namespaced frontmatter block (`qmd.metadata` with strings, numbers, booleans, or flat homogeneous arrays), and every search surface — CLI `search`/`vsearch`/`query` via `--filter <json>`, the SDK's `filter` option on `search()`/`searchLex()`/`searchVector()`, the MCP `query` tool, and HTTP `POST /query` and `/search` — accepts one shared recursive filter AST discriminated by `operator`: `and`/`or`/`not` logical groups, `eq`/`ne`/`gt`/`gte`/`lt`/`lte` comparisons, `in`/`nin`/`all` membership, and `exists` presence. Every returned result satisfies the filter (applied before RRF fusion and reranking); like collection filtering, highly selective filters remain best-effort for top-K completeness. Frontmatter stays ordinary searchable content — no chunking, embedding, snippet, or line-number changes — and documents without `qmd.metadata` behave exactly as before. JSON/SDK/MCP/HTTP results now include each document's indexed metadata, and `qmd status` reports how many documents still need metadata extraction (a normal `qmd update` backfills existing indexes).
+
+### Fixed
+
+- Embedding generation and legacy fingerprint adoption now tokenize documents
+  with the store-selected embedding model instead of the global default. This
+  keeps chunk boundaries aligned with the model that creates and verifies the
+  stored vectors without initializing an unrelated provider.
+
+### Changes
+
+- Plain Hangul lex terms that spell a common technical loanword (`서치`, `웹`,
+  `코어`, `마이그레이션`, about 80 entries in a built-in table) also match the
+  Latin spelling, so `하이브리드 서치` finds a note that only says
+  `hybrid-search` and `리액트 웹 코어` reaches `react-web-core`. The lookup runs
+  on particle-stripped stems too (`서치를`), single-syllable entries (`웹`, `훅`)
+  are bridged when they stand alone (not `웹을`), and terms with no entry produce the same FTS5 query as before.
+  Query-side only; no re-index. On the ko-vault bench the eleven new loanword
+  queries go from bm25_r5 0.0000 to 1.0000 while the original 52 hold at
+  0.9519 per query.
+- REST `POST /query` and the MCP `query` tool attach `vec_score` (cosine
+  similarity) and `fts_score` (normalized BM25) to each result on the
+  `rerank:false` path, where `score` is the 1/rank fusion position and cannot
+  be thresholded. Each is the max over the sub-queries that returned the hit
+  and is omitted, never 0, when that backend did not return it. The daemon
+  query log (`QMD_QUERY_LOG`) records the same two fields per result; the row
+  schema stays `v: 1` and `rerank:true` responses are unchanged.
+- Korean documents are chunked at their real token budget instead of the
+  English-tuned 3.0 chars/token: `estimateCharsPerToken` blends CJK and other
+  scripts as a harmonic mean (measured ko 1.64 / en 6.08 chars per token on
+  Qwen3-Embedding-0.6B-Q8_0, 2026-09-21), and indexing plus both search-path
+  best-chunk selections size chunks with it. A 20KB Korean document now
+  first-passes into ~900-token chunks instead of being split ~855 and Korean
+  rerank chunks shrink from ~3600 to ~1440 chars. Non-CJK text keeps the ratio
+  each call site already used — 3.0 when indexing, 4.0 on the search paths — so
+  English chunk boundaries do not move, and the ko-vault bench holds
+  (bm25_r5=0.9519).
+- Re-embedding a document whose chunk count shrank now prunes its stale
+  higher-`seq` vectors before inserting, so one `qmd embed` run converges
+  instead of waiting for a second run. The embedding fingerprint gains a
+  `chunk_chars_estimator` term, so `qmd status` reports re-embedding as needed
+  for existing indexes; run `qmd embed` once to pick up the new chunking.
+
+- `search`, `vsearch` and `query` take `--path`, `--since` and `--until`, so a
+  search can be narrowed to part of a collection or to what changed recently.
+  `--path` matches globs against `collection/path` and is repeatable, with a
+  `!` prefix to exclude; `--since` / `--until` take a span (`7d`) or a date.
+  The filter narrows the corpus rather than the result list — excluded
+  documents are gone before ranking, on the vector path as well as BM25, so a
+  narrow filter returns its own best matches instead of whatever survived the
+  global top-K. A span that does not parse is an error, and a filter that
+  leaves nothing to search says so instead of looking like "no match".
+
+- `qmd query --explain` now lists every expansion sub-query that placed the
+  document, with that sub-query's own rank, contribution, backend score and the
+  text it ran. It previously showed the top three contributions collapsed onto
+  one line without the query text, which could not distinguish a document that
+  ranked first in one sub-query and nowhere else from one that ranked middling
+  everywhere — two situations that call for different fixes.
+
+- `qmd grep <pattern>` matches document bodies exactly, by string or regular
+  expression, with no ranking and no LLM: every matching line, grouped by file,
+  with line numbers that `qmd get <file>:<n>:<count>` accepts. It is the escape
+  hatch for a query that finds nothing because tokenization never produced the
+  term the document contains — the failure this fork keeps hitting with Korean
+  text — and for finding an identifier or error string verbatim. It searches
+  exactly what the index holds and honours collection scoping, `--path`,
+  `--since` and `--until`. Smart case: an uppercase letter in the pattern makes
+  it case-sensitive, and Hangul has no case so Korean patterns are unaffected.
+  `-F` searches for a literal string. An MCP `grep` tool exposes the same thing
+  to agents, which is the reason it exists: a client whose only tools are
+  `query`, `get` and `multi_get` has no other way to match a string exactly.
+
+- The MCP `query` tool and the REST `/query` endpoint take the same `path`,
+  `since` and `until` parameters, so an agent can scope a search to a folder or
+  to recent changes without shelling out. A span that does not parse comes back
+  as an error rather than an unfiltered search, and an empty result under a
+  filter reports how many documents the filter left — an agent reading a bare
+  "No results" would otherwise conclude the corpus has nothing on the topic.
+
+- The HTTP and stdio MCP daemon keeps the text index current on its own. Before
+  each search it checks the collections that search covers — at most once every
+  30 seconds each — and re-indexes the ones whose files changed, so a note
+  written while the daemon runs is findable on the next query without `qmd
+  update`. It updates keyword search only; vectors still wait for `qmd embed`.
+  It does not run a collection's `update:` hook, does not clear the LLM cache
+  the way `qmd update` does, and does not touch a collection whose folder has
+  vanished or emptied, since reindexing would deactivate every document in it.
+
+- The daemon's query log now covers the MCP `query` tool, not just the REST
+  endpoints. A search an agent runs through MCP over HTTP lands in the same
+  `queries-YYYY-MM.jsonl` with `via: "mcp"`, the same result path spelling and
+  the same `X-QMD-*` header handling, so a dogfooding session's real traffic is
+  in one file. A plain `query` argument is recorded as one search of type
+  `auto`. stdio MCP calls stay unlogged — they carry no request to annotate.
+
+## [2.8.3-ko.3] - 2026-09-18
+
+The reranker now decides which document ranks first. The blend's retrieval-position
+term could outweigh the entire reranker score, so the top retrieval hit was
+unreachable; making position a 10% linear decay took recall@1 from .713 to .874 on
+223 name-like queries and from .467 to .867 on 30 paraphrase queries. The HTTP daemon
+gains two operational knobs: `QMD_QUERY_LOG=1` records every search it serves to a
+monthly JSONL, and `QMD_LLM_IDLE_TIMEOUT_MS=0` keeps models resident, which takes the
+first search after an idle spell from ~1.8s to ~0.07s.
+
+### Changes
+
+- `qmd query`'s reranker can now change which document comes first. The score
+  that orders results blended the reranker against a retrieval-position term of
+  `1 / rrfRank` under rank-gated weights, and that term falls 0.375 between rank
+  1 and rank 2 — more than the 0.25 the entire reranker term could contribute.
+  The top retrieval hit was therefore unreachable: a document the reranker scored
+  0.03 stayed ahead of one it scored 1.00. Position is now a linear decay across
+  the candidate window worth 10% of the blend, so it separates documents the
+  reranker scores alike instead of overruling it. Measured over a fixed candidate
+  dump per goldset, so every formula saw identical retrieval: recall@1 went .713
+  to .874 on 223 alias queries and .467 to .867 on 30 paraphrase queries. On both
+  goldsets the old blend's recall@1 equalled retrieval-only recall@1 to three
+  decimals, which is what an inert reranker looks like as a number.
+- New bench tooling: `scripts/bench-vault-summarize.ts` writes a plain-language
+  summary per document with a local model, and `bench-vault-summary-apply.mjs`
+  builds the summary-augmented copy of a vault that the bench then indexes. This
+  measures whether the vocabulary gap the paraphrase goldset is made of closes at
+  index time. On 16 such queries, giving each document three everyday-language
+  lines took `search` (BM25, no LLM) from .250 to .562 recall@5 and the unreranked
+  hybrid path from .625 to .812. The reranked path did not move (.875 both ways,
+  the same two queries missed): it was already covering the gap, so the summaries
+  buy the cheap backends most of what the expensive one had. The BM25 number
+  carries no confound — that backend never calls query expansion. Summary lines
+  are filtered by document frequency, because a model that emits "이 도구는 뭘 하는
+  건데?" would otherwise give every vague query a weak match on an unrelated
+  document.
+- New bench tooling: `scripts/bench-dump-candidates.ts` records the RRF rank and
+  reranker score of every candidate for each goldset query, and
+  `scripts/bench-blend-sweep.mjs` re-scores that dump under different blend
+  formulas. Comparing two formulas used to mean two bench runs, which vary in
+  their retrieval and take about an hour each; it now costs one dump and a
+  millisecond per formula, and the variants are compared against the same
+  candidates.
+
+- `bench-vault-goldset.mjs` adds two buckets that cost no model call: `alias`,
+  the display text of a `[[target|alias]]` wikilink, and `fmalias`, an entry of
+  the target's own `aliases:` frontmatter list. Both are human-written other
+  names for a document. First measurement on a 232-document vault (223 queries):
+  `full` scored 0.924 r@5 against `hybrid` 0.978 and `vector` 0.982 — of the 17
+  queries `full` missed, `hybrid` had 14 in its top five. The reranker demotes
+  short name-like queries that retrieval already found.
+- `bench-vault-paraphrase.ts` writes its output after every document, so a run
+  killed from outside keeps what it had done.
+
+- `QMD_LLM_IDLE_TIMEOUT_MS` sets how long loaded models stay idle before they
+  are unloaded (`0` = never), overriding the 5 minutes `createStore()` passes.
+  On a long-running HTTP daemon the first search after a quiet spell no longer
+  pays for reloading the models.
+- `QMD_QUERY_LOG=1` makes the HTTP daemon append every `POST /query` /
+  `/search` search to `queries-YYYY-MM.jsonl` in the qmd cache directory: the
+  qmd version and commit, an index fingerprint, the searches, and each result's
+  path, score and rank — never snippets. Clients tag rows with `X-QMD-Tag`,
+  `X-QMD-Qid` and `X-QMD-Role`, and skip them with `X-QMD-No-Log: 1`. Writes
+  never fail a search; `qmd status` shows the newest log file and the MCP
+  `status` tool shows the daemon's flag and last write error.
+- `scripts/dogfood.sh` builds the checkout, stops if bench-ko `bm25_r5` falls
+  below the newest BASELINE.md line, installs the packed tarball globally,
+  restarts the launchd daemon and smoke-tests it; `--restore` reinstalls the
+  published package.
+
+- `develop` is the working branch; `main` only receives merges from it and is
+  where `/release` tags. `publish.yml` authenticates with the `NPM_TOKEN`
+  repository secret and skips a version that is already on the registry, so a
+  manually published version or a re-pushed tag still gets its GitHub release.
+  CI runs for `develop` pushes and pull requests too.
+
+### Fixes
+
+- `bench-vault-report.mjs` writes its miss list next to the input, never on top
+  of it. The path came from `replace('bench.json', 'misses.json')`, a no-op for
+  any other file name, so reporting on a copied result overwrote that result.
+- Query expansion drops sub-queries that have nothing to do with the query again.
+  The drift filter kept an expansion only if it shared a word with the query, but
+  it read the query as `[a-z0-9]` words, so a Korean query produced an empty word
+  list and the filter passed everything. Measured over 151 expansions of 30
+  Korean queries it rejected none, including 22 that were generic English
+  boilerplate ("Proper implementation follows established patterns and best
+  practices.") with no relation to the query — each one an embedding call and a
+  vector search spent on noise. A shared Hangul syllable bigram now counts as the
+  same kind of anchor: it drops those 22 and keeps 127 of the 129 Korean
+  expansions. A query with no anchor of either kind still keeps everything.
+- Query expansion strips thinking tags from a sub-query before searching for it.
+  The grammar forbids newlines inside a line, so a `</think>` arrives welded to
+  the sub-query text rather than on a line of its own that parsing would skip; 20
+  of 46 hyde expansions in the same measurement carried one, and the tag was
+  embedded along with the text that mattered.
+- Query expansion no longer runs the same sub-query twice on the same backend.
+- `limit` no longer decides how wide a search looks, only how many results come
+  back. Both searches over-fetch by a multiple of `limit` — the FTS index by 10x
+  because the collection filter runs after the match, vectors by 3x or 30x
+  because chunks of one document collapse into one result — so a small `limit`
+  left a pool that post-filtering could exhaust, and `-n 5` was not the first five
+  of `-n 20`. The CLI made it visible: its default limit is 20 for `--json` and
+  `--files` and 5 otherwise, so the output format changed which documents were
+  found. Retrieval now looks at 20 documents at minimum whatever `limit` says,
+  which is the breadth `qmd query` already used internally.
+- `bench-vault.sh` refuses to run when the vault it was given sits inside the
+  work directory it is about to `rm -rf`. The work directory is named after the
+  vault, so a vault under `tmp/real-bench/` resolved to the same path and the
+  corpus was deleted before it could be indexed, which showed up as a bench over
+  zero documents rather than as an error.
+- `bench-vault-report.mjs` prints every backend that ran under each bucket, and
+  takes its miss list from the best backend rather than from BM25. The bucket
+  lines were BM25-only under a bare bucket name, so a run's `sem: 9/16` read as
+  the result of the pipeline the run was measuring.
+
+- The Windows git-install probe failed on every push with `Permission denied
+  (publickey)`: npm and pnpm resolve any github.com dependency over SSH first
+  and do not retry an auth failure over https, the runner has no key, and the
+  repository is private so anonymous https fails as well. The job now rewrites
+  every github.com URL to https with the job token via git `insteadOf` before
+  installing.
+
+## [2.8.3-ko.2] - 2026-09-17
+
+### Changes
+
+- Published to npm as `ko-qmd`. Install with `npm i -g ko-qmd`
+  after `npm uninstall -g @tobilu/qmd` (both ship a `qmd` bin). `publish.yml` is
+  back: pushing a `v*` tag runs the tests, publishes with provenance and creates
+  the GitHub release. The GitHub-tag install path still works for unpublished
+  commits.
+- New bench tooling: `scripts/bench-vault-paraphrase.ts` builds a paraphrase
+  goldset from a vault by asking a local model, through ollama, for the question
+  someone would type when they do not know the vocabulary a document is written
+  in. The existing `bench-vault-goldset.mjs` harvests the document's own words,
+  which measures lexical matching; this measures the case that fails it. Every
+  candidate passes four mechanical gates and a separate verification call that
+  rejects fluent questions about things the document does not discuss. Defaults
+  to `qwen3:4b`; takes `--minutes` to stop on a time budget, `--seed` to sample
+  the vault when it does, and `--max-df` to tune which heading words a question
+  may not reuse.
+- `GenerateOptions` no longer has a `model` field. `LlamaCpp.generate` never read
+  it: the model is fixed per instance from `generateModel` at construction, so a
+  caller passing `model` got the instance's model back with no error and no
+  indication the request was dropped. Construct a second `LlamaCpp` to generate
+  with a different model. Nothing in the package passed the field.
+
+### Fixes
+
+- The release pre-push hook reads CI from the remote being pushed to. It asked
+  `gh api repos/{owner}/{repo}`, which resolves through gh's own remote
+  heuristic: with an `upstream` remote present that is the repo this one was
+  forked from, so every commit that exists only here answered 422. The hook
+  reported "no runs found" and let the tag through unverified. An API error now
+  aborts instead of reading as "CI has not started".
+
+## [2.8.3-ko.1] - 2026-09-16
+
+### Changes
+
+- ko-vault bench fixture pins the package's default embedding model
+  (Qwen3-Embedding-0.6B-Q8_0) instead of embeddinggemma. Measured on the same
+  tree: `vector_r5` 0.9861 → 1.0000, `hybrid_r5` 0.9722 → 0.9861, `bm25_r5`
+  unchanged at 0.6528. Numbers and caveats in
+  `test/fixtures/ko-vault/BASELINE.md`.
+- README.md states what this distribution is and links README.ko.md.
+- Hangul lex queries also strip a verbal or nominalizing ending (`토큰화하는` →
+  `토큰화`, `검색하기` → `검색`) and unwind a two-particle chain (`청킹에서의` →
+  `청킹`). ko-vault bench `bm25_r5` 0.6635 → 0.7212 on a 52-query goldset, with
+  the original 36 queries unchanged at 0.6528.
+- Hangul stems also cover a bare `한`/`된` ending (`필요한` → `필요`) and the
+  하↔해 contraction (`더하` ↔ `더해`), so a query stem meets the contracted spelling
+  documents actually use. `bm25_r5` 0.7212 → 0.7404, hybrid and full 1.0000.
+- Long Korean queries no longer return nothing. `searchFTS` retries the same
+  terms ORed when the strict AND matches no document at all (three terms
+  minimum). A natural question is a sentence, and requiring every word of it
+  present matched nothing: on a 30-query Korean paraphrase goldset lex recall@5
+  was 0.0000 and is now 0.5667. The synthetic ko-vault fixture moves with it,
+  `bm25_r5` 0.7404 → 0.9519.
+- Hybrid RRF weights rebalanced for Korean: vector lists count half, relaxed
+  (ORed) lex lists count half again and never count as a strong signal, and
+  expansion-derived lists move 1.0 → 0.75 so the original query's vector list
+  still outranks a lex expansion. Hybrid recall@5 on 240 exact-phrase queries
+  0.9167 → 0.9583, on the paraphrase goldset 0.8333 → 0.8667. Sweep and caveats
+  in `test/fixtures/ko-vault/BASELINE.md`.
+- Hangul lex queries split script-mixed terms into runs and AND them
+  (`SKILL.md계약의핵심` → `skill` AND `md` AND `계약의핵심`). Before this the glued
+  token was one phrase that matches nothing, and the hyphen/dot branches kept the
+  Hangul run glued too. Measured on a real 232-document Korean vault with a
+  240-query goldset: `bm25_r5` 0.9042 → 0.9333, `bm25_mrr` 0.8666 → 0.8937.
+- `scripts/bench-vault.sh` and `scripts/bench-vault-goldset.mjs` run the Korean
+  bench over any real vault, building the goldset from that vault's own headings
+  and body clauses. Nothing from the vault is copied into the repo.
+- ko-vault goldset grew 36 → 52 with particle chains, verb endings and joined
+  compounds.
+- `qmd bench` no longer needs `expected_in_top_k` on every fixture entry. It was
+  required in practice: omitting it made the result limit NaN and every backend
+  returned zero results with no error.
+
+## [2.8.3-ko.0] - 2026-09-16
+
+### Fixes
+
+- pnpm consumers install this package from a git tag, where pnpm runs `prepare`
+  (tsc only). Two things broke that on Windows: a stale `pnpm-lock.yaml`
+  (`ERR_PNPM_OUTDATED_LOCKFILE`) and `pnpm.onlyBuiltDependencies`, which made
+  pnpm build better-sqlite3 from source in an environment with no Visual Studio.
+  The lockfile is regenerated and the built-dependency list is now empty — the
+  `dist` build needs no native module, and consumers build their own. Run
+  `pnpm approve-builds` when developing this repo with pnpm. npm installs were
+  unaffected.
+
+### Changes
+
+- ko-qmd distribution: package renamed to `ko-qmd`
+  (`2.8.3-ko.0`), consumed from git tags instead of npm (`publish.yml`
+  removed). CI adds a `windows-latest` Node 22 job and an Electron 39 smoke job
+  that imports the SDK with dynamic `import()` and runs `searchLex`. See
+  `README.ko.md`.
+- Hangul lex queries: an unquoted Korean word also matches its stem with one
+  trailing particle or `기` stripped (`검색을` → `("검 색" OR "검 색 을")`,
+  stem ≥2 syllables). Quoted phrases and Han/kana terms are unchanged. ko-vault
+  bench `bm25_r5` 0.6250 → 0.6528.
+- Hangul syllable bigrams in the FTS index: each indexed field carries the
+  bigrams of its Hangul runs after the character tokens, and a plain Korean word
+  queries bigram OR character phrases of the word and its stem. Character-phrase
+  and quoted-phrase matching is unchanged. `FTS_CJK_NORMALIZED_VERSION` is now
+  `"2"`, so existing indexes rebuild FTS once on open. ko-vault bench
+  `bm25_r5` 0.6528 → 0.6528 (no measured gain on the fixture).
+- Korean defaults: the default embedding model is now
+  `hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf`
+  (1024 dimensions; upstream default is embeddinggemma-300M). Reranker and
+  query-expansion defaults are unchanged. Existing indexes need `qmd embed -f`;
+  set `models: embed:` or `QMD_EMBED_MODEL` to keep embeddinggemma. The qmd skill
+  gains a "Korean queries" section. Hangul handling and ko-vault bench numbers
+  are in `README.ko.md`.
+
+## [2.8.3] - 2026-08-16
+
+### Security
+
+- `qmd update` no longer runs a project-local `.qmd/index.yml`'s `update:`
+  commands without approval (#886). That file arrives with a `git clone` and is
+  adopted automatically for any command run inside the tree, so cloning a
+  repository and running `qmd update` executed shell commands chosen by whoever
+  wrote it. On a terminal QMD now lists the commands and asks; with nobody to
+  ask it skips them and keeps indexing. Approvals are recorded per config file
+  and per command set in `<config dir>/trusted.json`, so editing a command — or
+  a `git pull` that rewrites one — asks again. New `qmd trust`,
+  `qmd trust list` and `qmd trust revoke` manage approvals, and
+  `QMD_TRUST_UPDATE_HOOKS=1` opts unattended runs back in. Commands in your own
+  `~/.config/qmd/*.yml`, including anything `qmd collection update-cmd` writes,
+  are unaffected.
+
+- The same project-local trust gate now covers collection `path` values that
+  resolve outside the project and non-default `models.embed` / `models.rerank`
+  / `models.generate` URIs (#889). In-project paths still index unattended;
+  out-of-project directories are skipped until `qmd trust`, and custom model
+  URIs are not loaded or downloaded. `QMD_TRUST_LOCAL_CONFIG=1` opts unattended
+  runs back in (and `QMD_TRUST_UPDATE_HOOKS=1` still does). `qmd collection
+  add` records trust as it writes, the same way `update-cmd` does.
+
+- Indexing no longer follows file symlinks or glob `../` / absolute patterns
+  out of the collection directory. `fast-glob` already skipped symlinked
+  directories, but a file symlink (or a mask like `../**/*.md`) still resolved
+  via `realpath` and ingested the target. `qmd://` filesystem resolution uses
+  the same containment check, so `qmd://collection/../../../etc/passwd` no
+  longer produces a path outside the collection.
+
+- `qmd mcp --http` now validates the `Origin` and `Host` headers on every
+  request and answers `403` when they name anything but a loopback address
+  (#881). Binding to localhost is no defence against the user's own browser:
+  a page can re-point its hostname at `127.0.0.1` (DNS rebinding) and read
+  the indexed corpus through `POST /query` or `POST /mcp`. Requests with no
+  `Origin` (curl, MCP clients, editors) are unaffected. Extend the allowlists
+  with `QMD_ALLOWED_ORIGINS` / `QMD_ALLOWED_HOSTS`, or set
+  `QMD_ALLOWED_ORIGINS=*` behind your own authenticating proxy. A wildcard
+  bind (`--host 0.0.0.0`) skips the host check and warns at startup.
+
+### Changed
+
+- Dependencies: `node-llama-cpp` 3.18.1 → **3.20.0** (llama.cpp b8390 → b10361, 2026-08-11). Also safe patch/minors: `picomatch` 4.0.4 → 4.0.5, `web-tree-sitter` 0.26.8 → 0.26.12, `tsx` 4.21.0 → 4.23.12, `vitest` 3.2.4 → 3.2.7. No zod/vitest major; `@modelcontextprotocol/server` stays 2.0.0 (no 2.x patch). `flake.nix` FOD hashes are not updated here.
+- `generate` and query expansion now await `LlamaContextSequence.dispose()` before disposing the parent context. node-llama-cpp 3.20 made sequence dispose async; the library's context-onDispose path does not wait.
+
+- MCP server now speaks protocol revision **2026-07-28** via the official
+  TypeScript SDK 2.x (`@modelcontextprotocol/server`). HTTP is sessionless
+  (no `Mcp-Session-Id`, no initialize handshake, no idle-session TTL / #816
+  reaper). Clients send version and capabilities in `_meta`; `server/discover`
+  is implemented; Streamable HTTP POST requires `Mcp-Method` / `Mcp-Name`
+  (mismatch → `-32020`); `tools/list` is deterministic and carries `ttlMs` /
+  `cacheScope`. 2025-era stdio clients still work (`serveStdio` dual-speak);
+  2025-era HTTP `initialize` is answered per-request without minting a
+  session. Existing tools (`query` / `get` / `multi_get` / `status`), stdio
+  EOF shutdown, and named-index daemon PIDs are unchanged. No release.
+
+- `qmd pull` (and implicit model downloads in `embed`/`query`) no longer print
+  node-llama-cpp's download progress bar. The bar redraws every few kilobytes
+  and flooded agent transcripts with thousands of tokens (#776). Pass
+  `qmd pull --progress` to show it on an interactive terminal.
+- `--full-path` no longer degrades silently when a result cannot be resolved on
+  disk (#785). A fallback there means the file moved or was deleted since the
+  last index, so `search`, `query`, `get` and `multi-get` now print a notice to
+  stderr naming how many results fell back and suggesting `qmd update`; stdout
+  stays machine-readable.
+- `search`/`query` now decide per result whether to show the docid under
+  `--full-path`, matching `multi-get` and `get`: a result that resolved shows
+  its on-disk path and no docid, one that did not keeps its `qmd://` URI *and*
+  its docid, so it is still addressable. Previously the docid was dropped for
+  every row whenever the flag was set, leaving unresolved rows with neither a
+  usable path nor an identifier.
+- `search --format csv` always emits the `docid` column, empty for rows that
+  resolved to an on-disk path. Under `--full-path` the header previously
+  dropped the column entirely — which also disagreed with the empty-result
+  header, always printed with `docid`. Column positions are now stable across
+  runs and formats.
+
+### Fixed
+
+- Concurrent first-open of a cold index no longer fails with
+  `table documents_fts already exists` on Bun/macOS. FTS5
+  `CREATE VIRTUAL TABLE IF NOT EXISTS` is not atomic across WAL
+  connections: two processes can both see a missing table on their
+  schema snapshot and the loser throws. Table create and legacy-schema
+  repair now use the same `BEGIN IMMEDIATE` + double-check as the FTS
+  sync triggers, and treat a concurrent "already exists" as success
+  when the table is present.
+
+- Nix flake `qmd-node-modules` FOD hashes updated for x86_64-linux and
+  aarch64-darwin after the MCP SDK 2.0 bump. `nix build` / Nix GHA was
+  failing with a fixed-output hash mismatch.
+
+- CJK FTS rebuild no longer skips leftover `fts5(name, body, content='documents')`
+  tables when `fts_cjk_normalized_version` is already stamped, and schema
+  repair now checks live FTS columns (`PRAGMA table_info`) as well as
+  `sqlite_master.sql`. The MCP HTTP test helper still seeds that legacy
+  table; `startMcpHttpServer` / `createStore` on it must not throw
+  `no such column: T.name` (#792 regression).
+
+- `qmd collection add --glob` is no longer silently ignored. parseArgs ran
+  with `strict: false`, so OpenClaw's `--glob memory.md` (and any other
+  `--glob`) fell through, the default `**/*.md` was used, and a second
+  collection on the same path collided as a duplicate instead of indexing
+  the requested mask (#536). `--glob` is now an alias for `--mask`.
+
+- The `bin/qmd` trampoline now execs `process.execPath` instead of
+  re-resolving `node` from PATH. Native addons (`better-sqlite3`) are
+  compiled for the Node that installed qmd; a version manager (nvm, fnm,
+  mise) selecting a different major in the working directory used to spawn
+  that other binary and fail with `NODE_MODULE_VERSION` / `ERR_DLOPEN_FAILED`
+  (#577 leftover; #319). `bun bin/qmd` still resolves `node` from PATH so
+  Node-ABI addons are not loaded into bun.
+
+- `qmd update` / `qmd collection add` no longer swallow unreadable files
+  silently (#460). `readFileSync` failures (ETIMEDOUT on APFS compressed
+  files, EAGAIN, EACCES, …) still skip the file so the rest of the collection
+  indexes, but the CLI now warns with the path and error code and reports
+  the skip count. The SDK `update()` result includes `skipped`.
+
+- The architecture diagram no longer draws Vec expansions into BM25 search
+  (#680). `lex` expansions are FTS-only; `vec` and `hyde` expansions are
+  vector-only. The original query still goes to both backends.
+
+- `qmd bench` no longer runs to a wall of 0.00 when the fixture collection is
+  missing or empty (#716). It errors up front with the same "Collection not
+  found" / index hint as `qmd search -c`, and if every backend still scores
+  zero it warns on stderr to check `qmd ls`.
+
+- `qmd cleanup` now reclaims the content and FTS space left behind after a
+  wrong-directory `qmd update`. Deactivating files (the next update in the
+  right directory) only tombstoned the `documents` rows; cleanup deleted those
+  rows and vacuumed, but never dropped the unreferenced `content` hashes and
+  never ran FTS5 `optimize`, so `documents_fts_data` kept the old bodies
+  (#550). Cleanup now deletes inactive docs, then orphaned content, then
+  compact FTS, then vacuum. `--dry-run` reports the content hashes too.
+
+- Concurrent `query` calls with `rerank: true` on a cold MCP server no longer
+  race `ensureRerankContexts()`. Embed already serialized context creation;
+  rerank did not, so two overlapping first queries both saw an empty pool,
+  both created ranking contexts, and the inactivity timer disposed the loser
+  (`Object is disposed`, #682). Callers now await the in-flight create.
+
+- Embedding-context pool size no longer assumes every GGUF costs 150 MB of
+  VRAM (the nomic-embed figure). Larger models such as Qwen3-Embedding-0.6B
+  are ~1190 MB per 2048-token context; opening 8 of those exhausted an 8 GB
+  card so `qmd query` failed with `Failed to create any rerank context` even
+  though the reranker itself was fine. The pool is now sized from the weight
+  file, and 1 GB is reserved for the reranker (#799). Default
+  embeddinggemma/nomic throughput is unchanged. `QMD_EMBED_PARALLELISM` still
+  overrides.
+
+- Multi-collection `-c A -c B` (and SDK/MCP `collections: [A, B]`) no longer
+  searches globally then post-filters. A large unrelated collection could fill
+  the FTS/ANN top-k so the requested collections vanished, yielding false-empty
+  results even though each collection matched on its own. `searchFTS` /
+  `searchVec` now search each requested collection, then merge by score
+  (#775). Single-collection exact-scan (#791, #803) is unchanged.
+
+- Query expansion no longer consumes caller `intent`, and a cached expansion
+  whose sub-queries all miss is dropped instead of replaying forever (#818).
+  Intent still steers reranking and snippet/chunk selection; it just no longer
+  enters the expansion prompt or cache key, where the model copied meta-language
+  ("so I can compare spend settings") into lex/vec terms that matched nothing.
+
+- Files whose names differ only in the characters the legacy slug collapsed to
+  `-` (spaces, underscores) no longer evict each other from the index (#717).
+  The handalized-path migration now skips any row whose path is still owned by
+  a file in the current scan, so it only adopts genuinely stale pre-2.6 rows.
+  `qmd get` and `qmd ls <prefix>` also match `_` and `%` in paths literally
+  instead of as SQL `LIKE` wildcards, so `qmd get 2026_06_16.md` no longer
+  returns a sibling `2026-06-16.md`.
+
+- CLI `multi-get` and SDK/MCP `multi_get` now share one comma-list resolver.
+  Collection-prefixed paths (`qmd/docs/SYNTAX.md`) work in both transports,
+  unanchored `LIKE '%name'` no longer silently fetches a different document
+  for a filename fragment (`NTAX.md` ≠ `SYNTAX.md`), and ambiguous names
+  across collections error with the candidate list instead of `LIMIT 1` (#759).
+
+- The Nix flake wrapper now seeds the same pre-import env as `bin/qmd`.
+  Nix installs exec `bun src/cli/qmd.ts` directly, so they previously skipped
+  the launcher: `qmd mcp` could leak llama/ggml native logs onto JSON-RPC
+  stdio, and Darwin CLI exits dumped a ggml Metal residency-set stack trace
+  after an otherwise successful query. The wrapper now quiets those logs for
+  `mcp` and sets `GGML_METAL_NO_RESIDENCY=1` on Darwin unless
+  `QMD_METAL_KEEP_RESIDENCY=1` (#723).
+
+- Rerank context creation no longer swallows the real failure. A VRAM OOM or
+  corrupt model previously produced only `Reranker unavailable — skipping
+  reranking` (and a dead identical retry whose comment claimed it disabled
+  flash attention, which ranking contexts never supported). The warning now
+  includes the underlying message so the two cases are distinguishable (#782).
+
+- The Nix flake package now ships `skills/` next to `src/` in `$out/lib/qmd/`.
+  `findPackageRoot()` walks up from the wrapped `src/cli/qmd.ts` looking for a
+  sibling `skills/` directory; without it, `qmd skill show` and `qmd skills list`
+  always failed with "QMD skill not found" on Nix-installed binaries (#722).
+
+- `/release` step 1 no longer points at a missing script. `skills/release/scripts/release-context.sh`
+  now exists: it silently installs git hooks and prints version info, working-tree
+  status, commits and files since the last tag, `[Unreleased]`, and the previous
+  changelog entry. The skill's process list also drops the duplicate step 7 and
+  checks dependency updates before cutting the release (#796).
+
+- `store.searchVec()` (and SDK `searchVector()`) now embed the query with the
+  store's pinned embed model instead of the global `QMD_EMBED_MODEL`. A store
+  created with a non-default `models.embed` previously failed with
+  `Dimension mismatch ... Expected N ... received M` and loaded the wrong
+  (often much larger) model at query time. Hybrid/precomputed/session search
+  paths were unaffected and stay unchanged (#690).
+
+- `qmd collection add --mask "a.md,*.txt"` now indexes the union of each
+  pattern. The comma-separated form was documented and commonly guessed, but
+  the joined string was passed to fast-glob as one literal glob, so it
+  matched zero files with no error. Brace form `{a.md,*.txt}` is unchanged.
+  The same split applies on `qmd update` for stored comma-list masks (#557).
+
+- NixOS / immutable-root installs no longer crash `qmd embed` with EACCES
+  when node-llama-cpp tries to compile llama.cpp into a read-only
+  `node_modules`. The flake wrapper puts Nix's glibc and libstdc++ on
+  `LD_LIBRARY_PATH` so prebuilt binaries can `dlopen` them, and
+  `getLlama()` uses `build: "never"` when the llama directory is not
+  writable (#574).
+
+- CJK FTS rebuild no longer raises "database is busy" when flushing insert
+  batches. The streaming `.iterate()` cursor stayed open across
+  `BEGIN` on the same connection; the scan now uses keyset-paginated
+  `LIMIT` batches so each SELECT finalizes before the insert transaction
+  starts (#797).
+
+- Quoted FTS phrases containing dotted tokens (e.g. `"1.0.21"`) now match the
+  indexed document. The porter unicode61 tokenizer stores dotted strings as
+  adjacent parts, but phrase sanitization stripped the dots into a single
+  token (`1021`) that could never hit. Dotted tokens inside quotes are split
+  into adjacent phrase terms, matching the bare-term rewrite from #563 (#757).
+
+- `scripts/build.mjs` no longer passes `shell: true` to `spawnSync` on Windows.
+  With the default Node install path (`C:\Program Files\nodejs\node.exe`),
+  `cmd.exe` split the unquoted `process.execPath` at the space, the `tsc`
+  spawn failed, and `prepare` could still report success with no `dist/` —
+  leaving `bin/qmd` at "not built". The helper always receives a real binary
+  path plus an args array, so no shell is needed. A spawn error now prints
+  the missing binary path instead of failing silently. (#681)
+
+- Case-sensitive collections no longer collapse distinct document identities that
+  differ only by path casing. The implicit `COLLATE NOCASE` legacy migration was
+  unsafe for filesystems that contain both `README.md` and `readme.md`; case-only
+  legacy migrations must now be explicit and operator-reviewed (#801).
+
+- `cleanupOrphanedVectors` now runs its orphan count and both DELETEs in a
+  single immediate transaction. An interruption between the two DELETEs
+  (crash, `SQLITE_BUSY`) could desync `vectors_vec` from `content_vectors`,
+  leaving stale metadata rows that make a later reactivation of the same
+  content hash look already-embedded — so `qmd embed` skips it and the
+  document becomes silently unsearchable by vector, with no orphan left to
+  clean up (#766).
+
+- `qmd embed` no longer splits a UTF-16 surrogate pair (emoji, etc.) across a
+  chunk boundary. A chunk ending or starting mid-pair produced an unpaired
+  surrogate in the chunk text, which some remote embedding APIs reject as
+  invalid JSON — permanently failing that chunk on every retry, since the
+  boundary calculation is deterministic. This covers both the character-based
+  chunker and `chunkDocumentByTokens`'s recursive re-splitting for
+  astral-plane-dense content, which could previously drive the char budget
+  low enough to reproduce the same split (#777).
+
+- `insertContext` looks up `store_collections` by name. #754 retargeted the
+  query from the dropped `collections` table but left `WHERE id = ?`, and
+  `store_collections` has `name TEXT PRIMARY KEY` with no `id` column — the
+  call threw `no such column: id`. Matches `deleteContext` /
+  `updateStoreContext` (#853).
+
+- `qmd collection add` with no path argument now errors with usage instead of
+  silently indexing the current working directory (#684). Pass `.` to index
+  CWD, matching the documented examples.
+
+- `qmd status` reports orphaned embedding chunks, `qmd update` hints when they
+  exceed 10% of vectors, and `qmd cleanup --dry-run` previews what would be
+  removed. Incremental update still does not auto-prune vectors (a transient
+  empty mount would otherwise force a full re-embed) (#768).
+
+- `qmd --index <name> mcp --http --daemon` now scopes PID/log files per index
+  (`mcp-<name>.pid`) and passes the resolved database path to the child, so a
+  named-index daemon no longer collides with the default `mcp.pid` or opens
+  the default store (#772).
+
+- Opening a store no longer throws `SQLiteError: no such column: T.name` when
+  `documents_fts` is still the legacy `fts5(name, body, content='documents')`
+  schema. `CREATE VIRTUAL TABLE IF NOT EXISTS` left that table in place, and
+  the CJK FTS rebuild's `DELETE FROM documents_fts` compiled against
+  `documents.name`, which does not exist (#792).
+
+- Rerank cache keys now include the resolved `models.rerank` URI, so swapping
+  the configured reranker no longer serves the previous model's cached scores
+  (#764).
+
+- `vsearch -c <collection>` no longer returns empty results for small
+  collections crowded out of the global ANN candidate pool. `searchVec` now
+  exact-scans the collection's vectors with `vec_distance_cosine` when the
+  set is within 20k rows (ANN + post-filter cannot see collections that never
+  enter global top-k, and sqlite-vec caps `k` at 4096 so a larger multiplier
+  alone is not enough). Larger collections still use capped ANN over-fetch
+  (#791, #803).
+
+- `multi-get --format files` now emits the docid as its own CSV field
+  (`#docid,path,...`) instead of prepending it into the path field with a
+  space (`#docid path,...`), matching `search --format files` and keeping
+  naive comma-splitting usable (#760).
+
+- `qmd embed` now takes an exclusive process lock (`.qmd-embed.lock` next to
+  the index DB) so concurrent invocations no longer race on `vectors_vec`
+  and fail with `UNIQUE constraint failed: vectors_vec.hash_seq`. A second
+  embed exits early with `Another embed process is already running. Skipping.`
+  Stale locks from crashed processes are recovered via PID identity checks
+  (#825).
+
+- windows prepare fix #778 keeps dist build #824
+
+- `qmd mcp` (stdio) now shuts down gracefully when stdin reaches EOF instead
+  of orphaning to PID 1 when the parent MCP client dies (#751): the server
+  closes its transport, gives in-flight request handlers a bounded window to
+  settle, closes the store (which disposes its llama.cpp instance), and lets
+  the process drain via `process.exitCode` (no forced `process.exit()`, which
+  has caused exit-time native crashes before).
+
+- `qmd --version` no longer reports an unrelated repository's commit (#787).
+  The commit was discovered at runtime with `git -C <installDir> rev-parse`,
+  and `git -C` walks *up*, so any install nested inside another checkout
+  reported that checkout's HEAD — a global npm install under a git-managed
+  prefix such as Homebrew's `/opt/homebrew` claimed Homebrew's commit as
+  qmd's. Identical tarballs reported different "commits" depending only on
+  where they were installed, which is why one issue can collect three distinct
+  hashes for the same published build. `scripts/build.mjs` now stamps the
+  commit it built from into `dist/cli/build-info.json` (suffixed `-dirty` when
+  built from a modified tree), and the runtime prefers that. Source checkouts
+  still resolve their own HEAD, but only after confirming the enclosing
+  repository is qmd's; anything else reports no commit rather than a
+  misleading one. The lookup also no longer interpolates the install path into
+  a shell string, so a path containing a space stops silently dropping the
+  commit, and `--version` from a build runs no subprocess at all.
+
+- `qmd doctor` no longer false-positives `.etag` HTTP sidecars (written by
+  `qmd pull` next to each download) as invalid GGUF models. The model-cache
+  check now only inspects real `.gguf` files, so a sidecar that happens to
+  sort before the blob no longer poisons the report. #812
+
+- `qmd mcp stop` and `qmd mcp --http --daemon` now verify that a pidfile PID still belongs to a qmd process before signalling it or refusing to start. Recycled PIDs (common after reboot) are treated as stale: the pidfile is unlinked instead of SIGTERM'ing an unrelated process or blocking daemon start with a false "Already running" error (#806).
+
+- `qmd collection add` now rejects missing paths and regular files before
+  creating collection configuration or index state. The error reports both the
+  received and resolved path so malformed shell arguments can be corrected.
+
+- Claude Code plugin: scope the plugin `source` to `./skills` so installs
+  copy just the skills (~50 KB) instead of the entire repository. Previously a
+  canonical install materialized ~230 MB / 9,000+ items into
+  `~/.claude/plugins/cache/` — including a full npm dependency install
+  triggered by the repo-root `package.json`. Both skills (`qmd` and `release`)
+  still ship, unchanged. (#790)
+
+- Claude Code plugin: releases now bump the plugin version in
+  `.claude-plugin/marketplace.json` in lockstep with `package.json`. The
+  plugin cache is keyed on this version, and it had been stuck at `0.1.0`
+  since February — so installed plugins never received skill updates
+  (users who installed in February are still being served that snapshot
+  today, despite the qmd skill nearly tripling in size since). Also bumps
+  the plugin to `2.6.3` as a one-time catch-up so existing installs pick
+  up the current skill on their next `claude plugin update`. (#789)
+
+### Changed
+
+- `--full-path` no longer degrades silently when a result cannot be resolved on
+  disk (#785). A fallback there means the file moved or was deleted since the
+  last index, so `search`, `query`, `get` and `multi-get` now print a notice to
+  stderr naming how many results fell back and suggesting `qmd update`; stdout
+  stays machine-readable.
+- `search`/`query` now decide per result whether to show the docid under
+  `--full-path`, matching `multi-get` and `get`: a result that resolved shows
+  its on-disk path and no docid, one that did not keeps its `qmd://` URI *and*
+  its docid, so it is still addressable. Previously the docid was dropped for
+  every row whenever the flag was set, leaving unresolved rows with neither a
+  usable path nor an identifier.
+- `search --format csv` always emits the `docid` column, empty for rows that
+  resolved to an on-disk path. Under `--full-path` the header previously
+  dropped the column entirely — which also disagreed with the empty-result
+  header, always printed with `docid`. Column positions are now stable across
+  runs and formats.
+
+## [2.6.3] - 2026-06-24
+
+### Added
+
+- `qmd embed --timeout <minutes>` overrides the embed session's max duration
+  (previously hardcoded to 30 minutes). Use a larger value to let a big index
+  finish in one run, or `--timeout 0` to remove the cap entirely. When the cap is
+  reached, remaining document batches are skipped as before, so re-running
+  `qmd embed` continues where it left off.
+
+### Documentation
+
+- README: added a "Configuring `index.yml`" section documenting the full config
+  schema — `global_context`, `editor_uri`, the `models.embed`/`rerank`/`generate`
+  overrides, and per-collection `path`/`pattern`/`ignore`/`update`/
+  `includeByDefault`/`context` — with file-location rules (`XDG_CONFIG_HOME`,
+  `QMD_CONFIG_DIR`, named `{name}.yml`, project-local `.qmd/index.yml`). Every key
+  is verified against `src/collections.ts` and its consumers. Documents behavior
+  that previously existed only in code, where the absence of docs led contributors
+  to repeatedly re-submit already-shipped model-resolution fixes (#502, #559, #564)
+  and to request config that already works (#645, #678). Added
+  `XDG_CONFIG_HOME`/`QMD_CONFIG_DIR` to the environment-variable table and noted
+  the `index.yml` `models:` / `QMD_EMBED_MODEL` override path in the Model
+  Configuration section.
+- README: expanded the per-collection `update` field into an "Automatic update
+  commands" subsection — the feature the maintainer publicly called under-documented
+  — covering execution via `bash -c` in the collection's directory, the run-then-
+  reindex order, the non-zero-exit abort behavior, and the `qmd collection
+  update-cmd` set/clear shortcut. The `ignore` key now states it is YAML-only (no
+  CLI command) and additive with the un-overridable built-in exclusions.
+- `example-index.yml`: overhauled from three near-identical collections into a
+  fully-commented starter template where each collection demonstrates a distinct
+  feature (hierarchical context, auto-`update`, `ignore` patterns, non-markdown
+  globs, `includeByDefault: false`, and an all-fields example), plus commented
+  `editor_uri`/`models` stubs. README now links to it. Model URIs are intentionally
+  left as placeholders so the template can't drift from the defaults.
+- README: documented collection filtering (`-c` semantics), the `collection
+  show`/`include`/`exclude`/`update-cmd` subcommands, the `--intent`/`--no-rerank`/
+  `-C`/`--full-path` search flags, the `--format <kind>` output selector (with the
+  legacy `--json`/`--csv`/`--md`/`--xml`/`--files` booleans noted as aliases),
+  `vector-search`/`deep-search` aliases, embed
+  memory flags (`--max-docs-per-batch`/`--max-batch-mb`), a sample `--explain`
+  score trace, the `qmd doctor`/`qmd init` commands, the `get` `:from:count`
+  suffix and `--no-line-numbers`, an MCP tool parameter reference, and a
+  Benchmarking section for `qmd bench`.
+- docs/SYNTAX.md: removed the non-existent `q` MCP parameter example (the `query`
+  tool and REST endpoint accept only the `searches` array) and added a Scoping
+  section.
+- README: removed the misleading `qmd update --pull` example. The `--pull` flag is
+  parsed but never consumed (`updateCollections()` ignores it); the real mechanism
+  for running `git pull` before re-indexing is a per-collection `update` command,
+  set via `qmd collection update-cmd`.
+
+### Fixed
+
+- MCP server instructions now tell agents to scope with the plural `collections`
+  parameter (matching the schema). The previous singular `collection` hint led
+  agents to pass a parameter that Zod silently strips, producing unscoped results.
+  The `get` instruction line also now documents the full `file.md:from:count`
+  range suffix instead of only the single-line `file.md:100` offset.
+
+- Filesystem paths with special characters (`#`, `&`, spaces, `[]`, `()`, etc.)
+  now round-trip correctly through index → search → get. Previously
+  `reindexCollection` called `handelize()` on relative paths before storing
+  them, turning `# Meeting - 234232 3432 __ 5.md` into
+  `Meeting-234232-3432-5.md` and making `qmd get <actual-path>`,
+  `qmd get --full-path`, and `qmd ls` return dead or garbled paths. Paths are
+  now stored verbatim. Existing indexes auto-migrate on the next `qmd update`.
+
+- FTS5 search now correctly matches dotted version strings like `2026.4.10`. The
+  `porter unicode61` tokenizer splits on dots (storing `2026`, `4`, `10` as
+  separate tokens), but the query sanitizer was stripping dots and producing
+  `2026410` which never matched. Dotted terms are now split and ANDed together
+  so version-string searches work as expected (#563).
+- HTTP REST endpoints `/query` and `/search` now return `qmd://collection/path`
+  URIs in the `file` field, matching the output format used by the CLI and MCP
+  resource URIs. Previously the raw `displayPath` (`collection/path`) was
+  returned without the scheme prefix (#576).
+- The embed session `maxDuration` is now env-configurable via
+  `QMD_EMBED_MAX_DURATION_MS` (default: 30 min). This prevents large-corpus
+  embeddings from being aborted by the hardcoded 30-minute ceiling (#673).
+- `qmd query`, `qmd update`, and other commands no longer fail with
+  `SQLiteError: database is locked` when multiple processes run against the
+  same index in parallel (e.g. an `update` racing a long `embed`, the
+  first-open schema migration racing a routine command, or an agent fanning
+  out searches). `openDatabase` now sets `PRAGMA busy_timeout = 120000` on
+  every connection, so a writer that loses the race queues at batch
+  boundaries instead of throwing immediately. WAL handles read/write
+  concurrency but does not serialise concurrent writers, and `bun:sqlite`
+  and `better-sqlite3` both default the timeout to 0, so the loser
+  previously failed on the first DDL statement in `initializeDatabase`.
+  Override the default with `QMD_SQLITE_BUSY_TIMEOUT` (milliseconds; `0`
+  restores fail-fast). Two more crashes on the same concurrent-open
+  path are fixed: `trigger documents_ai already exists` (the FTS sync
+  triggers were dropped and recreated as separate statements on every
+  open, so two processes interleaved between the `DROP` and the
+  `CREATE`; `busy_timeout` serialises individual statements but not the
+  pair) and `database is locked` while migrating a cold database to WAL
+  (the `journal_mode` switch needs a brief exclusive lock and does not
+  invoke the busy handler). FTS trigger setup is now gated behind
+  `PRAGMA user_version` inside one `IMMEDIATE` transaction, and the WAL
+  migration retries within the busy-timeout budget.
+
+## [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
+
+## [2.1.0] - 2026-04-05
+
+Code files now chunk at function and class boundaries via tree-sitter,
+clickable editor links land you at the right line from search results,
+and per-collection model configuration means you can point different
+collections at different embedding models. 25+ community PRs fix
+embedding stability, BM25 accuracy, and cross-platform launcher issues.
+
+### Changes
+
+- AST-aware chunking for code files via `web-tree-sitter`. Supported
+  languages: TypeScript/JavaScript, Python, Go, and Rust. Code files
+  are chunked at function, class, and import boundaries instead of
+  arbitrary text positions. Markdown and unknown file types are unchanged.
+  `--chunk-strategy <auto|regex>` flag on `qmd embed` and `qmd query`
+  (default `regex`). SDK: `chunkStrategy` option on `embed()` and
+  `search()`. `qmd status` shows grammar availability.
+- `qmd bench <fixture.json>` command for search quality benchmarks.
+  Measures precision@k, recall, MRR, and F1 across BM25, vector, hybrid,
+  and full pipeline backends. Ships with an example fixture against
+  the eval-docs test collection. #470 (thanks @jmilinovich)
+- `models:` section in `index.yml` lets you configure `embed`, `rerank`,
+  and `generate` model URIs per collection. Resolution order is
+  config > env var (`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL`,
+  `QMD_GENERATE_MODEL`) > built-in default. #502
+  (thanks @JohnRichardEnders)
+- CLI search output now emits clickable OSC 8 terminal hyperlinks when
+  stdout is a TTY. Links resolve `qmd://` paths to absolute filesystem
+  paths and open in editors via URI templates (default:
+  `vscode://file/{path}:{line}:{col}`). Configure with `QMD_EDITOR_URI`
+  or `editor_uri` in the YAML config. #508 (thanks @danmackinlay)
+- `--no-rerank` flag skips the reranking step in `qmd query` — useful
+  when you want fast results or don't have a GPU. Also exposed as
+  `rerank: false` on the MCP `query` tool. #370 (thanks @mvanhorn),
+  #478 (thanks @zestyboy)
+- ONNX conversion script for deploying embedding models via
+  Transformers.js. #399 (thanks @shreyaskarnik)
+- GitHub Actions workflow to build the Nix flake on Linux and macOS.
+
+### Fixes
+
+- Embedding: prevent `qmd embed` from running indefinitely when the
+  embedding loop stalls. #458 (thanks @ccc-fff)
+- Embedding: truncate oversized text before embedding to prevent GGML
+  crash, and bound memory usage during batch embedding. #393
+  (thanks @lskun), #395 (thanks @ProgramCaiCai)
+- Embedding: set explicit embed context size (default 2048, configurable
+  via `QMD_EMBED_CONTEXT_SIZE`) instead of using the model's full
+  window. #500
+- Embedding: error on dimension mismatch instead of silently rebuilding
+  the vec0 table. #501
+- Embedding: handle vec0 `OR REPLACE` limitation in `insertEmbedding`.
+  #456 (thanks @antonio-mello-ai)
+- Embedding: fix model selection when multiple models are configured.
+  #494
+- BM25: correct field weights to include all 3 FTS columns — title,
+  body, and path were not weighted correctly. #462 (thanks @goldsr09)
+- BM25: handle hyphenated tokens in FTS5 lex queries so terms like
+  "real-time" match correctly. #463 (thanks @goldsr09)
+- BM25: preserve underscores in search terms instead of stripping them.
+  #404
+- BM25: use CTE in `searchFTS` to prevent query planner regression with
+  collection filter.
+- Reranker: increase default context size 2048→4096 and make
+  configurable via `QMD_RERANK_CONTEXT_SIZE`. Fix template overhead
+  underestimate 200→512. #453 (thanks @builderjarvis)
+- GPU: catch initialization failures and fall back to CPU instead of
+  crashing.
+- MCP: read version from `package.json` instead of hardcoding. #431
+- MCP: include collection name in status output. #416
+- Multi-get: support brace expansion patterns in glob matching. #424
+- Launcher: prioritize `package-lock.json` to prevent Bun false
+  positive. #385 (thanks @rymalia)
+- Launcher: remove `$BUN_INSTALL` check that caused false Bun detection.
+  #362 (thanks @syedair)
+- Launcher: skip Git Bash path detection on WSL. #371
+  (thanks @oysteinkrog)
+- Model cache: respect `XDG_CACHE_HOME` for model cache directory. #457
+  (thanks @antonio-mello-ai)
+- SQLite: add macOS Homebrew SQLite support for Bun and restore
+  actionable errors. #377 (thanks @serhii12)
+- Pin zod to exact 4.2.1 to fix `tsc` build failure. #382
+  (thanks @rymalia)
+- Preserve dots and original case in `handelize()` — filenames like
+  `MEMORY.md` no longer become `memory-md`. #475 (thanks @alexei-led)
+- Include `line` in `--json` search output so editor integrations can
+  jump directly to `file:line`. #506 (thanks @danmackinlay)
+- Nix: fix paths in flake and make Bun dependency a fixed-output
+  derivation so sandboxed Linux builds work offline. #479
+  (thanks @surma-dump)
+- Sync stale `bun.lock` (`better-sqlite3` 11.x → 12.x). CI and release
+  script now use `--frozen-lockfile` to prevent recurrence. #386
+  (thanks @Mic92)
+- Approve native build scripts in pnpm so `better-sqlite3` and
+  tree-sitter modules compile correctly. Update vitest ^3.0.0 → ^3.2.4.
+
+## [2.0.1] - 2026-03-10
+
+### Changes
+
+- `qmd skill install` copies the packaged QMD skill into
+  `~/.claude/commands/` for one-command setup. #355 (thanks @nibzard)
+
+### Fixes
+
+- Fix Qwen3-Embedding GGUF filename case — HuggingFace filenames are
+  case-sensitive, the lowercase variant returned 404. #349 (thanks @byheaven)
+- Resolve symlinked global launcher path so `qmd` works correctly when
+  installed via `npm i -g`. #352 (thanks @nibzard)
+
+## [2.0.0] - 2026-03-10
+
+QMD 2.0 declares a stable library API. The SDK is now the primary interface —
+the MCP server is a clean consumer of it, and the source is organized into
+`src/cli/` and `src/mcp/`. Also: Node 25 support and a runtime-aware bin wrapper
+for bun installs.
+
+### Changes
+
+- Stable SDK API with `QMDStore` interface — search, retrieval, collection/context
+  management, indexing, lifecycle
+- Unified `search()`: pass `query` for auto-expansion or `queries` for
+  pre-expanded lex/vec/hyde — replaces the old query/search/structuredSearch split
+- New `getDocumentBody()`, `getDefaultCollectionNames()`, `Maintenance` class
+- MCP server rewritten as a clean SDK consumer — zero internal store access
+- CLI and MCP organized into `src/cli/` and `src/mcp/` subdirectories
+- Runtime-aware `bin/qmd` wrapper detects bun vs node to avoid ABI mismatches.
+  Closes #319
+- `better-sqlite3` bumped to ^12.4.5 for Node 25 support. Closes #257
+- Utility exports: `extractSnippet`, `addLineNumbers`, `DEFAULT_MULTI_GET_MAX_BYTES`
+
+### Fixes
+
+- Remove unused `import { resolve }` in store.ts that shadowed local export
+
+## [1.1.6] - 2026-03-09
+
+QMD can now be used as a library. `import { createStore } from '@tobilu/qmd'`
+gives you the full search and indexing API — hybrid query, BM25, structured
+search, collection/context management — without shelling out to the CLI.
+
+### Changes
+
+- **SDK / library mode**: `createStore({ dbPath, config })` returns a
+  `QMDStore` with `query()`, `search()`, `structuredSearch()`, `get()`,
+  `multiGet()`, and collection/context management methods. Supports inline
+  config (no files needed) or a YAML config path.
+- **Package exports**: `package.json` now declares `main`, `types`, and
+  `exports` so bundlers and TypeScript resolve `@tobilu/qmd` correctly.
+
+## [1.1.5] - 2026-03-07
+
+Ambiguous queries like "performance" now produce dramatically better results
+when the caller knows what they mean. The new `intent` parameter steers all
+five pipeline stages — expansion, strong-signal bypass, chunk selection,
+reranking, and snippet extraction — without searching on its own. Design and
+original implementation by Ilya Grigorik (@vyalamar) in #180.
+
+### Changes
+
+- **Intent parameter**: optional `intent` string disambiguates queries across
+  the entire search pipeline. Available via CLI (`--intent` flag or `intent:`
+  line in query documents), MCP (`intent` field on the query tool), and
+  programmatic API. Adapted from PR #180 (thanks @vyalamar).
+- **Query expansion**: when intent is provided, the expansion LLM prompt
+  includes `Query intent: {intent}`, matching the finetune training data
+  format for better-aligned expansions.
+- **Reranking**: intent is prepended to the rerank query so Qwen3-Reranker
+  scores with domain context.
+- **Chunk selection**: intent terms scored at 0.5× weight alongside query
+  terms (1.0×) when selecting the best chunk per document for reranking.
+- **Snippet extraction**: intent terms scored at 0.3× weight to nudge
+  snippets toward intent-relevant lines without overriding query anchoring.
+- **Strong-signal bypass disabled with intent**: when intent is provided, the
+  BM25 strong-signal shortcut is skipped — the obvious keyword match may not
+  be what the caller wants.
+- **MCP instructions**: callers are now guided to provide `intent` on every
+  search call for disambiguation.
+- **Query document syntax**: `intent:` recognized as a line type. At most one
+  per document, cannot appear alone. Grammar updated in `docs/SYNTAX.md`.
+
+## [1.1.2] - 2026-03-07
+
+13 community PRs merged. GPU initialization replaced with node-llama-cpp's
+built-in `autoAttempt` — deleting ~220 lines of manual fallback code and
+fixing GPU issues reported across 10+ PRs in one shot. Reranking is faster
+through chunk deduplication and a parallelism cap that prevents VRAM
+exhaustion.
+
+### Changes
+
+- **GPU init**: use node-llama-cpp's `build: "autoAttempt"` instead of manual
+  GPU backend detection. Automatically tries Metal/CUDA/Vulkan and falls back
+  gracefully. #310 (thanks @giladgd — the node-llama-cpp author)
+- **Query `--explain`**: `qmd query --explain` exposes retrieval score traces
+  — backend scores, per-list RRF contributions, top-rank bonus, reranker
+  score, and final blended score. Works in JSON and CLI output. #242
+  (thanks @vyalamar)
+- **Collection ignore patterns**: `ignore: ["Sessions/**", "*.tmp"]` in
+  collection config to exclude files from indexing. #304 (thanks @sebkouba)
+- **Multilingual embeddings**: `QMD_EMBED_MODEL` env var lets you swap in
+  models like Qwen3-Embedding for non-English collections. #273 (thanks
+  @daocoding)
+- **Configurable expansion context**: `QMD_EXPAND_CONTEXT_SIZE` env var
+  (default 2048) — previously used the model's full 40960-token window,
+  wasting VRAM. #313 (thanks @0xble)
+- **`candidateLimit` exposed**: `-C` / `--candidate-limit` flag and MCP
+  parameter to tune how many candidates reach the reranker. #255 (thanks
+  @pandysp)
+- **MCP multi-session**: HTTP transport now supports multiple concurrent
+  client sessions, each with its own server instance. #286 (thanks @joelev)
+
+### Fixes
+
+- **Reranking performance**: cap parallel rerank contexts at 4 to prevent
+  VRAM exhaustion on high-core machines. Deduplicate identical chunk texts
+  before reranking — same content from different files now shares a single
+  reranker call. Cache scores by content hash instead of file path.
+- Deactivate stale docs when all files are removed from a collection and
+  `qmd update` is run. #312 (thanks @0xble)
+- Handle emoji-only filenames (`🐘.md` → `1f418.md`) instead of crashing.
+  #308 (thanks @debugerman)
+- Skip unreadable files during indexing (e.g. iCloud-evicted files returning
+  EAGAIN) instead of crashing. #253 (thanks @jimmynail)
+- Suppress progress bar escape sequences when stderr is not a TTY. #230
+  (thanks @dgilperez)
+- Emit format-appropriate empty output (`[]` for JSON, CSV header for CSV,
+  etc.) instead of plain text "No results." #228 (thanks @amsminn)
+- Correct Windows sqlite-vec package name (`sqlite-vec-windows-x64`) and add
+  `sqlite-vec-linux-arm64`. #225 (thanks @ilepn)
+- Fix claude plugin setup CLI commands in README. #311 (thanks @gi11es)
+
+## [1.1.1] - 2026-03-06
+
+### Fixes
+
+- Reranker: truncate documents exceeding the 2048-token context window
+  instead of silently producing garbage scores. Long chunks (e.g. from
+  PDF ingestion) now get a fair ranking.
+- Nix: add python3 and cctools to build dependencies. #214 (thanks
+  @pcasaretto)
+
+## [1.1.0] - 2026-02-20
+
+QMD now speaks in **query documents** — structured multi-line queries where every line is typed (`lex:`, `vec:`, `hyde:`), combining keyword precision with semantic recall. A single plain query still works exactly as before (it's treated as an implicit `expand:` and auto-expanded by the LLM). Lex now supports quoted phrases and negation (`"C++ performance" -sports -athlete`), making intent-aware disambiguation practical. The formal query grammar is documented in `docs/SYNTAX.md`.
+
+The npm package now uses the standard `#!/usr/bin/env node` bin convention, replacing the custom bash wrapper. This fixes native module ABI mismatches when installed via bun and works on any platform with node >= 22 on PATH.
+
+### Changes
+
+- **Query document format**: multi-line queries with typed sub-queries (`lex:`, `vec:`, `hyde:`). Plain queries remain the default (`expand:` implicit, but not written inside the document). First sub-query gets 2× fusion weight — put your strongest signal first. Formal grammar in `docs/SYNTAX.md`.
+- **Lex syntax**: full BM25 operator support. `"exact phrase"` for verbatim matching; `-term` and `-"phrase"` for exclusions. Essential for disambiguation when a term is overloaded across domains (e.g. `performance -sports -athlete`).
+- **`expand:` shortcut**: send a single plain query (or start the document with `expand:` on its only line) to auto-expand via the local LLM. Query documents themselves are limited to `lex`, `vec`, and `hyde` lines.
+- **MCP `query` tool** (renamed from `structured_search`): rewrote the tool description to fully teach AI agents the query document format, lex syntax, and combination strategy. Includes worked examples with intent-aware lex.
+- **HTTP `/query` endpoint** (renamed from `/search`; `/search` kept as silent alias).
+- **`collections` array filter**: filter by multiple collections in a single query (`collections: ["notes", "brain"]`). Removed the single `collection` string param — array only.
+- **Collection `include`/`exclude`**: `includeByDefault: false` hides a collection from all queries unless explicitly named via `collections`. CLI: `qmd collection exclude <name>` / `qmd collection include <name>`.
+- **Collection `update-cmd`**: attach a shell command that runs before every `qmd update` (e.g. `git stash && git pull --rebase --ff-only && git stash pop`). CLI: `qmd collection update-cmd <name> '<cmd>'`.
+- **`qmd status` tips**: shows actionable tips when collections lack context descriptions or update commands.
+- **`qmd collection` subcommands**: `show`, `update-cmd`, `include`, `exclude`. Bare `qmd collection` now prints help.
+- **Packaging**: replaced custom bash wrapper with standard `#!/usr/bin/env node` shebang on `dist/qmd.js`. Fixes native module ABI mismatches when installed via bun, and works on any platform where node >= 22 is on PATH.
+- **Removed MCP tools** `search`, `vector_search`, `deep_search` — all superseded by `query`.
+- **Removed** `qmd context check` command.
+- **CLI timing**: each LLM step (expand, embed, rerank) prints elapsed time inline (`Expanding query... (4.2s)`).
+
+### Fixes
+
+- `qmd collection list` shows `[excluded]` tag for collections with `includeByDefault: false`.
+- Default searches now respect `includeByDefault` — excluded collections are skipped unless explicitly named.
+- Fix main module detection when installed globally via npm/bun (symlink resolution).
+
+## [1.0.7] - 2026-02-18
+
+### Changes
+
+- LLM: add LiquidAI LFM2-1.2B as an alternative base model for query
+  expansion fine-tuning. LFM2's hybrid architecture (convolutions + attention)
+  is 2x faster at decode/prefill vs standard transformers — good fit for
+  on-device inference.
+- CLI: support multiple `-c` flags to search across several collections at
+  once (e.g. `qmd search -c notes -c journals "query"`). #191 (thanks
+  @openclaw)
+
+### Fixes
+
+- Return empty JSON array `[]` instead of no output when `--json` search
+  finds no results.
+- Resolve relative paths passed to `--index` so they don't produce malformed
+  config entries.
+- Respect `XDG_CONFIG_HOME` for collection config path instead of always
+  using `~/.config`. #190 (thanks @openclaw)
+- CLI: empty-collection hint now shows the correct `collection add` command.
+  #200 (thanks @vincentkoc)
+
+## [1.0.6] - 2026-02-16
+
+### Changes
+
+- CLI: `qmd status` now shows models with full HuggingFace links instead of
+  static names in `--help`. Model info is derived from the actual configured
+  URIs so it stays accurate if models change.
+- Release tooling: pre-push hook handles non-interactive shells (CI, editors)
+  gracefully — warnings auto-proceed instead of hanging on a tty prompt.
+  Annotated tags now resolve correctly for CI checks.
+
+## [1.0.5] - 2026-02-16
+
+The npm package now ships compiled JavaScript instead of raw TypeScript,
+removing the `tsx` runtime dependency. A new `/release` skill automates the
+full release workflow with changelog validation and git hook enforcement.
+
+### Changes
+
+- Build: compile TypeScript to `dist/` via `tsc` so the npm package no longer
+  requires `tsx` at runtime. The `qmd` shell wrapper now runs `dist/qmd.js`
+  directly.
+- Release tooling: new `/release` skill that manages the full release
+  lifecycle — validates changelog, installs git hooks, previews release notes,
+  and cuts the release. Auto-populates `[Unreleased]` from git history when
+  empty.
+- Release tooling: `scripts/extract-changelog.sh` extracts cumulative notes
+  for the full minor series (e.g. 1.0.0 through 1.0.5) for GitHub releases.
+  Includes `[Unreleased]` content in previews.
+- Release tooling: `scripts/release.sh` renames `[Unreleased]` to a versioned
+  heading and inserts a fresh empty `[Unreleased]` section automatically.
+- Release tooling: pre-push git hook blocks `v*` tag pushes unless
+  `package.json` version matches the tag, a changelog entry exists, and CI
+  passed on GitHub.
+- Publish workflow: GitHub Actions now builds TypeScript, creates a GitHub
+  release with cumulative notes extracted from the changelog, and publishes
+  to npm with provenance.
+
+## [1.0.0] - 2026-02-15
+
+QMD now runs on both Node.js and Bun, with up to 2.7x faster reranking
+through parallel GPU contexts. GPU auto-detection replaces the unreliable
+`gpu: "auto"` with explicit CUDA/Metal/Vulkan probing.
+
+### Changes
+
+- Runtime: support Node.js (>=22) alongside Bun via a cross-runtime SQLite
+  abstraction layer (`src/db.ts`). `bun:sqlite` on Bun, `better-sqlite3` on
+  Node. The `qmd` wrapper auto-detects a suitable Node.js install via PATH,
+  then falls back to mise, asdf, nvm, and Homebrew locations.
+- Performance: parallel embedding & reranking via multiple LlamaContext
+  instances — up to 2.7x faster on multi-core machines.
+- Performance: flash attention for ~20% less VRAM per reranking context,
+  enabling more parallel contexts on GPU.
+- Performance: right-sized reranker context (40960 → 2048 tokens, 17x less
+  memory) since chunks are capped at ~900 tokens.
+- Performance: adaptive parallelism — context count computed from available
+  VRAM (GPU) or CPU math cores rather than hardcoded.
+- GPU: probe for CUDA, Metal, Vulkan explicitly at startup instead of
+  relying on node-llama-cpp's `gpu: "auto"`. `qmd status` shows device info.
+- Tests: reorganized into flat `test/` directory with vitest for Node.js and
+  bun test for Bun. New `eval-bm25` and `store.helpers.unit` suites.
+
+### Fixes
+
+- Prevent VRAM waste from duplicate context creation during concurrent
+  `embedBatch` calls — initialization lock now covers the full path.
+- Collection-aware FTS filtering so scoped keyword search actually restricts
+  results to the requested collection.
+
+## [0.9.0] - 2026-02-15
+
+First published release on npm as `@tobilu/qmd`. MCP HTTP transport with
+daemon mode cuts warm query latency from ~16s to ~10s by keeping models
+loaded between requests.
+
+### Changes
+
+- MCP: HTTP transport with daemon lifecycle — `qmd mcp --http --daemon`
+  starts a background server, `qmd mcp stop` shuts it down. Models stay warm
+  in VRAM between queries. #149 (thanks @igrigorik)
+- Search: type-routed query expansion preserves lex/vec/hyde type info and
+  routes to the appropriate backend. Eliminates ~4 wasted backend calls per
+  query (10.0 → 6.0 calls, 1278ms → 549ms). #149 (thanks @igrigorik)
+- Search: unified pipeline — extracted `hybridQuery()` and
+  `vectorSearchQuery()` to `store.ts` so CLI and MCP share identical logic.
+  Fixes a class of bugs where results differed between the two. #149 (thanks
+  @igrigorik)
+- MCP: dynamic instructions generated at startup from actual index state —
+  LLMs see collection names, doc counts, and content descriptions. #149
+  (thanks @igrigorik)
+- MCP: tool renames (vsearch → vector_search, query → deep_search) with
+  rewritten descriptions for better tool selection. #149 (thanks @igrigorik)
+- Integration: Claude Code plugin with inline status checks and MCP
+  integration. #99 (thanks @galligan)
+
+### Fixes
+
+- BM25 score normalization — formula was inverted (`1/(1+|x|)` instead of
+  `|x|/(1+|x|)`), so strong matches scored *lowest*. Broke `--min-score`
+  filtering and made the "strong signal" short-circuit dead code. #76 (thanks
+  @dgilperez)
+- Normalize Unicode paths to NFC for macOS compatibility. #82 (thanks
+  @c-stoeckl)
+- Handle dense content (code) that tokenizes beyond expected chunk size.
+- Proper cleanup of Metal GPU resources on process exit.
+- SQLite-vec readiness verification after extension load.
+- Reactivate deactivated documents on re-index instead of creating duplicates.
+- Bun UTF-8 path corruption workaround for non-ASCII filenames.
+- Disable following symlinks in glob.scan to avoid infinite loops.
+
+## [0.8.0] - 2026-01-28
+
+Fine-tuned query expansion model trained with GRPO replaces the stock Qwen3
+0.6B. The training pipeline scores expansions on named entity preservation,
+format compliance, and diversity — producing noticeably better lexical
+variations and HyDE documents.
+
+### Changes
+
+- LLM: deploy GRPO-trained (Group Relative Policy Optimization) query
+  expansion model, hosted on HuggingFace and auto-downloaded on first use.
+  Better preservation of proper nouns and technical terms in expansions.
+- LLM: `/only:lex` mode for single-type expansions — useful when you know
+  which search backend will help.
+- LLM: HyDE output moved to first position so vector search can start
+  embedding while other expansions generate.
+- LLM: session lifecycle management via `withLLMSession()` pattern — ensures
+  cleanup even on failure, similar to database transactions.
+- Integration: org-mode title extraction support. #50 (thanks @sh54)
+- Integration: SQLite extension loading in Nix devshell. #48 (thanks @sh54)
+- Integration: AI agent discovery via skills.sh. #64 (thanks @Algiras)
+
+### Fixes
+
+- Use sequential embedding on CPU-only systems — parallel contexts caused a
+  race condition where contexts competed for CPU cores, making things slower.
+  #54 (thanks @freeman-jiang)
+- Fix `collectionName` column in vector search SQL (was still using old
+  `collectionId` from before YAML migration). #61 (thanks @jdvmi00)
+- Fix Qwen3 sampling params to prevent repetition loops — stock
+  temperature/top-p caused occasional infinite repeat patterns.
+- Add `--index` option to CLI argument parser (was documented but not wired
+  up). #84 (thanks @Tritlo)
+- Fix DisposedError during slow batch embedding. #41 (thanks @wuhup)
+
+## [0.7.0] - 2026-01-09
+
+First community contributions. The project gained external contributors,
+surfacing bugs that only appear in diverse environments — Homebrew sqlite-vec
+paths, case-sensitive model filenames, and sqlite-vec JOIN incompatibilities.
+
+### Changes
+
+- Indexing: native `realpathSync()` replaces `readlink -f` subprocess spawn
+  per file. On a 5000-file collection this eliminates 5000 shell spawns,
+  ~15% faster. #8 (thanks @burke)
+- Indexing: single-pass tokenization — chunking algorithm tokenized each
+  document twice (count then split); now tokenizes once and reuses. #9
+  (thanks @burke)
+
+### Fixes
+
+- Fix `vsearch` and `query` hanging — sqlite-vec's virtual table doesn't
+  support the JOIN pattern used; rewrote to subquery. #23 (thanks @mbrendan)
+- Fix MCP server exiting immediately after startup — process had no active
+  handles keeping the event loop alive. #29 (thanks @mostlydev)
+- Fix collection filter SQL to properly restrict vector search results.
+- Support non-ASCII filenames in collection filter.
+- Skip empty files during indexing instead of crashing on zero-length content.
+- Fix case sensitivity in Qwen3 model filename resolution. #15 (thanks
+  @gavrix)
+- Fix sqlite-vec loading on macOS with Homebrew (`BREW_PREFIX` detection).
+  #42 (thanks @komsit37)
+- Fix Nix flake to use correct `src/qmd.ts` path. #7 (thanks @burke)
+- Fix docid lookup with quotes support in get command. #36 (thanks
+  @JoshuaLelon)
+- Fix query expansion model size in documentation. #38 (thanks @odysseus0)
+
+## [0.6.0] - 2025-12-28
+
+Replaced Ollama HTTP API with node-llama-cpp for all LLM operations. Ollama
+adds convenience but also a running server dependency. node-llama-cpp loads
+GGUF models directly in-process — zero external dependencies. Models
+auto-download from HuggingFace on first use.
+
+### Changes
+
+- LLM: structured query expansion via JSON schema grammar constraints.
+  Model produces typed expansions — **lexical** (BM25 keywords), **vector**
+  (semantic rephrasings), **HyDE** (hypothetical document excerpts) — so each
+  routes to the right backend instead of sending everything everywhere.
+- LLM: lazy model loading with 2-minute inactivity auto-unload. Keeps memory
+  low when idle while avoiding ~3s model load on every query.
+- Search: conditional query expansion — when BM25 returns strong results, the
+  expensive LLM expansion is skipped entirely.
+- Search: multi-chunk reranking — documents with multiple relevant chunks
+  scored by aggregating across all chunks rather than best single chunk.
+- Search: cosine distance for vector search (was L2).
+- Search: embeddinggemma nomic-style prompt formatting.
+- Testing: evaluation harness with synthetic test documents and Hit@K metrics
+  for BM25, vector, and hybrid RRF.
+
+## [0.5.0] - 2025-12-13
+
+Collections and contexts moved from SQLite tables to YAML at
+`~/.config/qmd/index.yml`. SQLite was overkill for config — you can't share
+it, and it's opaque. YAML is human-readable and version-controllable. The
+migration was extensive (35+ commits) because every part of the system that
+touched collections or contexts had to be updated.
+
+### Changes
+
+- Config: YAML-based collections and contexts replace SQLite tables.
+  `collections` and `path_contexts` tables dropped from schema. Collections
+  support an optional `update:` command (e.g., `git pull`) before re-index.
+- CLI: `qmd collection add/list/remove/rename` commands with `--name` and
+  `--mask` glob pattern support.
+- CLI: `qmd ls` virtual file tree — list collections, files in a collection,
+  or files under a path prefix.
+- CLI: `qmd context add/list/check/rm` with hierarchical context inheritance.
+  A query to `qmd://notes/2024/jan/` inherits context from `notes/`,
+  `notes/2024/`, and `notes/2024/jan/`.
+- CLI: `qmd context add / "text"` for global context across all collections.
+- CLI: `qmd context check` audit command to find paths without context.
+- Paths: `qmd://` virtual URI scheme for portable document references.
+  `qmd://notes/ideas.md` works regardless of where the collection lives on
+  disk. Works in `get`, `multi-get`, `ls`, and context commands.
+- CLI: document IDs (docid) — first 6 chars of content hash for stable
+  references. Shown as `#abc123` in search results, usable with `get` and
+  `multi-get`.
+- CLI: `--line-numbers` flag for get command output.
+
+## [0.4.0] - 2025-12-10
+
+MCP server for AI agent integration. Without it, agents had to shell out to
+`qmd search` and parse CLI output. The monolithic `qmd.ts` (1840 lines) was
+split into focused modules with the project's first test suite (215 tests).
+
+### Changes
+
+- MCP: stdio server with tools for search, vector search, hybrid query,
+  document retrieval, and status. Runs over stdio transport for Claude
+  Desktop and MCP clients.
+- MCP: spec-compliant with June 2025 MCP specification — removed non-spec
+  `mimeType`, added `isError: true` to errors, `structuredContent` for
+  machine-readable results, proper URI encoding.
+- MCP: simplified tool naming (`qmd_search` → `search`) since MCP already
+  namespaces by server.
+- Architecture: extract `store.ts` (1221 LOC), `llm.ts` (539 LOC),
+  `formatter.ts` (359 LOC), `mcp.ts` (503 LOC) from monolithic `qmd.ts`.
+- Testing: 215 tests (store: 96, llm: 60, mcp: 59) with mocked Ollama for
+  fast, deterministic runs. Before this: zero tests.
+
+## [0.3.0] - 2025-12-08
+
+Document chunking for vector search. A 5000-word document about many topics
+gets a single embedding that averages everything together, matching poorly for
+specific queries. Chunking produces one embedding per ~900-token section with
+focused semantic signal.
+
+### Changes
+
+- Search: markdown-aware chunking — prefers heading boundaries, then paragraph
+  breaks, then sentence boundaries. 15% overlap between chunks ensures
+  cross-boundary queries still match.
+- Search: multi-chunk scoring bonus (+0.02 per additional chunk, capped at
+  +0.1 for 5+ chunks). Documents relevant in multiple sections rank higher.
+- CLI: display paths show collection-relative paths and extracted titles
+  (from H1 headings or YAML frontmatter) instead of raw filesystem paths.
+- CLI: `--all` flag returns all matches (use with `--min-score` to filter).
+- CLI: byte-based progress bar with ETA for `embed` command.
+- CLI: human-readable time formatting ("15m 4s" instead of "904.2s").
+- CLI: documents >64KB truncated with warning during embedding.
+
+## [0.2.0] - 2025-12-08
+
+### Changes
+
+- CLI: `--json`, `--csv`, `--files`, `--md`, `--xml` output format flags.
+  `--json` for programmatic access, `--files` for piping, `--md`/`--xml` for
+  LLM consumption, `--csv` for spreadsheets.
+- CLI: `qmd status` shows index health — document count, size, embedding
+  coverage, time since last update.
+- Search: weighted RRF — original query gets 2x weight relative to expanded
+  queries since the user's actual words are a more reliable signal.
+
+## [0.1.0] - 2025-12-07
+
+Initial implementation. Built in a single day for searching personal markdown
+notes, journals, and meeting transcripts.
+
+### Changes
+
+- Search: SQLite FTS5 with BM25 ranking. Chose SQLite over Elasticsearch
+  because QMD is a personal tool — single binary, no server dependencies.
+- Search: sqlite-vec for vector similarity. Same rationale: in-process, no
+  external vector database.
+- Search: Reciprocal Rank Fusion to combine BM25 and vector results. RRF is
+  parameter-free and handles missing signals gracefully.
+- LLM: Ollama for embeddings, reranking, and query expansion. Later replaced
+  with node-llama-cpp in 0.6.0.
+- CLI: `qmd add`, `qmd embed`, `qmd search`, `qmd vsearch`, `qmd query`,
+  `qmd get`. ~1800 lines of TypeScript in a single `qmd.ts` file.
+
+[Unreleased]: https://github.com/tobi/qmd/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/tobi/qmd/releases/tag/v1.0.0
+[0.9.0]: https://github.com/tobi/qmd/compare/v0.8.0...v0.9.0