ko-qmd 2.8.3-ko.2 → 2.8.3-ko.4

package/CHANGELOG.md

@@ -2,6 +2,259 @@
 
 ## [Unreleased]
 
+## [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 `lemon-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

package/README.ko.md

@@ -4,18 +4,23 @@
 
 - 패키지 이름: `ko-qmd` (npm 발행 — `v*` 태그 push 가 `publish.yml` 로 발행)
 - 버전 규칙: `<업스트림 버전>-ko.N` (예: `2.8.3-ko.0`)
-- 브랜치: `main` = 배포 브랜치(업스트림 릴리스 + 한국어 패치 스택). 업스트림은 `upstream` 원격으로만 따라간다 — 포크가 아니다.
+- 브랜치: `develop` = 작업 브랜치(PR 은 여기로), `main` = 배포 브랜치(develop 을 머지한 뒤 `/release` 로 태그 → `publish.yml` 이 `NPM_TOKEN` 시크릿으로 발행). 업스트림은 `upstream` 원격으로만 따라간다 — 포크가 아니다.
 
 ## 업스트림과 다른 점
 
 1. 패키징: 이름·repository·플러그인 marketplace owner, `publish.yml` 은 `ko-qmd` 로 발행, CI에 `windows-latest`와 Electron 스모크 잡 추가
 2. Hangul FTS (`src/hangul.ts`, `store.ts` 접점 2곳)
    - 질의: 따옴표 없는 한글 단어는 끝 조사 하나 또는 `기`를 뗀 어간도 매칭한다(`검색을` → `검색`, 어간 2음절 이상). 따옴표 구문·한자·가나는 그대로.
+   - 외래어 다리: 기술 용어의 한글 외래어 표기(`서치`·`웹`·`코어`·`마이그레이션` 등 약 80개, `hangul.ts` 내장 표)는 영문 표기를 OR 로 함께 찾는다(`하이브리드 서치` → `hybrid search`). 어간에도 적용(`서치를` → `search`), 영문과 붙은 한글 구간도(`qmd서치`). 붙여 쓴 한글 복합어(`레몬웹코어`)와 1음절 항목에 조사가 붙은 꼴(`웹을`)은 대상 아님. 질의 쪽만 바뀌므로 재색인 불필요.
    - 색인: 한글 구간의 음절 bigram을 필드 끝에 덧붙인다. `FTS_CJK_NORMALIZED_VERSION`이 `"2"`라 기존 인덱스는 처음 열 때 FTS를 한 번 다시 만든다.
 3. 한국어 기본값
-   - 기본 임베딩 모델: `hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf`(업스트림은 embeddinggemma-300M). 리랭커·질의 확장 모델은 업스트림 기본값 그대로. 업스트림 [README.md](README.md)의 모델 표·"Custom Embedding Model" 절은 업스트림 기본값 기준이다.
+   - 기본 임베딩 모델: `hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf`(업스트림은 embeddinggemma-300M). [README.md](README.md)의 모델 표·"Custom Embedding Model"·"Model Configuration" 절도 이 기본값 기준으로 고쳐 뒀다. 리랭커·질의 확장 모델은 업스트림 기본값 그대로.
    - 스킬 `skills/qmd/SKILL.md`에 "Korean queries" 절(`lex:`에 어간·alias·영문 용어, `vec:`에 한국어 패러프레이즈).
 
