@lincoln504/pi-research 1.6.18 → 1.6.20

package/dist/thread-worker.mjs

@@ -2699,6 +2699,13 @@ var ConfigSchema = Type.Object({
   WORKER_CONCURRENCY: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
   /** Knowledge store isolation mode (default: 'global' — one shared store across every directory) */
   KNOWLEDGE_STORE_MODE: Type.Union([Type.Literal("none"), Type.Literal("project"), Type.Literal("global")], { default: "global" }),
+  /** Knowledge store retrieval strategy (default: 'vector' — current hybrid dense+sparse behavior).
+   *  'vector' = hybrid search (embedding similarity + BM25/FTS fused via RRF; requires the
+   *  optional @huggingface/transformers dependency and a downloaded embedding model).
+   *  'bm25'   = pure lexical/BM25 retrieval over the same stored findings — NO embedding model:
+   *  never initialized, downloaded, or invoked. Uses a separate lexical table in the same
+   *  LanceDB database, so existing vector stores are untouched (no migration). */
+  KNOWLEDGE_STORE_RETRIEVAL: Type.Union([Type.Literal("vector"), Type.Literal("bm25")], { default: "vector" }),
   /** Embedding model to use for the knowledge store */
   EMBEDDING_MODEL: Type.String({ default: "onnx-community/granite-embedding-small-english-r2-ONNX" }),
   /** Hardware backend for embeddings: 'auto' (probe WebGPU viability out-of-process, fall back to CPU), 'webgpu' (force), or 'cpu' (force).

package/docs/AGENT-SKILL.md

@@ -125,7 +125,7 @@ Manual. Symlink the directory into any agent's skills folder yourself:
 
 ### Prerequisites
 
-- Node.js >= 22.19.0
+- Node.js >= 22.22.2
 - `pi-research` installed where the launcher can find it, plus a configured model
   (`PI_RESEARCH_MODEL`) + API key. See [Configuration](CONFIGURATION.md).
 

package/docs/CHANGELOG.md

@@ -5,8 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.6.18]
+## [1.6.20] - 2026-09-21
 
+### Added
+
+- **BM25-only (lexical) knowledge-store retrieval mode: the store can now run entirely without an embedding model** (merged PR #14 by @akmalayari). A new project-scoped setting, `PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL` (`vector` — the default and unchanged hybrid behavior — or `bm25`), selects how stored findings are retrieved. In `bm25` mode, retrieval is pure BM25 over LanceDB's Tantivy full-text indexes (the same lexical half the hybrid path already used, now standing alone over the summary text and full page Markdown) — the `@huggingface/transformers` dependency is never resolved, loaded, downloaded, or invoked, so a bm25-only installation works with `--omit=optional` and no model download. Each strategy keeps its own table in the same database directory (`knowledge` vs `knowledge-bm25`), so switching requires no migration and existing vector stores are untouched. The mode is exposed everywhere the scoping mode is: `knowledge-config set retrieval <vector|bm25>` and `show` on the CLI, a Knowledge Retrieval entry in the `/research-config` menu (embedding model/device entries hide in bm25 mode), the healthcheck, and the availability probe — which in bm25 mode no longer demands the optional embedding package. New tests cover the lexical round-trip, BM25 ranking sanity, scope isolation, cross-mode coexistence, per-mode availability probing, config parsing, and a hard embedder-factory-never-called isolation assertion; docs (KNOWLEDGE-STORE.md, CONFIGURATION.md, `.env.example`) document the three-way scoping × retrieval story.
+
+### Changed
+
+- **pi packages updated to the 0.87.0 line and the compatibility floor/tested-ceiling moved to match.** `@earendil-works/pi-ai`, `pi-coding-agent`, `pi-server` and `pi-tui` move `>=0.85.0 <1` → `>=0.87.0 <1` (all four verified at 0.87.0); `PI_MIN_VERSION` and `PI_TESTED_MAX_VERSION` move 0.85.0 → 0.87.0 with the floor's rationale updated for the 0.86 pi-ai TranscriptContext / JSON-value / fail-closed-user_bash changes and the 0.87 `SessionEntry` union (`ContextEditEntry`), SessionManager-canonical provider context, and `shouldStopAfterTurn` → `finishTurn` boundary. All four type-checks, lint, and the full unit suite (3,120 tests) pass against the 0.87.0 packages; `src/index.ts`'s runtime-check comment tracks the new floor.
+- **`@lancedb/lancedb` moves 0.38.0 → 0.39.0** (same-semver native store; the full unit suite passes against it, and the `apache-arrow` hold below was re-verified against the new native reader — the 21.2.0 IPC failure reproduces identically under 0.39.0).
+
+### Fixed
+
+- **CodeQL alert #267 (`js/unused-local-variable`, note): an unused `vi` import left in the PR #14 test file `store-bm25.test.ts` is removed.** Caught by the CodeQL run on the merge commit; no other open alerts remain.
+- **Dependency holds re-verified and enforced again after an attempted refresh:** `apache-arrow` stays 21.1.0 — 21.2.0 breaks `@lancedb/lancedb` 0.39.0's IPC schema parsing (the RangeOutOfBounds footer error reproduces in the test runner; a create-then-read of the store schema fails at `createTable`), confirming the existing hold against the new native reader; `playwright-core` stays 1.60.0 (camoufox-js 0.12.0's peer range still caps `<1.61.0` — 1.63.0 fails `npm install` with ERESOLVE); `@huggingface/transformers` stays 4.2.0 (4.3.0 pulls `onnxruntime-node` 1.30.0 and reshuffles the optional native stack for no needed gain, per the 1.6.18 hold); `typebox` moves 1.3.7 → 1.3.27, realigning the lockstep rule with the new host line (pi 0.87.0's own packages pin 1.3.27 — 1.3.34 was briefly tried and reverted for breaking that rule). Dev-only in-range bumps: `eslint` 10.10.0 → 10.11.0, `@typescript-eslint/*` 8.70.0 → 8.70.1.
+
+## [1.6.19] - 2026-09-18
+
+### Added
+
+- **`scripts/verify-changelog.cjs`: a release gate that the tagged commit carries a dated changelog section for its version.** The release path validated the tag against `package.json` and `SKILL.md` but never against `docs/CHANGELOG.md`, so a release could be tagged with its changes still sitting under `## [Unreleased]` — which happened twice. `v1.6.12`'s block was later folded into `[1.6.13]` (misattributing it), and `v1.6.17`'s was overwritten by the next release and lost outright. The gate fails closed on a missing, undated, empty, duplicated, or non-newest section; it is unit-tested (`test/unit/scripts/verify-changelog.test.ts`, 11 cases) and runs in CI's lint job and in the release workflow's pre-publish job. The two historical gaps are repaired in the same pass: `[1.6.17]` is restored from git, `[1.6.12]` is reconstructed from the commits in `v1.6.11..v1.6.12` (the Stack Exchange clickable-link fix and the explicit `vite` devDependency, both of which `[1.6.13]` had absorbed, plus the previously undocumented Japanese translation), and `[1.6.18]` gains its missing date.
+
+### Changed
+
+- **README: the adm-zip advisory bullet is removed from the requirements/limitations list.** It only asserted the absence of advisories, which is the audit gate's job (`docs/AUDIT-GATE.md`), not a user-facing limitation. The stealth-browser size claim is corrected from "~500MB" to "1GB+ installed" (the Linux asset downloads at ~630MB and unpacks to ~1.3GB).
+- **Supported Node floor raised from 22.19.0 to 22.22.2** (`engines.node`, `.nvmrc`, README, `docs/AGENT-SKILL.md`, `docs/SDK.md`, all three translations, the `agent-skill` README, the `scripts/setup.cjs` check + warning, and the lockfile root). `jsdom` 30 — a production dependency — and `npm` 12, which CI's install jobs run, both declare `^22.22.2 || ^24.15.0 || >=26.0.0`, so the old floor installed a tree outside its own dependency's support. CI's npm upgrade moved to a separate-prefix install as a result (see Fixed).
+- **Two stale in-code comments that still named the pre-0.85.0 pi floor are corrected to 0.85.0** (`src/core/pi-version.ts`, `src/index.ts`). No behavioral or dependency change.
+
+### Fixed
+
+- **CI no longer upgrades npm by replacing the bundled npm in place.** Node 22.22.2 bundles npm 10.9.7, which cannot install a new npm over itself: the reify deletes npm's own `node_modules` entries while the running process still needs them, and it dies with `Cannot find module 'promise-retry'` (reproduced locally on v22.22.2; CI runs 35414345489 and 35414867837, the ubuntu/macOS unit-test and validate legs). `--force`, `--ignore-scripts` and `--no-audit` all reproduce it, so `--force` was never the fix and the original comment's engines rationale was wrong. `scripts/use-npm12.cjs` installs npm 12 into a separate prefix and puts it on PATH; the release workflow's `publish` job does the same inline for npm 11, which self-upgraded on the same Node and would otherwise have failed the publish.
+
+## [1.6.18] - 2026-09-16
 ### Fixed
 
 - **`buildSafeOptions` no longer sends the literal `'off'` reasoning level into pi-ai's compat API (merged PR #13 by @lukey03).** pi-ai 0.85.1's compat path treats any truthy `reasoning` as thinking-enabled, and `'off'` has no entry in its thinking-budget table, so `maxTokens` was computed as `NaN` and serialized as `max_tokens: null` — every coordinator/plan call 400'd on providers that validate the cap (observed on Fireworks' anthropic-messages endpoint, where research never got past the first planning call). `'off'` now crosses the boundary as `undefined`, pi-ai's no-reasoning value; explicit non-off levels, caller precedence, and the maxTokens cap are unchanged. The new `build-safe-options.test.ts` drives the real compat `completeSimple` against a stubbed transport and asserts on the actual request body (5 of its 9 tests fail pre-patch); the one coordinator-boundary assertion that expected the literal `'off'` was updated to the compat contract.
@@ -20,6 +51,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **README: the "Currently recommended model" line is removed** (leaving the README with no model endorsement), and the leftover double blank line it left behind is fixed.
 - **Dev dependency lockfile refresh, all in-range: `vitest` 5.0.0 → 5.0.1, `@vitest/coverage-v8` 5.0.0 → 5.0.1, `vite` 8.2.2 → 8.3.0, `dependency-cruiser` 18.2.0 → 18.3.1, `jsdom` 30.0.1 → 30.1.0, `webgpu` 0.6.0 → 0.6.1.** Deliberate holds re-verified and unchanged: `typebox` stays 1.3.7 (lockstep with the host pi 0.85.1 line), `apache-arrow` stays 21.1.0 (21.2.0 breaks LanceDB IPC), `playwright-core` stays 1.60.0 (camoufox-js 0.12.0 peers `<1.61.0`), `typescript` stays `<6.1.0` (@typescript-eslint peer ceiling), and `@huggingface/transformers` stays 4.2.0 (4.3.0 pulls an `onnxruntime-web` dev build, `1.31.0-dev.20260914`, and reshuffles the optional native stack for no needed gain). The full gate suite is green: lint, all four type-checks (TS 6 and TS 7 native, src and tests), 3,073 unit tests, dependency-cruiser, build + manifest verify, and the audit gate with an empty allowlist.
 
+## [1.6.17] - 2026-09-09
+
+### Changed
+
+- **README: the adm-zip limitation bullet is trimmed to its essentials.** It no longer walks through the consumer-CI consequence (`npm audit` exiting nonzero until the upstream fix ships) or re-states the verified mechanics — installs succeed, don't run `npm audit fix --force`, details in `docs/AUDIT-GATE.md` — because pi-research is a research tool, not a CI component, and the full verified impact matrix lives in the runbook. No behavioral or dependency change.
+
 ## [1.6.16] - 2026-09-09
 
 ### Added
@@ -64,14 +101,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`npm ci` under npm 12 rejected the lockfile an `npm update` had rewritten** (this release cycle's own dep refresh): the rewrite dropped the `node-domexception@1.0.28` alias entry backing the `@nolyfill/domexception` override while leaving a stale real `node-domexception@1.0.0` copy nested under `@earendil-works/pi-coding-agent`. npm 11 (the local dev npm) accepted the tree; CI's npm 12 is stricter and failed every `npm ci --legacy-peer-deps` leg. The lockfile was regenerated with npm 12 itself, which collapses the stale nested copy so the override is the only resolution; `npm ci --legacy-peer-deps` now validates clean under both npm 11 and npm 12, and CI is green cross-OS.
 
-- **Stack Exchange tool output can no longer open a real browser tab when clicked.** The tool's formatters emitted markdown links (`[title](link)`) and bare URLs, and question/answer bodies carried third-party markup — any markdown-rendering surface (assistant replies, research reports, the terminal UI, which turns markdown links AND bare URLs into OSC 8 terminal hyperlinks and opens them in the system browser on mouse press+release) turned these into click-to-open-tab targets in the middle of scrolling tool output. New `src/utils/plain-url.ts` fixes this at the source, cross-platform and renderer-independent: `plainUrl()` wraps every emitted URL in backticks (code spans tokenize before autolink/link parsing in every CommonMark renderer, so a code-spanned URL can never become a link but stays byte-exact and copyable for the model), and `fenceBlock()` wraps third-party body content in a fenced code block whose length grows past any backtick run in the content (embedded links, headings and tables render inert; content containing its own ``` fences cannot close the fence early). All stackexchange formatters (questions, answers, users, sites, compact variants, and the `get`+compact path) now emit code-spanned URLs and own-line-fenced bodies — fence placement matters: an opening fence inline after `- **Body:**` is NOT recognized as a code block by CommonMark and was verified (against pi's bundled `marked`) to still render embedded links clickable, so the fence starts on its own line. The tool's prompt guidelines now also instruct the model never to re-emit result URLs as markdown links, covering the assistant-echo path. Pinned by `test/unit/stackexchange/output/no-clickable-links.test.ts`, which scans each formatter's clickable surface (post code-span/fence stripping) for link syntax and — when `marked` is resolvable — renders the actual output and asserts zero anchor elements.
-
-- **CI: declare `vite` as an explicit devDependency.** CI installs with `--legacy-peer-deps`, which skips peer dependency resolution — `vite` was only reachable as a transitive peer and the install could not resolve it. Now declared directly.
-
 ### Verified
 
 - 3,064 unit tests over 242 files, ESLint clean, all four type-checks (TS 6 src + tests, TS 7 native src + tests), dependency-cruiser and madge clean (190 modules, no circular dependencies), build, and `npm ci --dry-run` manifest verification; `npm audit` reports 0 vulnerabilities. The packed tarball was installed into a clean project: pi 0.85.1 resolves fresh, the documented dual apache-arrow layout (21.1.0 nested / 18.1.0 hoisted for LanceDB) reproduces, and the installed CLI boots. CI green cross-OS (ubuntu ×2, macOS, Windows) including the consumer fresh-install and Arrow/LanceDB interop legs. For this cycle additionally: the tarball installed and the CLI booted under npm 10, npm 11, and npm 12 alike, with the dual apache-arrow layout identical across all three.
 
+## [1.6.12] - 2026-09-07
+
+### Added
+
+- **Consolidated Japanese translation** (`docs/DOCUMENTATION-JA.md`), listed after the zh-CN doc in the README.
+
+### Fixed
+
+- **Stack Exchange tool output can no longer open a real browser tab when clicked.** The tool's formatters emitted markdown links (`[title](link)`) and bare URLs, and question/answer bodies carried third-party markup — any markdown-rendering surface (assistant replies, research reports, the terminal UI, which turns markdown links AND bare URLs into OSC 8 terminal hyperlinks and opens them in the system browser on mouse press+release) turned these into click-to-open-tab targets in the middle of scrolling tool output. New `src/utils/plain-url.ts` fixes this at the source, cross-platform and renderer-independent: `plainUrl()` wraps every emitted URL in backticks (code spans tokenize before autolink/link parsing in every CommonMark renderer, so a code-spanned URL can never become a link but stays byte-exact and copyable for the model), and `fenceBlock()` wraps third-party body content in a fenced code block whose length grows past any backtick run in the content (embedded links, headings and tables render inert; content containing its own ``` fences cannot close the fence early). All stackexchange formatters (questions, answers, users, sites, compact variants, and the `get`+compact path) now emit code-spanned URLs and own-line-fenced bodies — fence placement matters: an opening fence inline after `- **Body:**` is NOT recognized as a code block by CommonMark and was verified (against pi's bundled `marked`) to still render embedded links clickable, so the fence starts on its own line. The tool's prompt guidelines now also instruct the model never to re-emit result URLs as markdown links, covering the assistant-echo path. Pinned by `test/unit/stackexchange/output/no-clickable-links.test.ts`, which scans each formatter's clickable surface (post code-span/fence stripping) for link syntax and — when `marked` is resolvable — renders the actual output and asserts zero anchor elements.
+
+- **CI: declare `vite` as an explicit devDependency.** CI installs with `--legacy-peer-deps`, which skips peer dependency resolution — `vite` was only reachable as a transitive peer and the install could not resolve it. Now declared directly.
+
 ## [1.6.11] - 2026-09-04
 
 ### Changed

package/docs/CONFIGURATION.md

@@ -27,6 +27,7 @@ variables still take effect.) A setting is written to one of two scopes:
 |---------|-------|--------|---------|
 | `/research` depth | project | normal · deep · ultra | `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` |
 | Knowledge Mode | project | none · project · global | `PI_RESEARCH_KNOWLEDGE_STORE_MODE` |
+| Knowledge Retrieval | project | vector · bm25 | `PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL` |
 | Researcher Timeout | user | 3 · 5 · 10 · 15 · 20 · 30 (minutes) | `PI_RESEARCH_TIMEOUT_MS` |
 | Max Concurrency | user | 1 – 5 | `PI_RESEARCH_MAX_RESEARCHERS` |
 | Scrape Batches | user | unlimited · 1 · 2 · 3 · 5 · 10 · 15 | `PI_RESEARCH_MAX_SCRAPE_BATCHES` |
@@ -127,7 +128,8 @@ See the [knowledge store doc](KNOWLEDGE-STORE.md) for what each value does.
 
 | Variable | Default | Range | Description |
 |----------|---------|-------|-------------|
-| `PI_RESEARCH_KNOWLEDGE_STORE_MODE` (TUI) `[project]` | `global` | none · project · global | Store scope: one shared store across every directory (`global`), scoped to the current directory (`project`), or disabled (`none`). Independently of this setting, the store is cleanly OFF when its required packages are not installed (optional `@huggingface/transformers` skipped at install, broken `@lancedb/lancedb`): init fails fast instead of retry-storming, and `pi-research knowledge-config`, the `/research-config` menu, and the healthcheck all name the missing package and the repair. |
+| `PI_RESEARCH_KNOWLEDGE_STORE_MODE` (TUI) `[project]` | `global` | none · project · global | Store scope: one shared store across every directory (`global`), scoped to the current directory (`project`), or disabled (`none`). Independently of this setting, the store is cleanly OFF when its required packages are not installed (optional `@huggingface/transformers` skipped at install, broken `@lancedb/lancedb`): init fails fast instead of retry-storming, and `pi-research knowledge-config`, the `/research-config` menu, and the healthcheck all name the missing package and the repair. In `bm25` retrieval mode the embedding package is not required at all. |
+| `PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL` (TUI) `[project]` | `vector` | vector · bm25 | Retrieval strategy: `vector` = hybrid (embedding similarity + BM25 fused via RRF; needs the optional embedding model), `bm25` = pure lexical BM25 (no embedding model — never downloaded or initialized; works with `--omit=optional`). Each strategy keeps its own table in the same database directory, so switching requires no migration. |
 | `PI_RESEARCH_EMBEDDING_MODEL` (TUI) | `onnx-community/granite-embedding-small-english-r2-ONNX` | — | Embedding model. Changing it clears the store and starts fresh. |
 | `PI_RESEARCH_EMBEDDING_DEVICE` (TUI) | `auto` | auto · webgpu · cpu | Inference backend. `auto` probes WebGPU viability out-of-process and falls back to CPU; `cpu` forces CPU; `webgpu` forces the GPU path with no probe (advanced — can hard-crash on a software GPU). The TUI exposes only `auto` (as "GPU") and `cpu`. |
 | `PI_RESEARCH_CACHE_TTL_DAYS` (TUI) | `30` | 1–365 | How long cached findings are kept before eviction. |

package/docs/KNOWLEDGE-STORE.md

@@ -58,6 +58,35 @@ The embedding model is lazy — it only downloads and initializes the first time
 the store is actually written or searched, so the `global` default adds no startup
 cost until a run caches its first page.
 
+### Retrieval strategies: vector (hybrid) and bm25 (lexical)
+
+Independent of scope, the store's retrieval strategy is set by
+`PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL` (a project-scoped setting, default
+`vector`):
+
+| Strategy | Behavior |
+|----------|----------|
+| `vector` (default) | Hybrid search: embedding similarity + BM25 keyword matching over the stored summaries and full page text, fused via reciprocal rank fusion (RRF). Richest matching, especially for paraphrases. Requires the optional `@huggingface/transformers` dependency and a downloaded embedding model. |
+| `bm25` | Pure lexical search: BM25 ranking over the same stored summaries and full page text. **No embedding model** — never downloaded, initialized, or invoked — so a bm25-only installation works with `--omit=optional` and adds no model download. |
+
+Change the strategy for the current directory with the `/research-config` TUI
+(Knowledge Retrieval), or with `pi-research knowledge-config set retrieval
+<vector|bm25>` on the standalone CLI. Like Knowledge Mode, it persists to the
+per-directory project registry and applies without a restart.
+
+The two strategies keep **separate tables** in the same database directory
+(`knowledge` for vector, `knowledge-bm25` for bm25). An existing vector store is
+never touched by bm25 mode and vice versa — switching strategies requires no
+migration, and each mode keeps its own history while the other is active. In
+`bm25` mode, `exportKnowledge()` omits vectors, and the embedding settings
+(`PI_RESEARCH_EMBEDDING_MODEL`, `PI_RESEARCH_EMBEDDING_DEVICE`,
+`PI_RESEARCH_EMBEDDING_MODEL_INIT_TIMEOUT_MS`) are ignored entirely.
+
+BM25 ranking uses Tantivy (LanceDB's full-text engine) with its default Unicode
+tokenization and lowercasing, over both the summary text and the full page
+Markdown — so lexical mode matches the same fields the hybrid mode's keyword
+half does.
+
 ### How a run uses the store
 
 The store is driven by the orchestrator, not called ad hoc by researcher agents,
@@ -76,6 +105,9 @@ synthesized answer with citations — or reports that live research is needed.
 
 ### Embeddings and the model
 
+Applies to the `vector` (hybrid) retrieval strategy only — `bm25` mode runs with
+no embedding model at all.
+
 Embeddings are computed locally with
 [`@huggingface/transformers`](https://github.com/huggingface/transformers.js) over
 ONNX. The default model is
@@ -173,7 +205,8 @@ keep history longer.
 
 ### Changing the model: migration
 
-When the configured embedding model differs from the one the stored vectors were
+Applies to the `vector` retrieval strategy. When the configured embedding model
+differs from the one the stored vectors were
 built with, the store is migrated according to `PI_RESEARCH_MIGRATION_STRATEGY`:
 
 | Strategy | What happens |
@@ -209,12 +242,13 @@ indices are pruned to keep it bounded. There is no manual maintenance command.
 | Setting | Variable | Default |
 |---------|----------|---------|
 | Knowledge Mode (project-scoped) | `PI_RESEARCH_KNOWLEDGE_STORE_MODE` | `global` |
-| Embedding model | `PI_RESEARCH_EMBEDDING_MODEL` | `onnx-community/granite-embedding-small-english-r2-ONNX` |
-| Embedding device | `PI_RESEARCH_EMBEDDING_DEVICE` | `auto` |
+| Retrieval strategy (project-scoped) | `PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL` | `vector` |
+| Embedding model (vector mode only) | `PI_RESEARCH_EMBEDDING_MODEL` | `onnx-community/granite-embedding-small-english-r2-ONNX` |
+| Embedding device (vector mode only) | `PI_RESEARCH_EMBEDDING_DEVICE` | `auto` |
 | Cache retention (days) | `PI_RESEARCH_CACHE_TTL_DAYS` | `30` |
 | Migration strategy | `PI_RESEARCH_MIGRATION_STRATEGY` | `backup` |
 | Database directory | `PI_RESEARCH_KNOWLEDGE_DIR` | `~/.pi/research/knowledge_db` |
-| Model init timeout (ms) | `PI_RESEARCH_EMBEDDING_MODEL_INIT_TIMEOUT_MS` | `300000` |
+| Model init timeout, vector mode only (ms) | `PI_RESEARCH_EMBEDDING_MODEL_INIT_TIMEOUT_MS` | `300000` |
 | Re-probe WebGPU | `PI_RESEARCH_WEBGPU_REPROBE` | _(unset)_ |
 
 See [CONFIGURATION.md](CONFIGURATION.md) for the full configuration model, and

package/docs/SDK.md

@@ -50,7 +50,7 @@ global file entirely and run purely from defaults + `process.env` + `options.con
 > `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`. That applies to
 > `--experimental-transform-types` exactly as it does to
 > `--experimental-strip-types`, so neither flag helps here; a loader (or the pi
-> host) is mandatory. (`engines.node` is `>=22.19.0`.)
+> host) is mandatory. (`engines.node` is `>=22.22.2`.)
 
 ```typescript
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.6.18",
+  "version": "1.6.20",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,
@@ -73,7 +73,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=22.22.2"
   },
   "scripts": {
     "lint": "npx eslint --config config/tooling/eslint.config.js src/",
@@ -104,6 +104,7 @@
     "install:system-deps": "node scripts/setup.cjs --system-deps",
     "deps:check": "depcruise --config config/tooling/dependency-cruiser.cjs --output-type err-long src",
     "deps:generate": "npx --yes madge@8.0.0 --image docs/deps.svg src/index.ts",
+    "verify:changelog": "node scripts/verify-changelog.cjs",
     "analyze:dependencies": "ncu",
     "analyze:compatibility": "depngn"
   },
@@ -114,12 +115,12 @@
     "image": "https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/hero.png"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": ">=0.85.0 <1",
-    "@earendil-works/pi-coding-agent": ">=0.85.0 <1",
-    "@earendil-works/pi-server": ">=0.85.0 <1",
-    "@earendil-works/pi-tui": ">=0.85.0 <1",
+    "@earendil-works/pi-ai": ">=0.87.0 <1",
+    "@earendil-works/pi-coding-agent": ">=0.87.0 <1",
+    "@earendil-works/pi-server": ">=0.87.0 <1",
+    "@earendil-works/pi-tui": ">=0.87.0 <1",
     "@kreuzberg/html-to-markdown-node": "^3.7.2",
-    "@lancedb/lancedb": "0.38.0",
+    "@lancedb/lancedb": "0.39.0",
     "apache-arrow": "21.1.0",
     "bgutils-js": "^4.0.3",
     "camoufox-js": "^0.12.0",
@@ -130,7 +131,7 @@
     "pdf-oxide-wasm": "^0.3.77",
     "playwright-core": "1.60.0",
     "poolifier": "^5.3.2",
-    "typebox": "1.3.7",
+    "typebox": "1.3.27",
     "undici": "^8.10.2",
     "youtubei.js": "^18.0.0"
   },
@@ -156,12 +157,12 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/jsdom": "^30.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.70.0",
-    "@typescript-eslint/parser": "^8.70.0",
+    "@typescript-eslint/eslint-plugin": "8.70.1",
+    "@typescript-eslint/parser": "8.70.1",
     "@vitest/coverage-v8": "^5.0.1",
     "dependency-cruiser": "^18.2.0",
     "depngn": "^0.6.0",
-    "eslint": "^10.10.0",
+    "eslint": "10.11.0",
     "npm-check-updates": "^23.1.0",
     "typescript": ">=6.0.3 <6.1.0",
     "vite": "^8.2.2",

package/scripts/setup.cjs

@@ -23,9 +23,12 @@ const isLinux = process.platform === 'linux';
 const isDarwin = process.platform === 'darwin';
 const isWindows = process.platform === 'win32';
 
-const [nodeMajor, nodeMinor] = process.version.replace('v', '').split('.').map((n) => parseInt(n, 10));
-if (nodeMajor < 22 || (nodeMajor === 22 && nodeMinor < 19)) {
-  console.warn(`WARNING: Node.js ${process.version} is below the minimum (>=22.19.0). Upgrade to 22.19.0+.`);
+const [nodeMajor, nodeMinor, nodePatch] = process.version.replace('v', '').split('.').map((n) => parseInt(n, 10));
+// Minimum is 22.22.2 — the floor `jsdom` 30 (a runtime dependency) and npm 12 both declare.
+const belowMinimum =
+  nodeMajor < 22 || (nodeMajor === 22 && (nodeMinor < 22 || (nodeMinor === 22 && nodePatch < 2)));
+if (belowMinimum) {
+  console.warn(`WARNING: Node.js ${process.version} is below the minimum (>=22.22.2). Upgrade to 22.22.2+.`);
 }
 
 /**

package/src/cli.ts

@@ -8,6 +8,7 @@
  *   pi-research research "<query>" [--depth N] [--model provider/id]
  *   pi-research knowledge "<q>" ["<q2>" ...]
  *   pi-research knowledge-config [set <none|project|global>]
+ *   pi-research knowledge-config set retrieval <vector|bm25>
  *   pi-research status [--json]
  *   pi-research help
  *
@@ -895,6 +896,32 @@ export async function cmdKnowledgeConfig(kc: NonNullable<ParsedArgs['knowledgeCo
   // silently breaking the documented `--json: Emit a JSON object` contract for
   // this one subcommand.
   try {
+    if (kc.action === 'set-retrieval') {
+      const before = getConfig(cwd, 'cli').KNOWLEDGE_STORE_RETRIEVAL;
+      const cfg = { ...getConfig(cwd, 'cli'), KNOWLEDGE_STORE_RETRIEVAL: kc.retrieval! };
+      // Persist ONLY the retrieval strategy for this directory — mirrors the
+      // scoping-mode `set` branch above (changedKeys-scoped registry write).
+      saveConfig(cfg, 'local', cwd, ['PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL']);
+      resetConfig();
+      const info = describeKnowledgeStoreMode(cwd, 'cli');
+      const overridden = info.retrieval !== kc.retrieval;
+      if (kc.json) {
+        toStdout(pretty({ command: 'knowledge-config', action: 'set-retrieval', requested: kc.retrieval, previous: before, saved: true, effectiveOverriddenBy: overridden ? info.retrievalOrigin : null, ...info, cwd }));
+        return EXIT.OK;
+      }
+      toStdout(
+        `knowledge store retrieval for this directory: ${before} -> ${kc.retrieval}  (saved per-directory)\n` +
+        `  strategy: ${kc.retrieval === 'bm25' ? 'lexical BM25 — no embedding model needed' : 'hybrid (embedding + BM25, fused) — needs the optional embedding dependency'}\n` +
+        `  saved:    per-directory (${cwd})\n` +
+        `  db dir:   ${info.dbDir}\n` +
+        (info.available ? '' : `  state:    ${info.unavailableReason}\n`) +
+        (overridden
+          ? `\nNOTE: the effective retrieval here is still '${info.retrieval}' because a higher-precedence ${info.retrievalOrigin} overrides it. Clear that source for this setting to take effect.\n`
+          : ''),
+      );
+      return EXIT.OK;
+    }
+
     if (kc.action === 'set') {
       const before = getConfig(cwd, 'cli').KNOWLEDGE_STORE_MODE;
       const cfg = { ...getConfig(cwd, 'cli'), KNOWLEDGE_STORE_MODE: kc.mode! };
@@ -932,11 +959,14 @@ export async function cmdKnowledgeConfig(kc: NonNullable<ParsedArgs['knowledgeCo
     }
     toStdout(
       `knowledge store mode: ${info.mode}   (source: ${info.origin})\n` +
-      `  scope:   ${info.mode === 'none' ? 'disabled here' : info.mode === 'project' ? 'this directory only' : 'shared across all directories'}\n` +
-      `  db dir:  ${info.dbDir}\n` +
-      (info.available ? '' : `  state:   ${info.unavailableReason}\n`) +
-      `\nchange it for THIS directory:  ${BINARY_NAME} knowledge-config set <none|project|global>\n` +
-      `change the machine-wide default: set PI_RESEARCH_KNOWLEDGE_STORE_MODE=<mode> in ${resolvedConfigPaths().configEnv}\n`,
+      `knowledge store retrieval: ${info.retrieval}   (source: ${info.retrievalOrigin})\n` +
+      `  scope:     ${info.mode === 'none' ? 'disabled here' : info.mode === 'project' ? 'this directory only' : 'shared across all directories'}\n` +
+      `  strategy:  ${info.retrieval === 'bm25' ? 'lexical BM25 — no embedding model needed' : 'hybrid (embedding + BM25, fused)'}\n` +
+      `  db dir:    ${info.dbDir}\n` +
+      (info.available ? '' : `  state:     ${info.unavailableReason}\n`) +
+      `\nchange scope for THIS directory:     ${BINARY_NAME} knowledge-config set <none|project|global>\n` +
+      `change retrieval for THIS directory: ${BINARY_NAME} knowledge-config set retrieval <vector|bm25>\n` +
+      `change the machine-wide defaults: set PI_RESEARCH_KNOWLEDGE_STORE_MODE=<mode> and/or PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL=<vector|bm25> in ${resolvedConfigPaths().configEnv}\n`,
     );
     return EXIT.OK;
   } catch (err) {
@@ -1235,7 +1265,7 @@ interface ParsedArgs {
   command?: string;
   research?: ResearchArgs;
   knowledge?: { queries: string[]; json?: boolean };
-  knowledgeConfig?: { action: 'show' | 'set'; mode?: 'none' | 'project' | 'global'; json?: boolean };
+  knowledgeConfig?: { action: 'show' | 'set' | 'set-retrieval'; mode?: 'none' | 'project' | 'global'; retrieval?: 'vector' | 'bm25'; json?: boolean };
   status?: { json?: boolean };
   skill?: { action: 'install' | 'uninstall' | 'status'; json?: boolean; dryRun?: boolean; copy?: boolean };
   configPath?: string;
@@ -1270,6 +1300,10 @@ COMMANDS
     --json                       Emit a JSON object.
   knowledge-config set <mode>    Set the mode for THIS directory (none | project | global);
                                  persisted per-directory. Takes effect on the next run.
+  knowledge-config set retrieval <vector|bm25>
+                                 Set the retrieval strategy for THIS directory: 'vector'
+                                 (hybrid embedding+BM25, default) or 'bm25' (pure lexical,
+                                 no embedding model). Persisted per-directory.
 
   status                         Show detected config, model/key, and readiness.
     --config <path>              Layer this config file on top (highest file precedence; base
@@ -1303,6 +1337,7 @@ CONFIGURE
 
   Knowledge store — ON by default in every directory (mode 'global', one shared store).
     per-directory:  ${BINARY_NAME} knowledge-config set <none|project|global>
+                    ${BINARY_NAME} knowledge-config set retrieval <vector|bm25>
     machine-wide:   PI_RESEARCH_KNOWLEDGE_STORE_MODE=<mode>  in ${p.configEnv}
     'project' scopes the store to the current directory; 'none' disables it here.
 
@@ -1421,6 +1456,24 @@ export function parseArgs(argv: string[]): ParsedArgs {
       return out;
     }
     if (action === 'set') {
+      // Extended form: `knowledge-config set retrieval <vector|bm25>` — switches the
+      // retrieval STRATEGY (the scoping mode uses the original single-arg form).
+      if (positional[1] === 'retrieval') {
+        const retrieval = positional[2];
+        if (retrieval === undefined) {
+          throw new UsageError('knowledge-config set retrieval requires a strategy: vector | bm25.');
+        }
+        if (retrieval !== 'vector' && retrieval !== 'bm25') {
+          throw new UsageError(`invalid retrieval strategy "${retrieval}". Use one of: vector | bm25.`);
+        }
+        if (positional.length > 3) {
+          throw new UsageError(`unexpected argument "${positional[3]}" after "knowledge-config set retrieval ${retrieval}".`);
+        }
+        out.command = 'knowledge-config';
+        out.knowledgeConfig = { action: 'set-retrieval', retrieval, json };
+        out.configPath = configPath;
+        return out;
+      }
       const mode = positional[1];
       if (mode === undefined) {
         throw new UsageError('knowledge-config set requires a mode: none | project | global.');
@@ -1436,7 +1489,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
       out.configPath = configPath;
       return out;
     }
-    throw new UsageError(`unknown knowledge-config action "${action}". Use: show | set <none|project|global>.`);
+    throw new UsageError(`unknown knowledge-config action "${action}". Use: show | set <none|project|global> | set retrieval <vector|bm25>.`);
   }
 
   if (cmd === 'skill') {

package/src/config.ts

@@ -50,6 +50,13 @@ export const ConfigSchema = Type.Object({
   WORKER_CONCURRENCY: Type.Number({ minimum: 1, maximum: 10, default: 2 }),
   /** Knowledge store isolation mode (default: 'global' — one shared store across every directory) */
   KNOWLEDGE_STORE_MODE: Type.Union([Type.Literal('none'), Type.Literal('project'), Type.Literal('global')], { default: 'global' }),
+  /** Knowledge store retrieval strategy (default: 'vector' — current hybrid dense+sparse behavior).
+   *  'vector' = hybrid search (embedding similarity + BM25/FTS fused via RRF; requires the
+   *  optional @huggingface/transformers dependency and a downloaded embedding model).
+   *  'bm25'   = pure lexical/BM25 retrieval over the same stored findings — NO embedding model:
+   *  never initialized, downloaded, or invoked. Uses a separate lexical table in the same
+   *  LanceDB database, so existing vector stores are untouched (no migration). */
+  KNOWLEDGE_STORE_RETRIEVAL: Type.Union([Type.Literal('vector'), Type.Literal('bm25')], { default: 'vector' }),
   /** Embedding model to use for the knowledge store */
   EMBEDDING_MODEL: Type.String({ default: 'onnx-community/granite-embedding-small-english-r2-ONNX' }),
   /** Hardware backend for embeddings: 'auto' (probe WebGPU viability out-of-process, fall back to CPU), 'webgpu' (force), or 'cpu' (force).
@@ -211,6 +218,7 @@ export const DEFAULTS: Config = Value.Create(ConfigSchema);
 const LOCAL_SCOPE_KEYS = new Set([
   'PI_RESEARCH_DEFAULT_RESEARCH_DEPTH',
   'PI_RESEARCH_KNOWLEDGE_STORE_MODE',
+  'PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL',
 ]);
 
 /**
@@ -600,6 +608,10 @@ export interface KnowledgeStoreModeInfo {
   mode: 'none' | 'project' | 'global';
   /** Human-readable source of the EFFECTIVE value (highest-precedence source that set it). */
   origin: string;
+  /** Knowledge store retrieval strategy ('vector' hybrid — default, or 'bm25' lexical-only). */
+  retrieval: 'vector' | 'bm25';
+  /** Human-readable source of the EFFECTIVE retrieval value (same precedence walk as `origin`). */
+  retrievalOrigin: string;
   /** Physical LanceDB directory backing the store (shared across project/global modes). */
   dbDir: string;
   /**
@@ -627,34 +639,40 @@ export function describeKnowledgeStoreMode(
   iface?: ConfigInterface,
 ): KnowledgeStoreModeInfo {
   const cfg = getConfig(cwd, iface);
-  const KEY = 'PI_RESEARCH_KNOWLEDGE_STORE_MODE';
-  const fileHasKey = (p: string): boolean => {
+  const fileHasKey = (key: string, p: string): boolean => {
     try {
-      return fs.existsSync(p) && parseDotEnv(fs.readFileSync(p, 'utf-8'))[KEY] !== undefined;
+      return fs.existsSync(p) && parseDotEnv(fs.readFileSync(p, 'utf-8'))[key] !== undefined;
     } catch {
       return false;
     }
   };
 
-  let origin = 'built-in default';
-  if (process.env[KEY] !== undefined) {
-    origin = 'environment variable';
-  } else {
+  /**
+   * Walk the same precedence createConfig applies, highest first, for one env key:
+   *   env var  >  per-directory project registry  >  {iface}.env overlay  >  config.env  >  default.
+   */
+  const originFor = (KEY: string): string => {
+    if (process.env[KEY] !== undefined) {
+      return 'environment variable';
+    }
     let registryHasKey = false;
     try {
       const registry = loadProjectSettingsRegistry();
       registryHasKey = findRegistryEntry(registry, normalizeWorkspacePath(cwd))?.[KEY] !== undefined;
     } catch { /* unreadable registry → not the origin */ }
-    if (registryHasKey) origin = 'this directory (project settings)';
-    else if (iface && fileHasKey(getInterfaceEnvFilePath(iface))) origin = `${iface}.env overlay`;
-    else if (fileHasKey(getGlobalEnvFilePath())) origin = 'config.env (machine-wide default)';
-  }
+    if (registryHasKey) return 'this directory (project settings)';
+    if (iface && fileHasKey(KEY, getInterfaceEnvFilePath(iface))) return `${iface}.env overlay`;
+    if (fileHasKey(KEY, getGlobalEnvFilePath())) return 'config.env (machine-wide default)';
+    return 'built-in default';
+  };
 
   return {
     mode: cfg.KNOWLEDGE_STORE_MODE,
-    origin,
+    origin: originFor('PI_RESEARCH_KNOWLEDGE_STORE_MODE'),
+    retrieval: cfg.KNOWLEDGE_STORE_RETRIEVAL,
+    retrievalOrigin: originFor('PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL'),
     dbDir: getDbDir(cfg, cwd),
-    ...availabilityFields(),
+    ...availabilityFields(cfg),
   };
 }
 
