@oomkapwn/enquire-mcp 3.7.20 → 3.8.0-rc.10

package/CHANGELOG.md

@@ -2,6 +2,613 @@
 
 All notable changes to this project will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.0-rc.10] — 2026-05-22
+
+> **TL;DR:** Tenth v3.8.0 release candidate. **Backlog items P3-25, P3-21, P3-27** from the v3.8.0 pre-stable queue, plus **watcher.ts branch-floor lift** (69% → 71% target). Tilde-fence headings now correctly excluded from `extractHeadings`; `--persistent-index` help text no longer implies sole-flag sufficiency for `obsidian_full_text_search`; HNSW metadata (dim/size/rowsByLabel) validated before native constructor call. **846 tests** (+4 negative-controls). Ships under `@rc` dist-tag.
+
+**Minor — tenth v3.8.0 release candidate.**
+
+### Fix P3-25 — tilde fences (`~~~`) excluded from heading extraction
+
+**Background.** `extractHeadings` in `src/tools/read.ts` used `/^\s*```/` to detect fenced code blocks. The CommonMark spec allows fences with `~~~` (three or more tildes) as an alternative to backtick fences. A Markdown note like:
+
+```
+# Real heading
+
+~~~sh
+## fake heading inside tilde fence
+~~~
+
+## Also real
+```
+
+would previously return three headings (including the fake inside the tilde fence) — polluting the document-map projection.
+
+**Fix (`src/tools/read.ts`, `extractHeadings`):** Extended regex to `/^\s*(`{3,}|~{3,})/` — detects both backtick fences and tilde fences of length ≥ 3.
+
+**Negative-control test** (`tests/tools.test.ts`, `readNote — document-map projection` describe block): verifies `format: "map"` returns exactly `["# Real heading", "## Also real"]` for a note with a tilde-fenced block containing `## fake heading inside tilde fence`.
+
+### Fix P3-21 — `--persistent-index` help text wording drift
+
+**Background.** `PERSISTENT_INDEX_HELP` in `src/cli-help.ts` read: *"Registers obsidian_full_text_search."* This implied `--persistent-index` alone was sufficient to expose the tool. In fact, **both** `--persistent-index` AND `--diagnostic-search-tools` are required (the tool is gated on both flags independently). The old phrasing was a gating-wording drift bug introduced in v3.5.14 and never caught by the subsequent OIA walks because the string lived in a new module (`cli-help.ts`) not yet in the walk's scan path.
+
+**Fix (`src/cli-help.ts`):** Rewrote `PERSISTENT_INDEX_HELP` to: *"Maintain a SQLite FTS5 inverted index for sub-100ms BM25-ranked search. Required for obsidian_full_text_search — also pass --diagnostic-search-tools to surface it alongside the default hybrid obsidian_search."* Both flags are now explicitly called out. The `DIAGNOSTIC_SEARCH_TOOLS_HELP` string already had this correct wording.
+
+### Fix P3-27 — HNSW metadata shallow validation before native constructor
+
+**Background.** `loadHnswFromDisk` in `src/hnsw.ts` passed `meta.dim`, `meta.size`, and `meta.rowsByLabel` from a JSON-parsed `.meta` sidecar directly to the native hnswlib constructor without validating the types. A corrupted or hand-edited `.meta` file with `dim: -1` or `rowsByLabel: null` would crash the native module with an opaque C-level exception rather than triggering a clean rebuild.
+
+**Fix (`src/hnsw.ts`, `loadHnswFromDisk`):** Added three guard blocks after the existing signature check — before any native constructor call:
+- `dim` must be a positive integer (rejects ≤ 0, NaN, non-integer).
+- `size` must be a non-negative integer.
+- `rowsByLabel` must be a plain object (rejects `null`, arrays, primitives).
+
+Each guard emits a `process.stderr.write` warning and returns `null` (triggering a clean rebuild), consistent with the existing pattern for sig-mismatch.
+
+**Negative-control tests** (`tests/hnsw.test.ts`): two new `it` blocks — one with `dim: -1` (invalid int), one with `rowsByLabel: null` (non-object) — verify that `loadHnswFromDisk` returns `null` rather than throwing.
+
+### Watcher branch-floor lift (69% → 71%)
+
+Added `tests/watcher.test.ts` test: *"attachEmbed: embed-db sync failure is logged to stderr (silent=false) and FTS5 still updates — NEGATIVE control"*. Uses a throwing embedder to verify:
+1. FTS5 still updates (fail-soft path in `attachEmbed`).
+2. `embedDb.totalChunks() === 0` (embed-db write skipped).
+3. `stderr` contains `"embed-db sync failed"` plus the synthetic error message.
+
+This exercises the `try/catch` branch in `attachEmbed` that was previously uncovered, lifting `watcher.ts` from 69% to ≥71% branch coverage.
+
+### Method note
+
+Post-merge self-audit scope for rc.10 (CLAUDE.md rule since v3.7.15):
+- `src/tools/read.ts` `extractHeadings`: regex body change only. TSDoc for `extractHeadings` describes the fence behavior — updated in-line with fix. α-class clear.
+- `src/cli-help.ts` `PERSISTENT_INDEX_HELP`: string replacement. Comment header above the export already stated the intent; updated. No other caller-side TSDoc mentions this constant by value. α-class clear.
+- `src/hnsw.ts` `loadHnswFromDisk`: added early-return guards. TSDoc for `loadHnswFromDisk` says "returns null on any load error" — the new guards are consistent with that contract, no header update needed. α-class clear.
+- `tests/watcher.test.ts`: test-only addition, no production code change.
+
+Docs-consistency: test count updated 842 → 846 across README.md (badge + tagline + feature matrix + npm test line), package.json description, docs/COMPARISON.md.
+
+### Stats
+
+- **846 tests** (+4 negative-controls vs rc.9).
+- `watcher.ts` branch coverage: 69% → ≥71%.
+- `npm audit`: 0 vulnerabilities.
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All 9 required CI gates pass locally.
+
+### v3.8.0 remaining backlog
+
+- **T-2, T-3** — communities handler + hyde E2E.
+- **T-4** — optional serve-http HTTP smoke.
+- OCR'd PDF watcher embed-sync, HNSW in-memory watcher update.
+- External audit before `@latest` promotion.
+
+---
+
+## [3.8.0-rc.9] — 2026-05-22
+
+> **TL;DR:** Ninth v3.8.0 release candidate. **Round-7 external audit response** — 3 fixes: W-FLAKE-2 (chokidar FSEvents startup warmup missing from R-7 embed tests — sibling of rc.7 #36 fix), R-10 (HNSW k multiplier 4× → 6× to reduce post-privacy-filter under-return), and N-new (qs 6.15.1 → 6.15.2, GHSA-q8mj-m7cp-5q26, DoS in `qs.stringify` with comma-format arrays). Ships under `@rc` dist-tag.
+
+**Minor — ninth v3.8.0 release candidate.**
+
+### Fix W-FLAKE-2 — R-7 embed tests missing chokidar FSEvents warmup
+
+**Background.** rc.7 fix #36 added a 50ms chokidar FSEvents startup warmup to the stderr-capture watcher tests (lines ~156 and ~190) to prevent race conditions where the first `fs.writeFile` landed before chokidar's FSEvents listener was ready. The round-7 external audit (rc.8 codebase) found that the sibling R-7 embed tests (`attachEmbed: .md change re-embeds`, line ~358; `attachEmbed: PDF add`, line ~412) were missing the same warmup. Under `npm run test:coverage` (parallel vitest workers + V8 coverage instrumentation overhead), the chokidar debounce path could be slow enough that `waitFor(() => embedDb.totalChunks() > 0, 4000)` timed out intermittently — producing 1 failed test in 1/3 coverage runs.
+
+**Fix:** Added `await new Promise((r) => setTimeout(r, 50))` after `await w.start()` in both R-7 embed tests (same pattern as rc.7 fix at lines 156/190). Also bumped the `waitFor` timeout from 4000ms → 6000ms in those two tests as defense-in-depth against instrumentation slowdown. No test count change — warmup and timeout are existing-test hardening.
+
+**Sibling analysis:** The original rc.7 #36 fix (stderr tests) and this fix (embed tests) now cover all 4 chokidar watcher test sites that do a `w.start()` + immediate first write. Sweep complete.
+
+### Fix R-10 — HNSW k multiplier: 4× → 6× limit to reduce post-privacy-filter under-return
+
+**Background.** The HNSW k-NN path in `embeddingsSearch` fetches `k = Math.min(Math.max(overFetch * 2, 30), N)` candidates (effective 4× limit), then applies the privacy filter (`vault.isExcluded`), then slices to `limit`. Under dense `--exclude-glob` configurations (large fraction of the embed-db excluded), the privacy filter removes a disproportionate share of the over-fetched pool → `matches.length < limit`. For brute-force cosine the multiplier is 2× limit; HNSW used 4× — which helped somewhat but was insufficient under heavy exclusion.
+
+**Fix (`src/tools/search.ts`):** Changed `overFetch * 2` → `overFetch * 3` (effective 4× → 6× limit, baseline floor 30 → 50). Residual under-return can still occur when >66% of the index is excluded — documented in the `embeddingsSearch` TSDoc privacy-contract paragraph as accepted behavior (privacy > completeness).
+
+**Root cause class:** Post-search privacy filter shrinks the result set below the requested limit. Same class applies to the brute-force path (2× over-fetch) and reranker candidate pool, but those are lower-risk: brute-force fetches the entire db anyway, and rerankers typically run on already-filtered hits.
+
+### Fix N-new — qs 6.15.1 → 6.15.2 (GHSA-q8mj-m7cp-5q26, moderate DoS)
+
+**Vulnerability:** `qs.stringify` crashes with `TypeError` when `encodeValuesOnly: true` and an array in comma format contains `null`/`undefined` entries. This is a remotely triggerable DoS for any application that exposes `qs.stringify` to untrusted input. Affected range: `qs` 6.11.1 – 6.15.1. Fixed in 6.15.2.
+
+**Scope:** `qs` is a transitive dep: `@modelcontextprotocol/sdk@1.29.0 → express@5.2.1 → qs`. enquire-mcp uses express for the `serve-http` MCP transport. The HTTP body is pre-validated by Zod before any query-string serialization path, so exploitability is low; nonetheless a patch is available and applied.
+
+**Fix:** `npm audit fix` updated `package-lock.json` to pin `qs@6.15.2`. No `package.json` change needed (this is a lock-file-only fix to a transitive dep).
+
+### Method note
+
+Round-7 audit verdict: **all round-24 findings confirmed closed** in rc.8. New items surfaced:
+- W-FLAKE-2 — closed in this release (rc.9)
+- R-10 — closed in this release (rc.9, implementation + docs)
+- N-new (qs) — closed in this release (rc.9)
+
+**Post-merge self-audit scope for rc.9:**
+- `watcher.test.ts`: only warmup + timeout changes, no new runtime guards → no new negative-control obligation.
+- `search.ts`: HNSW k multiplier change + TSDoc paragraph. No TSDoc header drift risk (the function body change IS the TSDoc update). α-class clear.
+- `package-lock.json`: lock-only change, no code.
+
+### Stats
+
+- **842 tests** (unchanged from rc.8).
+- `npm audit`: 0 vulnerabilities.
+- HNSW effective over-fetch: **4×** → **6× limit**.
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All 9 required CI gates pass locally.
+
+### v3.8.0 remaining backlog
+
+- **T-2, T-3** — communities handler + hyde E2E.
+- **T-4** — optional serve-http HTTP smoke.
+- OCR'd PDF watcher embed-sync, HNSW in-memory watcher update, watcher.ts ≥71% branch floor.
+- External audit before `@latest` promotion.
+
+## [3.8.0-rc.8] — 2026-05-21
+
+> **TL;DR:** Eighth v3.8.0 release candidate. **Round-24 external audit response** — 2 findings closed: T-1 (contextPack hard-cap has zero test coverage for the triggered path — violation of CLAUDE.md negative-control rule) and INFO-2 (embed-pipeline.ts missing from per-file FLOORS). Adds `tests/context-pack.test.ts` (4 tests with positive + negative controls), lifts meta.ts branch coverage 67.66% → 73.85%, adds embed-pipeline.ts floor at 84%. Ships under `@rc` dist-tag.
+
+**Minor — eighth v3.8.0 release candidate.**
+
+### Finding T-1 — `contextPack` hard-cap: zero tests for triggered path
+
+**Background.** rc.6 R-4 added a hard final bundle cap to `contextPack`: after assembling all sections, if `raw.length > charBudget`, the bundle is sliced to `charBudget` chars and a `[…budget cap reached…]` marker is appended. The round-24 external audit (rc.7 codebase) found **zero test coverage** for this code path — a direct violation of CLAUDE.md anti-pattern "Invariant test without negative-control — a test that ALWAYS passes proves nothing. Rule since v3.6.4."
+
+**Fix:** New `tests/context-pack.test.ts` with 4 tests:
+
+1. **Positive control** — `budget_tokens: 1000`, small note → bundle fits, marker NOT appended. Proves the cap is not always applied.
+2. **Negative control** — `budget_tokens: 1` (charBudget=4 chars), big note → cap IS triggered, marker present, sliced portion ≤ charBudget.
+3. **Error path** — empty and whitespace-only query → throws.
+4. **Empty match set** — off-topic query against unrelated content → valid result, `included_notes: []`.
+
+**Side effect (coverage uplift):** The 4 new tests exercise contextPack's hybrid-search + section-assembly code path. `src/tools/meta.ts` branch coverage jumped from 67.66% → 73.85% (+6.2pp), allowing the per-file floor to be raised from 65% → 71%.
+
+### Finding INFO-2 — `embed-pipeline.ts` missing from per-file FLOORS
+
+**Background.** rc.4 extracted `embedSingleNote`/`embedSinglePdf` from `server.ts` into `embed-pipeline.ts`. The new module had direct unit tests (`tests/embed-pipeline.test.ts`) with ~86% branch coverage. But the file was never added to the per-file FLOORS table in `scripts/check-per-file-coverage.mjs` — so a future branch coverage regression in that file would only be caught by the global 75% gate (which averages over 31 source files), not by a file-specific floor.
+
+**Fix:** Added `"src/embed-pipeline.ts": { branches: 84 }` to FLOORS (floor at 84%, 2pp below current 86.84%). The per-file script now enforces **10 floors** (was 9).
+
+**Note:** The FLOORS comment deferred this addition with "Re-lifted in rc.4+ when we either move embed-pipeline…". That condition was met in rc.4; rc.8 closes the gap.
+
+### Method note
+
+Round-24 audit had **4 entries** total:
+- T-1 (this fix) — ship-ready ✅
+- INFO-2 (this fix) — ship-ready ✅
+- R-10 HNSW privacy under-return — acknowledged deferred work, NOT a regression. Documented in v3.8.0 backlog.
+- INFO-3 CHANGELOG "no open items" nuance — accepted wording; the note says "round-23 report IDs", not "all product backlog". Will clarify in stable release notes.
+
+**Post-merge self-audit scope:** context-pack.test.ts is a new file with no function-body-changed TSDoc to drift. scripts/check-per-file-coverage.mjs FLOORS table is a config change with no TSDoc. No new drift risk.
+
+### Stats
+
+- **842 tests** (+4 from T-1 contextPack tests). Was 838 in v3.8.0-rc.7.
+- **10 per-file FLOORS** (was 9); `embed-pipeline.ts` floor at 84%.
+- `tools/meta.ts` branches: 67.66% → **73.85%** (floor raised 65% → 71%).
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All 9 required CI gates pass locally.
+
+### v3.8.0 remaining backlog (unchanged from rc.7)
+
+- **R-10** — HNSW + privacy under-return fix.
+- **T-2, T-3** — communities handler + hyde E2E.
+- **T-4** — optional serve-http HTTP smoke.
+- OCR'd PDF watcher embed-sync, HNSW in-memory watcher update, watcher.ts ≥71% branch floor.
+- External audit before `@latest` promotion.
+
+## [3.8.0-rc.7] — 2026-05-21
+
+> **TL;DR:** Seventh v3.8.0 release candidate. **Post-rc.6 self-audit** — 3 fixes: α-class TSDoc drift in `contextPack` (hard budget cap not documented in TSDoc), N-5 sibling (`serve --watch` help text missing .pdf + embed-db, only `serve-http` was updated in rc.6), and watcher flake (task #36 — chokidar FSEvents startup delay missing from the line-170 stderr-capture test, same pattern as sibling at line-140). Ships under `@rc` dist-tag.
+
+**Minor — seventh v3.8.0 release candidate.**
+
+### Fix 1 — α-class TSDoc drift: `contextPack` budget-cap paragraph
+
+The rc.6 R-4 fix added a hard final bundle cap (`bundle.slice(0, charBudget)` with marker) to `contextPack` but the function-level TSDoc "Budget enforcement" paragraph was NOT updated in the same commit — describing only the per-section truncation, omitting the hard cap. Detected by the mandatory post-merge self-audit sweep (CLAUDE.md rule since v3.7.15).
+
+Fix: added one sentence to the TSDoc paragraph: "As a final defense-in-depth, the assembled bundle is hard-capped at `budget_tokens × 4` chars and marked `[…budget cap reached…]` if truncated."
+
+**Overclaim class note**: this is the 10th TSDoc drift instance in the project ledger (v3.6.1 was #1, …, v3.7.14 F1 + F2 were #6/#7, v3.7.15 R17-1 was #8, the rc.6 ARCH-1 TSDoc update + migration note would have been #10 if missed — but it was caught in the same commit). rc.7 Fix 1 is instance #10 (missed because the R-4 contextPack change was a small add-on to meta.ts, not a standalone "function body changed" commit).
+
+### Fix 2 — N-5 sibling: `serve --watch` help text
+
+rc.6 N-5 updated the `serve-http --watch` option help string but missed the parallel `serve` command option (line 124 of `src/cli.ts`). Both now read the canonical form: "Watch the vault for .md and .pdf changes; incrementally re-syncs FTS5 and embed-db (when available)." Detected by post-rc.6 sibling sweep (CLAUDE.md rule: "sweep that patch's own diff for fresh instances of the same class").
+
+### Fix 3 — watcher.test.ts chokidar FSEvents startup delay (task #36)
+
+The line-170 `"logs reindexed / unlink lines to stderr"` test had no delay between `w.start()` and the first `fs.writeFile()`. On macOS CI runners with slower FSEvents initialization, the write event fires before chokidar finishes attaching its listener — causing a flake (~25% on macOS CI, observed once in rc.5 test-macos). The sibling test at line 140 correctly had `await new Promise(r => setTimeout(r, 20))` as a warm-up guard.
+
+Fix: added `await new Promise(r => setTimeout(r, 50))` after `w.start()` in the line-170 test. Also bumped the line-140 test's warm-up from 20ms → 50ms (both tests on the same macOS risk surface). Root cause is identical to T-FLAKE-1 class: a time-based assumption where two independent clocks (OS event system + test) aren't synchronized.
+
+### Method note
+
+Post-merge self-audit sweep applied per CLAUDE.md rule (since v3.7.15). Three findings, all in the rc.6 diff's own scope:
+- Fix 1: body-changed-without-header-update (same class as v3.7.14 F1/F2, v3.7.15 R17-1)
+- Fix 2: incomplete N-class sweep (only one of two sibling options updated)
+- Fix 3: chokidar warm-up gap (parallel to T-FLAKE-1 timing class)
+
+No new tests added (all fixes are documentation/timing corrections on existing code).
+
+### Stats
+
+- **838 tests** (unchanged). All fixes are doc/timing changes.
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All 9 required CI gates pass locally.
+
+## [3.8.0-rc.6] — 2026-05-21
+
+> **TL;DR:** Sixth v3.8.0 release candidate. **Round-23 external audit response** — 6 fixes: T-FLAKE-1 vitest per-it timeout (build-embeddings test), N-4 protobufjs GHSA-jggg-4jg4-v7c6 bump, N-5 serve-http `--watch` help text parity, ARCH-1 circular import (`buildEmbedText` moved to `embed-pipeline.ts`), R-4 contextPack hard budget cap, and OIA promoted from advisory → required (9th CI gate). Ships under `@rc` dist-tag.
+
+**Minor — sixth v3.8.0 release candidate.**
+
+### Fix 1 — T-FLAKE-1: vitest per-it timeout on `build-embeddings` test
+
+`tests/cli.test.ts` `build-embeddings HONORS model_alias=bge` test was flaking in CI because the global `testTimeout: 15_000` (vitest.config.ts) killed the test before the `spawnSync` subprocess finished (subprocess loads the BGE embedder: 30–60s cold). Root cause: two independent timeout sources with inverted priority — vitest kills at 15s, subprocess is allowed 60s.
+
+Fix: added the vitest per-it timeout override (third argument to `it(name, fn, 90_000)`) so vitest allows 90s for that test, while the subprocess-level `timeout: 60_000` stays as the inner guard. 30s assertion budget remains after subprocess exits. No new test added — this is a timing fix on an existing test.
+
+### Fix 2 — N-4: protobufjs GHSA-jggg-4jg4-v7c6 (moderate DoS)
+
+`npm audit fix` updated protobufjs 7.5.7 → 7.6.0. The advisory describes unbounded recursive JSON descriptor expansion (moderate severity, DoS vector). `package-lock.json` updated.
+
+### Fix 3 — N-5: `serve-http --watch` CLI help text parity with api.md
+
+`src/cli.ts` serve-http `--watch` option help string previously read "Watch the vault for .md changes and refresh indexes incrementally." — omitting `.pdf` and embed-db re-sync. Updated to match `docs/api.md` which accurately describes watcher behavior since v3.8.0-rc.2 + rc.3: "Watch the vault for .md and .pdf changes; incrementally re-syncs FTS5 and embed-db (when available)."
+
+### Fix 4 — ARCH-1: break circular import (`buildEmbedText`)
+
+`src/embed-pipeline.ts` (introduced in rc.4) imported `buildEmbedText` from `./server.js`, while `src/server.ts` imported `embedSingleNote`/`embedSinglePdf` from `./embed-pipeline.js` — a circular dependency. ESM live bindings made the build succeed, but the architecture was unsound.
+
+Fix: moved `buildEmbedText` from `server.ts` to `embed-pipeline.ts` (where it's consumed). `server.ts` now re-exports it via `export { buildEmbedText } from "./embed-pipeline.js"` for backward compat — `src/index.ts` and `tests/late-chunking.test.ts` see no API change. Circular eliminated.
+
+**TSDoc rule** (CLAUDE.md anti-pattern "TSDoc header drifts from function body"): `buildEmbedText` TSDoc preserved verbatim + annotated with the move in the same commit.
+
+### Fix 5 — R-4: contextPack hard budget cap
+
+`contextPack` in `src/tools/meta.ts` tracked `charsUsed` per-section but had systematic gaps: section headers like `"## Top notes"` were pushed to the sections array without adding their length to `charsUsed`, and `join("\n")` overhead accumulated unchecked. Result: the returned `bundle` could slightly exceed `charBudget`.
+
+Fix: after `sections.join("\n")`, apply a hard cap: if `raw.length > charBudget`, truncate to `charBudget` chars and append `\n[…budget cap reached…]` so callers can detect the truncation. The per-section checks remain as the primary mechanism; the slice is defense-in-depth.
+
+### Fix 6 — OIA promoted from advisory → required (9th CI gate)
+
+`check:oia` (`scripts/oia-walk.mjs`, added v3.7.17, added as advisory CI job in v3.7.19) had zero false positives across v3.7.19 → v3.8.0-rc.5 (6 releases). Round-23 audit report identified the failure to promote as a gap.
+
+Changes:
+- `.github/workflows/ci.yml` — removed `continue-on-error: true` from `oia` job.
+- `.github/workflows/release.yml` — added `|oia` to `REQUIRED` regex; bumped `REQ_COUNT` 8 → 9; updated comment.
+- `README.md` — updated "8 required" → "9 required" in feature matrix + CI security table; added `oia` to the gate list.
+- `CLAUDE.md` quality bar item 7 — updated 8 → 9.
+
+The `tests/docs-consistency.test.ts` "N required CI gates" invariant (added v3.7.14 F4) immediately caught the `REQ_COUNT` mismatch during local test run — exactly as designed.
+
+### Method note
+
+Round-23 was the first full-round external audit on v3.8.0-rc.5 (post-K-3). All 6 findings in this patch are from that audit report (`enquire-mcp-audit-report-2026-05-21-reaudit-v3.8.0-rc.5-FULL.md`). No open audit items remain from rounds 1–23 as of this release.
+
+**Post-merge self-audit sweep (CLAUDE.md rule since v3.7.15):** checked this diff for fresh TSDoc drift — ARCH-1 (buildEmbedText move) TSDoc preserved + migration note added in same commit; R-4 contextPack has no header (anonymous helper block); no function bodies changed without header update.
+
+### Stats
+
+- **838 tests** (unchanged from rc.5). No new tests in rc.6 — all fixes are runtime/config changes.
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All 9 required CI gates pass locally (including the newly-required `oia`).
+
+### v3.8.0 remaining backlog (next RCs)
+
+- **R-10** — HNSW + privacy under-return fix (over-fetch margin tuning).
+- **T-1..T-5** — test coverage gaps (`contextPack`, `get_communities` handler E2E, `hyde_search` E2E, `serve-http` cli.test E2E).
+- **4/5 reranker E2E in CI** with model-cache strategy.
+- **OCR'd PDF watcher embed-sync** (deferred from rc.3).
+- **HNSW in-memory update** alongside watcher upserts (architectural).
+- **watcher.ts catch-branch coverage via vi.mock or DI** — lift floor back to ≥71%.
+- **External audit on rc.N** before promotion to stable.
+
+## [3.8.0-rc.5] — 2026-05-21
+
+> **TL;DR:** Fifth v3.8.0 release candidate. Adds **K-3 readOnlyHint structural invariant** — pins the tool-registry's `READ_ONLY` ↔ read-handler / `WRITE` ↔ write-handler mapping so the annotations can't drift away from the wired handlers. Catches the class of bug an MCP client's `readOnlyHint`-driven confirmation gate would silently swallow. Ships under `@rc` dist-tag.
+
+**Minor — fifth v3.8.0 release candidate.**
+
+### K-3 — readOnlyHint structural invariant
+
+**Background.** MCP tool annotations advertise to the client and the agent orchestrator what each tool can do. Specifically:
+- `readOnlyHint: true` → MCP clients that gate destructive operations behind user confirmation will SKIP that gate for this tool.
+- `destructiveHint: true` → MCP clients show a "destructive" badge and may ask for explicit confirmation per call.
+
+If a tool annotated `readOnlyHint: true` is silently wired to a write handler (e.g. `createNote`, `appendToNote`, `renameNote`, `replaceInNotes`, `archiveNote`, `chatThreadAppend`, `frontmatterSet`), the client won't confirm, and the agent can mutate the vault without the user knowing.
+
+`src/tool-registry.ts` already follows the convention (two shorthand annotation objects — `READ_ONLY` + `WRITE` — at lines 57, 138, 1028 — plus 7 known write-handler names). But there was no automated check that the convention is maintained. K-3 pins it.
+
+### What's enforced
+
+1. **Every `READ_ONLY`-annotated tool's handler block does NOT reference any function in `KNOWN_WRITE_HANDLERS`.**
+2. **Every `WRITE`-annotated tool's handler block references at least one function from `KNOWN_WRITE_HANDLERS`.**
+3. **Every tool in `tool-registry.ts` has an explicit `READ_ONLY` or `WRITE` annotation** (no UNKNOWN).
+
+`KNOWN_WRITE_HANDLERS` is a set of 7 names: `createNote`, `appendToNote`, `renameNote`, `replaceInNotes`, `archiveNote`, `chatThreadAppend`, `frontmatterSet`. If a future PR adds a new write operation, it MUST register its handler name in this set, OR the K-3 invariant test will reject it as UNKNOWN/violation.
+
+### Implementation
+
+- **`tests/k3-readonly-hint-invariant.test.ts`** — 3 production tests + 3 negative-control fixture tests = 6 new tests.
+- **`scanRegistry(source)`** — exposed as a pure function so fixture-based negative controls can exercise the scanner directly (per CLAUDE.md anti-pattern "Invariant test without negative-control — Rule since v3.6.4").
+- **Block boundary fix** — the scanner bounds each `registerTool(...)` block by the NEXT `registerTool(` call (or end of file), not a fixed line window. Caught during initial test: a fixed 60-line window allowed the last READ_ONLY tool's window to extend into `registerWriteTools()` and grab the first WRITE tool's `createNote(` call. The block-bounding fix was found via the test failing on initial run — exactly the kind of class-of-bug discovery the invariant is designed for.
+
+### Fixture coverage (negative-control)
+
+3 fixture files under `tests/fixtures/k3-invariant/`:
+- **`good.fixture.ts`** — positive control: canonical READ_ONLY + WRITE patterns, both correctly wired.
+- **`bad-readonly-with-write.fixture.ts`** — READ_ONLY tool wired to `createNote` (the exact bug shape K-3 catches).
+- **`bad-write-no-handler.fixture.ts`** — WRITE tool wired to `readNote` (inverse drift).
+
+Each fixture is parseable by `scanRegistry` independently, so the negative-control sibling tests prove the scanner classifies each case correctly without requiring production code violations.
+
+### Stats
+
+- **838 tests** (+6 from K-3). Was 832 in v3.8.0-rc.4.
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All required CI gates pass locally.
+
+### v3.8.0 remaining backlog (next RCs)
+
+- **R-10** — HNSW + privacy under-return fix (over-fetch margin tuning).
+- **T-1..T-5** — test coverage gaps (`contextPack`, `get_communities` handler E2E, `hyde_search` E2E, `serve-http` cli.test E2E).
+- **4/5 reranker E2E in CI** with model-cache strategy.
+- **OCR'd PDF watcher embed-sync** (deferred from rc.3).
+- **HNSW in-memory update** alongside watcher upserts (architectural).
+- **watcher.ts catch-branch coverage via vi.mock or DI** — lift floor back to ≥71%.
+- **External audit on rc.N** before promotion to stable.
+
+## [3.8.0-rc.4] — 2026-05-21
+
+> **TL;DR:** Fourth v3.8.0 release candidate. Closes the rc.3 architectural deferral: extracts `embedSingleNote` (rc.2) + `embedSinglePdf` (rc.3) from `src/server.ts` into a dedicated `src/embed-pipeline.ts` module. The motivation was the `tests/no-internal-imports.test.ts` Class A invariant — server.ts is in `RESTRICTED_MODULES`, so the helpers couldn't be unit-tested directly. Now they can: 10 new direct unit tests in `tests/embed-pipeline.test.ts` cover happy paths, null returns, embedder error propagation, frontmatter title resolution, late-chunk-context honoring, and the data-integrity guard against mismatched vector counts. Ships under `@rc` dist-tag.
+
+**Minor — fourth v3.8.0 release candidate.**
+
+### Architectural extraction
+
+1. **New module `src/embed-pipeline.ts`** (~135 lines) — houses `embedSingleNote` + `embedSinglePdf` + shared `EmbedRow` interface. No new code; pure relocation + re-export.
+
+2. **`src/server.ts` import** — `syncEmbedDb` and `syncPdfEmbedDb` now import the helpers from `./embed-pipeline.js` (top-level import) instead of having them inlined. No behavior change.
+
+3. **`src/watcher.ts` dynamic import** — the `await import(...)` calls inside `handle()` now target `./embed-pipeline.js` instead of `./server.js`. Same dynamic-import gating (loads only when `embedDb` + `embedder` are wired) so the no-embed code path stays zero-cost.
+
+4. **`tests/embed-pipeline.test.ts`** — 10 new unit tests. Coverage on the new file: **94.44% statements / 85% branches / 100% functions / 100% lines**. The previously-flaky chokidar-based fail-soft tests from rc.3's draft batch are no longer needed — embedder-error propagation is now tested deterministically (vault + mock embedder, no watcher overhead).
+
+### Why this matters
+
+The Class A invariant from `tests/no-internal-imports.test.ts` blocks tests from value-importing `src/{cli,server,tool-registry,prompts}.ts`. Pre-rc.4, that meant the rc.2 + rc.3 helpers had ZERO direct unit tests — they got covered only end-to-end via watcher chokidar tests, which flake at ~25% locally due to debounce timing. rc.4 splits the helpers out into a non-restricted module so:
+
+- Future audit findings on these helpers can be tested in isolation (deterministic, fast — 227ms vs ~8s for chokidar-based watcher tests).
+- The "watcher.ts branch coverage floor 71% → 69%" deferral from rc.3 stays mostly closed (embed-pipeline at 85% branches absorbs the work; watcher.ts itself unchanged at 69.23% because the inline branches were always wiring + error handling, not pipeline logic).
+- New code added to the embed pipeline gets a clean test surface to extend, not a "where do I put this test?" question.
+
+### Coverage floor decision
+
+`src/watcher.ts` per-file branch floor stays at **69%** (set in rc.3) because:
+- The extraction moved LOGIC out of watcher.ts but watcher.ts's uncovered branches (lines 314-319, 327-328) are chokidar wiring + outer try/catch for file-disappeared-mid-event — not embed-pipeline logic.
+- Adding chokidar-based tests for those branches reintroduces rc.3's 25% flake rate.
+- Lifting requires either `vi.mock` on the dynamic import (rc.5+ scope — needs testing infrastructure design) or refactoring to dependency injection (architectural — rc.6+).
+
+Floor stays documented in `scripts/check-per-file-coverage.mjs` with the same rc.3 rationale, now amended to reference embed-pipeline coverage as the architectural offset.
+
+### Stats
+
+- **832 tests** (+10 from `tests/embed-pipeline.test.ts`). Was 822 in v3.8.0-rc.3.
+- New file: `src/embed-pipeline.ts` (~135 LoC, 85% branch coverage).
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All required CI gates pass locally.
+
+### v3.8.0 remaining backlog (next RCs)
+
+- **K-3** — `readOnlyHint: true` → no destructive operations structural invariant (rc.5 candidate).
+- **R-10** — HNSW + privacy under-return fix (over-fetch margin tuning).
+- **T-1..T-5** — test coverage gaps (`contextPack`, `get_communities` handler E2E, `hyde_search` E2E, `serve-http` cli.test E2E).
+- **4/5 reranker E2E in CI** with model-cache strategy.
+- **OCR'd PDF watcher embed-sync** (deferred from rc.3).
+- **HNSW in-memory update** alongside watcher upserts (architectural).
+- **watcher.ts catch-branch coverage via vi.mock or DI** — lift floor back to ≥71% (rc.5+).
+
+## [3.8.0-rc.3] — 2026-05-20
+
+> **TL;DR:** Third v3.8.0 release candidate. Closes the PDF half of **R-7 watcher → embed-db sync** that rc.2 deferred. Pre-rc.3 the watcher would re-embed edited `.md` files but PDFs still drifted silently. Now both surfaces stay in sync. Refactors `syncPdfEmbedDb` onto a shared `embedSinglePdf` helper (DRY with watcher), so bulk-sync and watcher-sync share one tested code path. Ships under `@rc` dist-tag.
+
+**Minor — third v3.8.0 release candidate.**
+
+### R-7 — PDF embed-sync via watcher (rc.2 deferral)
+
+**Background**: rc.2 closed the markdown half of R-7 but explicitly carried PDFs into rc.3 because the PDF pipeline has two extra steps (binary read + pdfjs text extraction with `[page: N]` markers) and the chunk+embed core was still inlined into `syncPdfEmbedDb`. Users who used `--watch --include-pdfs` saw FTS5 re-index PDFs in real-time but semantic-search results for those same PDFs stayed frozen at the last `build-embeddings` snapshot.
+
+**Implementation**:
+
+1. **Extracted `embedSinglePdf(vault, embedder, entry, opts)` helper** in `src/server.ts` (mirrors `embedSingleNote` from rc.2). Reads PDF bytes via `vault.readBinaryFile`, extracts text via `pdf.ts`'s `extractPdfText`, joins pages with `[page: N]` markers, chunks via `chunkContent`, builds embed-texts with `buildEmbedText` (carrying breadcrumb + late-chunk context), embeds, returns row-array. Returns `null` for image-only / zero-chunk PDFs so the caller can decide between `deleteNote` (drop stale rows) and "skip with warning" (never indexed).
+
+2. **Refactored `syncPdfEmbedDb` onto the helper**. The pre-rc.3 inline loop is now 6 lines: call helper → null branch (delete-stale or warn-skip) → upsert. The dead `extractPdfText` lazy-import was removed (now lives in the helper).
+
+3. **Watcher's `handle()` dispatches PDF embed-sync after FTS5 update**:
+   - `unlink` event on `.pdf` → `embedDb.deleteNote(relPath)` (rc.2 was md-only here too)
+   - `add` / `change` on `.pdf` → `embedSinglePdf(...)` → `embedDb.upsertNote(relPath, mtime, rows, "pdf")` (note the `kind="pdf"` parameter) OR `deleteNote` if image-only
+   - Same fail-soft posture as the rc.2 md path: errors LOG but don't fail the watcher; embed-db will resync on next bulk build.
+
+### What's NOT in rc.3 (deferred to rc.4+)
+
+- **OCR'd PDF watcher embed-sync**: OCR is opt-in and slow (Tesseract is seconds-per-page); doing it inline in the watcher would spike CPU on bulk paste-into-vault events. Likely deferred to a queue-based approach in rc.4.
+- **HNSW signature mismatch on individual upsert** (rc.2 same caveat): HNSW signature stays stale after watcher updates; next serve start triggers a rebuild.
+- **K-3 readOnlyHint structural invariant**, **R-10 HNSW + privacy under-return**, **T-1..T-5 test gaps**, **4/5 reranker E2E**: all still on the rc.4+ backlog.
+
+### Test coverage
+
+`tests/watcher.test.ts` — the existing rc.2 negative-control "PDF events DON'T touch embed-db (md-only for rc.2)" is now flipped into a positive: `attachEmbed: PDF add upserts to embed-db with kind=pdf (rc.3 R-7 continuation)`. Asserts:
+1. After PDF write, `embedDb.totalChunks() > 0` (chunks landed).
+2. `embedDb.getSourceStates("pdf")` includes the PDF's relPath (kind tag correct).
+3. After unlink, `embedDb.totalChunks() === 0` (rows dropped).
+
+Total: **822 tests** (no net change — test was repurposed from negative-control to positive). All 14 watcher tests pass.
+
+### How to use
+
+```bash
+enquire-mcp serve \
+  --vault ~/Obsidian/MyVault \
+  --include-pdfs \
+  --persistent-index \
+  --use-hnsw \
+  --watch
+```
+
+Now editing a PDF in the vault (or replacing it via Finder, or git-pulling a new version) → watcher re-extracts text + re-embeds + upserts → next semantic search sees the new content. Combined with rc.2's md path, both halves of R-7 now closed.
+
+### Coverage floor adjustment (documented)
+
+`src/watcher.ts` per-file branch floor lowered from **71% → 69%** (in `scripts/check-per-file-coverage.mjs`). Rationale: rc.3 added the PDF embed-sync block (lines 240-288 in `src/watcher.ts`, mirroring the rc.2 md path) which introduces ~5 new branches (embedDb-handle check, embedder-handle check, null-result branch, error-catch, kind="pdf" upsert path). The happy paths are covered end-to-end by the rc.2 R-7 md test + the rc.3 R-7 PDF test; the fail-soft error branches (embedder throws inside chokidar's event loop) are flaky in chokidar-based tests (~25% locally — increased file count perturbs `awaitWriteFinish` debounce timing past the test's `waitFor` budget). Re-lift the floor in rc.4+ via one of: (a) move `embedSingleNote` + `embedSinglePdf` to a dedicated `src/embed-pipeline.ts` module (not in the `no-internal-imports.test.ts` restricted list) so we can unit-test directly without spinning up chokidar, OR (b) add dependency-injection to make the throw path deterministic. Both are real options for rc.4+; rc.3 ships with documented adjustment per CLAUDE.md anti-pattern "silent floor reductions are not allowed — but documented ones are."
+
+### Stats
+
+- **822 tests** (unchanged from rc.2 — test repurposed, not added).
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All required CI gates pass locally.
+- Per-file watcher.ts branch floor: 71% → 69% (documented in `scripts/check-per-file-coverage.mjs` with rc.4+ uplift path).
+
+### v3.8.0 remaining backlog (next RCs)
+
+- **K-3** — `readOnlyHint: true` → no destructive operations structural invariant.
+- **R-10** — HNSW + privacy under-return fix (over-fetch margin tuning).
+- **T-1..T-5** — test coverage gaps (`contextPack`, `get_communities` handler E2E, `hyde_search` E2E, `serve-http` cli.test E2E).
+- **4/5 reranker E2E in CI** with model-cache strategy.
+- **OCR'd PDF watcher embed-sync** (deferred from rc.3).
+- **HNSW in-memory update** alongside watcher upserts (architectural).
+- **`src/embed-pipeline.ts` extraction** so the helpers move out of the `RESTRICTED_MODULES` list in `no-internal-imports.test.ts` → unit-testable → lift watcher.ts branch floor back to ≥71%.
+
+## [3.8.0-rc.2] — 2026-05-20
+
+> **TL;DR:** Second v3.8.0 release candidate. Closes **R-7 watcher → embed-db sync** (multiple audit rounds, biggest user-visible gap). Pre-3.8.0 the `--watch` flag only kept FTS5 in sync; embed-db drifted silently until manual `enquire-mcp build-embeddings` rebuild, slowly degrading semantic-search quality across a session. Now: when `--watch` is on AND the embed-db file exists, the watcher re-embeds + upserts changed `.md` files in real-time. Ships under `@rc` dist-tag.
+
+**Minor — second v3.8.0 release candidate.**
+
+### R-7 — Watcher → embed-db sync (multi-audit round backlog)
+
+**Background**: this was the largest open architectural item in the round-14 → round-22 cascade. Users on `--use-hnsw` or persistent semantic search edited their vault, saw FTS5 results update via the watcher, but semantic-search results stayed frozen at the last `build-embeddings` snapshot. The drift was invisible until the user noticed a search result not finding a recently-edited note.
+
+**Implementation**:
+
+1. **Extracted `embedSingleNote(vault, embedder, entry, opts)` helper** in `src/server.ts`. Pre-3.8.0 the chunk + embed + row-build logic lived inline inside `syncEmbedDb`'s loop; not reusable. Now shared between bulk sync + watcher.
+
+2. **Added `VaultWatcher.attachEmbed(embedDb, embedder, lateChunkContext)`** method in `src/watcher.ts`. Allows post-construction wiring of the embed-db + embedder pair (necessary because the watcher boots BEFORE HNSW init completes — HNSW build can take 25s+; the watcher needs to be capturing file events the moment serve starts).
+
+3. **`prepareServerDeps` opens a watcher-owned embed-db handle** when `--watch` is on AND the embed-db file exists. Separate handle from the HNSW init's short-lived rebuild scan handle. SQLite WAL mode allows concurrent opens; MVCC keeps state consistent. Peek-before-open pattern (CRIT-1 v3.6.1) honored: existing meta drives model alias + dim + quantization to avoid DROP TABLE on mismatch.
+
+4. **Watcher's `handle()` dispatches embed-sync after FTS5 update**:
+   - `unlink` event on `.md` → `embedDb.deleteNote(relPath)`
+   - `add` / `change` on `.md` → `embedSingleNote(...)` → `embedDb.upsertNote(relPath, mtime, rows)` (or `deleteNote` if note becomes empty)
+   - Failures are LOGGED but DON'T fail the watcher — FTS5 update already succeeded; embed-db will resync on next bulk build. Same fail-soft posture as existing FTS5 path.
+
+5. **Shutdown handler closes the watcher-owned embed-db** via SIGINT / SIGTERM / beforeExit — both stdio path (`server.ts`) and HTTP path (`http-transport.ts`).
+
+### What's NOT in rc.2 (deferred to rc.3)
+
+- **PDF embed-db sync via watcher**: rc.2 handles only `.md` for embed-sync. PDF embed updates need to also re-chunk via pdf.ts + embed each chunk — slightly larger refactor. Markdown is the higher-value first cut (most user vaults are markdown-heavy).
+- **OCR'd PDF embed sync**: same as above + the OCR path is opt-in.
+- **HNSW signature mismatch on individual upsert**: rc.2 leaves HNSW signature stale after watcher updates. On next serve start, the signature-mismatch detection triggers a rebuild. Real-time HNSW index update would require maintaining the in-memory HNSW alongside upserts (architectural).
+
+### Test coverage
+
+`tests/watcher.test.ts` — 2 new R-7 tests:
+- **Positive**: `.md` add → embed-db chunks appear (uses MOCK embedder, no 120MB model download in CI). Subsequent `.md` unlink → chunks dropped.
+- **Negative-control**: PDF events DO NOT touch embed-db (md-only for rc.2).
+
+Plus the existing 4 watcher tests still pass.
+
+### How to use
+
+```bash
+enquire-mcp serve \
+  --vault ~/Obsidian/MyVault \
+  --persistent-index \
+  --use-hnsw \
+  --watch
+```
+
+(or `serve-http` with same flags via the v3.8.0-rc.1 R-3 fix.)
+
+Now editing a note in Obsidian → ~250-500ms later → embeddings auto-update → next semantic search includes the latest changes.
+
+### Stats
+
+- **822 tests** (+2 from R-7 tests). Was 820 in v3.8.0-rc.1.
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All required CI gates pass locally.
+
+### v3.8.0 remaining backlog (next RCs)
+
+- **K-3** — `readOnlyHint: true` → no destructive operations structural invariant.
+- **R-10** — HNSW + privacy under-return fix (over-fetch margin tuning).
+- **T-1..T-5** — test coverage gaps (`contextPack`, `get_communities` handler E2E, `hyde_search` E2E, `serve-http` cli.test E2E).
+- **4/5 reranker E2E in CI** with model-cache strategy.
+- PDF embed-sync via watcher (deferred from rc.2).
+
+## [3.8.0-rc.1] — 2026-05-20
+
+> **TL;DR:** First release candidate for the v3.8.0 architectural milestone. Closes **R-3 serve-http feature parity** (round-20 audit) — 8 advanced retrieval flags that were silently missing from `serve-http` are now available, with a CLI-parity invariant test to prevent future drift. Ships under `@rc` dist-tag; v3.7.x remains `@latest` until v3.8.0 stable.
+
+**Minor — v3.8.0 release candidate.**
+
+### R-3 — serve-http feature parity (round-20 audit)
+
+Pre-3.8.0, `serve` accepted 8 advanced retrieval flags that `serve-http` did NOT register:
+- `--include-pdfs` (v2.8.0 — PDF FTS5/embedding indexing)
+- `--enable-reranker` (v2.9.0 — BGE cross-encoder)
+- `--reranker-model <alias>` (v2.9.0 / v3.3.0 — alias registry)
+- `--reranker-top-n <n>` (v2.9.0 — top-N to rerank)
+- `--use-hnsw` (v2.13.0 — in-memory ANN)
+- `--hnsw-ef <n>` (v2.13.0 — search beam width)
+- `--late-chunk-context <chars>` (v2.15.0 — context windowing)
+- `--no-hnsw-persist` (v2.16.0 — disable sidecar)
+
+**Impact**: HTTP-mode users (claude.ai web, ChatGPT, mobile MCP clients) got a strictly less-featured retrieval stack than stdio users despite the "same server, same tools, same indexes" framing in `docs/http-transport.md`. Specifically: no cross-encoder reranking, no HNSW ANN, no PDF indexing, no late-chunking — half the v3.7.x retrieval stack was inaccessible via remote MCP.
+
+**Fix**: extracted `addAdvancedRetrievalOptions(cmd: Command): Command` helper in `src/cli.ts`. Applied to BOTH `serve` and `serve-http`. Flag values flow through automatically because `ServeOptions` (in `src/server.ts`) already defines all 8 fields, and `serve-http`'s action handler does `...(opts as ServeOptions)` to spread all options into `HttpServeOptions`.
+
+### CLI-parity invariant test
+
+New `tests/cli-parity.test.ts` asserts both subcommands register the same 8 advanced retrieval flags. Two tests:
+1. **Positive**: both `serve` and `serve-http` registration blocks include all 8 flags (via the shared helper).
+2. **Negative-control**: the `addAdvancedRetrievalOptions` helper body itself must define exactly 8 flags (not more, not fewer) — catches accidental scope creep AND missing flags.
+
+If a future PR adds a new retrieval flag to only ONE command, OR drops a flag from the helper, CI fails on this test. **Structural enforcement > comment promises.**
+
+### Architectural items still deferred to v3.8.0 stable
+
+The full v3.8.0 milestone scope (multi-RC sequence):
+- **R-7 — watcher → embed-db sync** on .md changes (currently only FTS5 syncs)
+- **K-3 — `readOnlyHint: true` → no destructive operations** structural invariant
+- **R-10 — HNSW + privacy under-return** fix (over-fetch margin tuning)
+- **T-1 … T-5 — test coverage gaps** (`contextPack`, `get_communities` handler E2E, `hyde_search` E2E, `serve-http` cli.test E2E)
+- **4/5 reranker E2E in CI** (model-cache strategy to avoid 110 MB download per CI run)
+
+Each is multi-day work; the rc sequence will land them incrementally.
+
+### Stats
+
+- **820 tests** (+2 from CLI parity test). Was 818 in v3.7.20.
+- Dist-tag on npm: `@rc` (NOT `@latest`). v3.7.20 remains the recommended `@latest` channel.
+- All 8 required CI gates pass locally.
+
+### How to try v3.8.0-rc.1
+
+```bash
+npm install -g @oomkapwn/enquire-mcp@rc
+# or pin
+npm install @oomkapwn/enquire-mcp@3.8.0-rc.1
+```
+
+Then in `serve-http` mode, the 8 advanced retrieval flags are now accepted:
+```bash
+enquire-mcp serve-http \
+  --vault ~/Obsidian/MyVault \
+  --bearer-token-env ENQUIRE_BEARER_TOKEN \
+  --persistent-index \
+  --include-pdfs \
+  --enable-reranker \
+  --use-hnsw \
+  --watch
+```
+
 ## [3.7.20] — 2026-05-20
 
 > **TL;DR:** Round-22 deep audit on classes never explicitly swept (ε privacy, ζ DoS caps, μ input sanitization, ν error info disclosure). **2 findings closed**, plus a class-coverage matrix added to the audit ledger. Classes μ (input sanitization) and ζ (DoS caps) verified CLEAN.