+4. 데몬 질의 로그 (`src/query-log.ts`, `server.ts` 접점 = REST 핸들러·MCP `query` 툴·`status` 툴): `QMD_QUERY_LOG=1` 로 띄운 HTTP 데몬이 REST 검색과 HTTP MCP `query` 툴 호출마다 `queries-YYYY-MM.jsonl` 에 한 줄을 남긴다(stdio MCP 는 남기지 않는다)(결과 경로·점수, 스니펫 없음). `rerank:false` 응답·로그 행에는 결과마다 원시 점수 `vec_score`(코사인 유사도)·`fts_score`(정규화 BM25)가 붙는다 — 그 경로의 `score`는 1/순위라 임계값을 걸 수 없다. 헤더 `X-QMD-Tag`·`X-QMD-Qid`·`X-QMD-Role`·`X-QMD-No-Log`. 계약은 [README.md § Query log](README.md#query-log-ko-qmd). 업스트림 PR 대상 아님.
+5. 모델 idle 타임아웃 env (`src/llm.ts` `LlamaCpp` 생성자): `QMD_LLM_IDLE_TIMEOUT_MS` 가 `createStore()` 의 5분 고정값보다 우선한다. `0` 이면 모델을 내리지 않는다 — 상주 데몬의 첫 검색이 모델을 다시 올리지 않게 하는 용도다.
+6. 경로·시간 범위 필터 (`src/filters.ts`): CLI `--path`·`--since`·`--until`, REST·MCP `path`·`since`·`until`. 걸러진 코퍼스 안에서 순위를 매긴다(전역 top-K 뒤 후처리가 아님). SDK 옵션 이름은 `scope`다 — `filter`는 업스트림의 metadata 필터(`--filter <json>`)가 쓰고, 둘을 같이 주면 AND. ko-qmd 에서는 metadata 필터도 같은 전체 스캔·정확 스캔 경로를 타므로, 업스트림 README 의 "선택적 필터는 best-effort" 한계가 적용되지 않는다.
+
 ### 기본 임베딩 변경 후 재임베딩
 
 벡터는 모델 사이에 호환되지 않는다. embeddinggemma로 만든 기존 인덱스는 다시 임베딩해야 한다.
@@ -26,9 +31,24 @@ qmd embed -f
 
 embeddinggemma를 계속 쓰려면 `index.yml`의 `models: embed:` 또는 `QMD_EMBED_MODEL`로 지정한다.
 
+### dogfood — 작업 트리 빌드를 이 머신 데몬에 올리기
+
+```sh
+bash scripts/dogfood.sh              # build → bench-ko 게이트 → npm pack → npm i -g → 데몬 재시작 → 스모크
+bash scripts/dogfood.sh --restore    # 발행본(DOGFOOD_PIN_FILE 의 ko-qmd@<버전>, 없으면 latest)으로 되돌림
+bash scripts/dogfood.sh --check "RESULT bm25_r5=…"   # 게이트 판정만
+```
+
+- 게이트: `bench-ko.sh` 의 `bm25_r5` 가 [BASELINE.md](test/fixtures/ko-vault/BASELINE.md) 의 마지막 bench-ko `RESULT` 줄보다 낮으면 설치 전에 멈춘다(exit 3). bench 는 소스를 tsx 로 돌리므로, 설치된 `dist/` 는 스모크(설치된 `qmd --version` 의 커밋 · `POST /query`)가 확인한다.
+- `npm link` 가 아니라 pack 설치다 — 링크하면 데몬이 작업 트리의 `dist/` 를 서빙해 빌드 중에 깨질 수 있다.
+- 머신 배선은 env: `DOGFOOD_LABEL`(launchd 라벨, 기본 `com.lemoncloud.qmd-daemon`) · `DOGFOOD_URL`(기본 `http://127.0.0.1:8181`) · `DOGFOOD_SMOKE`(추가 스모크 명령 — `"status":"hit"` JSON 을 내야 함) · `DOGFOOD_PIN_FILE`.
+- 성공하면 `~/.cache/qmd/dogfood-deployed` 에 `<시각> <커밋>` 을 쓴다(`--restore` 가 지운다). 배치 중에는 설치된 바이너리가 발행본 핀과 다르다 — `qmd --version` 의 커밋이 구분자.
+
 ### ko-vault 벤치
 
-`bash scripts/bench-ko.sh` (픽스처 `test/fixtures/ko-vault/`, 문서 28·질의 36, 임베딩은 픽스처 `models.yml`의 embeddinggemma로 고정). 표와 run별 수치는 [BASELINE.md](test/fixtures/ko-vault/BASELINE.md).
+`bash scripts/bench-ko.sh` (픽스처 `test/fixtures/ko-vault/`, 문서 28·질의 63, 임베딩은 픽스처 `models.yml`의 Qwen3-Embedding-0.6B-Q8_0으로 고정 — 패키지 기본값과 같다). run별 수치는 [BASELINE.md](test/fixtures/ko-vault/BASELINE.md).
+
+아래 표는 질의 36·embeddinggemma 시절의 단계별 기록이다.
 
 | 단계 | bm25_r5 | vector_r5 | full_r5 |
 |---|---|---|---|
@@ -36,7 +56,7 @@ embeddinggemma를 계속 쓰려면 `index.yml`의 `models: embed:` 또는 `QMD_E
 | + 질의 조사 처리 (B2) | 0.6528 | 0.9861 | 1.0000 |
 | + bigram 색인 (B3) | 0.6528 | 0.9861 | 1.0000 |
 
-Qwen3-Embedding 기본값의 벤치 수치는 미측정이다(design §6 라운드 M1).
+Qwen3-Embedding 기본값에서 질의 52는 bm25_r5 0.9519 · vector_r5 1.0000 · full_r5 1.0000이다. 질의 63은 외래어 표기 질의 11건(`하이브리드 서치` → `hybrid-search.md`)을 더한 것으로, 그 11건의 bm25_r5는 BASELINE.md 2026-09-23 절에 따로 적는다.
 
 ## 설치
 
@@ -48,6 +68,8 @@ npm install -g ko-qmd@<version>
 "ko-qmd": "<version>"
 ```
 
+버전은 `<업스트림 버전>-ko.N` 형태의 prerelease 라, `^`·`~` 범위는 같은 `major.minor.patch` 의 `-ko.*` 안에서만 움직인다(`^2.8.3-ko.0` 은 `2.8.4-ko.0` 을 안 집는다). 정확한 버전으로 핀한다.
+
 업스트림 `@tobilu/qmd` 와 bin 이름이 같아 둘을 함께 둘 수 없다 — `npm uninstall -g @tobilu/qmd` 뒤 설치한다. 미발행 커밋은 GitHub 에서 직접(`npm i github:tak-bro/ko-qmd#<sha>`) 받을 수 있고, 그때는 `prepare`가 `scripts/build.mjs`(= `tsc -p tsconfig.build.json`)로 `dist/`를 만든다. **설치에는 node + tsc만 필요하고 bun은 필요 없다.** 개발용 `npm run test:unit`은 vitest와 `bun test`를 둘 다 돌리므로 bun이 필요하다.
 
 설치 스모크(빈 디렉터리):
@@ -73,13 +95,20 @@ Windows CI 결과·리빌드 소요 시간은 `docs/vault-search/WINDOWS.md` 에
 
 ## 업스트림 동기화
 
+`develop` 에서 `chore/upstream-sync-*` 브랜치를 따고, 업스트림의 first-parent 머지 지점을 하나씩 `--no-ff` 로 머지한다. 대상은 태그든 `main` 스냅샷이든 된다.
+
 ```sh
-git fetch upstream
-git rebase upstream/<tag>   # on ko
-npm run test:unit && bash scripts/bench-ko.sh
+git fetch upstream --tags
+git log --first-parent --oneline develop..upstream/main   # 머지할 지점 목록
+bash scripts/bench-ko.sh                                  # 머지 전 기준값 (tmp/bench-ko/bench.json 보관)
+git merge --no-ff <지점>                                   # 지점마다 반복, 충돌은 이 머지 커밋에서 해결
+bun run lint && bun run test:types && bun run test:unit && bash scripts/bench-ko.sh
 ```
 
-통과하면 `v<업스트림 버전>-ko.N` 태그를 push한다.
+- 벤치는 전체 수치가 아니라 bm25 recall@5·MRR 을 질의별로 머지 전과 비교한다(hybrid 는 실행마다 한 질의쯤 흔들린다 — BASELINE.md 2026-09-23).
+- PR 은 squash 가 아니라 **머지 커밋**으로 들인다. 업스트림 커밋이 조상으로 남아야 다음 동기화가 새 커밋만 본다. 같은 이유로 이 브랜치는 squash·rebase 하지 않는다.
+- `develop`·`main` 을 upstream 위로 rebase 하지 않는다(보호 브랜치 force push).
+- 업스트림 태그 위에 있을 때만 `v<업스트림 버전>-ko.N` 태그를 쓴다. `main` 스냅샷이면 버전은 `2.8.3-ko.N` 식으로 마지막 태그 기준이다.
 
 ## 라이선스