@@ -665,8 +683,8 @@ export function describeKnowledgeStoreMode(
  * throws: the probe catches resolution errors internally and reports them as
  * `available: false`.
  */
-function availabilityFields(): { available: boolean; unavailableReason: string } {
-  const availability = probeKnowledgeStoreAvailability();
+function availabilityFields(cfg?: Config): { available: boolean; unavailableReason: string } {
+  const availability = probeKnowledgeStoreAvailability(cfg?.KNOWLEDGE_STORE_RETRIEVAL ?? getConfig().KNOWLEDGE_STORE_RETRIEVAL);
   return {
     available: availability.available,
     unavailableReason: describeKnowledgeStoreUnavailability(availability),
@@ -924,6 +942,7 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
     PI_RESEARCH_WORKER_THREADS: String(config.WORKER_THREADS),
     PI_RESEARCH_WORKER_CONCURRENCY: String(config.WORKER_CONCURRENCY),
     PI_RESEARCH_KNOWLEDGE_STORE_MODE: config.KNOWLEDGE_STORE_MODE,
+    PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL: config.KNOWLEDGE_STORE_RETRIEVAL,
     PI_RESEARCH_EMBEDDING_MODEL: config.EMBEDDING_MODEL,
     PI_RESEARCH_EMBEDDING_DEVICE: config.EMBEDDING_DEVICE,
     PI_RESEARCH_SCRAPE_TIMEOUT_MS: String(config.SCRAPE_TIMEOUT_MS),
@@ -1147,6 +1166,7 @@ export function createConfig(env: Record<string, string | undefined>, processEnv
     WORKER_THREADS: parseEnvNumber(e, 'PI_RESEARCH_WORKER_THREADS', DEFAULTS.WORKER_THREADS, 1, 10, true),
     WORKER_CONCURRENCY: parseEnvNumber(e, 'PI_RESEARCH_WORKER_CONCURRENCY', DEFAULTS.WORKER_CONCURRENCY, 1, 10, true),
     KNOWLEDGE_STORE_MODE: parseEnvEnum(e, 'PI_RESEARCH_KNOWLEDGE_STORE_MODE', ['none', 'project', 'global'] as const, 'global'),
+    KNOWLEDGE_STORE_RETRIEVAL: parseEnvEnum(e, 'PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL', ['vector', 'bm25'] as const, 'vector'),
     EMBEDDING_MODEL: parseEnvString(e, 'PI_RESEARCH_EMBEDDING_MODEL', DEFAULTS.EMBEDDING_MODEL)!,
     EMBEDDING_DEVICE: parseEnvEnum(e, 'PI_RESEARCH_EMBEDDING_DEVICE', ['auto', 'webgpu', 'cpu'] as const, DEFAULTS.EMBEDDING_DEVICE),
     SCRAPE_TIMEOUT_MS: parseEnvNumber(e, 'PI_RESEARCH_SCRAPE_TIMEOUT_MS', DEFAULTS.SCRAPE_TIMEOUT_MS, 5000, 120000),

package/src/core/pi-version.ts

@@ -7,7 +7,7 @@
  *
  *   - As a pi EXTENSION, the host supplies `@earendil-works/*`. Our package.json
  *     range never constrains it, so an in-process check is the only enforcement.
- *   - As a standalone CLI/SDK, the range is `>=0.84.0 <1` and published tarballs
+ *   - As a standalone CLI/SDK, the range is `>=0.87.0 <1` and published tarballs
  *     carry no lockfile, so every fresh install resolves the newest 0.x at that
  *     instant. pi is pre-1.0: a minor bump may break anything under semver, and
  *     already has (0.83.0 extended the ResourceLoader contract).
@@ -74,8 +74,17 @@ export function compareVersions(a: SemverParts, b: SemverParts): number {
  * indefinite-hang-in-network-restricted-environments bug that explicit
  * option originally existed to prevent. The floor moved to close that gap,
  * not just because the type changed.
+ *
+ * 0.86.0 changed the pi-ai provider stream input from Context to normalized
+ * TranscriptContext values, restricted ToolCall.arguments / ToolResultMessage
+ * details to JSON-compatible values, and made user_bash fail closed; 0.87.0
+ * added ContextEditEntry to the SessionEntry union, made SessionManager the
+ * canonical provider-context source, and replaced shouldStopAfterTurn with the
+ * finishTurn boundary. The SDK paths (session service, model-registry factory)
+ * are written against that surface; an older host may resolve but is not a
+ * tested or supported target.
  */
-export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 85, patch: 0 };
+export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 87, patch: 0 };
 
 /**
  * Newest host line this release was actually exercised against (CI + a real run).
@@ -83,7 +92,7 @@ export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 85, patch: 0 };
  * Compared on MAJOR.MINOR only: a patch bump within a tested line is not a new
  * surface, and warning on it would be noise.
  */
-export const PI_TESTED_MAX_VERSION: SemverParts = { major: 0, minor: 85, patch: 0 };
+export const PI_TESTED_MAX_VERSION: SemverParts = { major: 0, minor: 87, patch: 0 };
 
 export type PiCompatibilityLevel = 'ok' | 'unparseable' | 'too-old' | 'untested';
 

package/src/healthcheck/index.ts

@@ -196,8 +196,25 @@ export function registerHealthChecks(registry: IHealthRegistryService, container
       }
       const store = await service.getStore();
       const counts = store ? await store.countScoped() : { local: 0, global: 0, projects: 0 };
+      const retrieval = getConfig(service.getCwd()).KNOWLEDGE_STORE_RETRIEVAL;
       const embedder = await service.getEmbedder();
 
+      if (retrieval === 'bm25') {
+        // Lexical mode: no embedding model exists — null is the healthy state, not
+        // a failure. Report BM25-specific diagnostics instead of the embedder's.
+        return {
+            healthy: true,
+            diagnostic: {
+                status: 'initialized',
+                retrieval: 'bm25',
+                model: 'none (lexical BM25)',
+                localEntries: counts.local,
+                globalEntries: counts.global,
+                totalProjects: counts.projects
+            }
+        };
+      }
+
       if (!embedder) {
         return { healthy: false, error: 'Embedder service not available' };
       }
@@ -240,6 +257,7 @@ export function registerHealthChecks(registry: IHealthRegistryService, container
           healthy: true, 
           diagnostic: { 
               status: 'initialized',
+              retrieval,
               device,
               model: config.EMBEDDING_MODEL,
               localEntries: counts.local,