jekyll-client-search 0.3.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bd0e3f73bbbf16d364c059483ad2ad40382232dda34ca1e8a0f83b0286fa605
-  data.tar.gz: 643dfe41f83ab07d100fa9f841e7b80f07ce1a8db5d5e3d2e5e43d4a29880a2e
+  metadata.gz: 3e0accecae865157aa09bda9bf9df5060bcad7a45eeb55555137f963fe1cca93
+  data.tar.gz: 8bb447d56a507fb5c7a632ae38433606317bccfda3e2cb01388c129617a49b8a
 SHA512:
-  metadata.gz: 2e0e6fbfde2eaf9695f31bc4f79980f5a0d5e88b299253fde5523faa137be6606c60fecf25de2d2ed4b0e3e05d08d2afc5a9033346dd64b25c3dbde8156a44b4
-  data.tar.gz: b2cdf16bbca7714c81b6ce4a8054f94fa654a30d3e30f5c926fde2f0f3c312cc28ed66d249f3c9dcd38f03cbd9ccb40bf437ce6180c13f867928afa16c6a1f30
+  metadata.gz: bcb6ee7ce75d7b75facd5c69db2f0c8479f4e70c0d5e6830b92f65cec936235596f3eb8e97db6621e9b6ec3559868b1f34d3b3ea1b8f5610464b880b88261104
+  data.tar.gz: 1c35127143ea928d0156ba202c0c4e6a485729de69afd69e3203f45d5625e0f00848a17e2f4cfe50f9085b8c61e76d16f81b36e05ffa8f27352cb655a42f5eaf

data/CHANGELOG.md

@@ -1,6 +1,112 @@
 # Changelog
 
-## Unreleased
+## 0.5.0 — 2026-11-08
+
+### Added
+
+- `rake docs:demo` — captures the checked-in illustrative overview as
+  animated AVIF + WebP + static PNG (headless Chrome + ffmpeg + img2webp;
+  build-host tools), embedded in README via `<picture>`. Examples are
+  schematic, not generated from a live Jekyll build.
+
+- Dev-tooling bumps: `markdownlint-cli2` 0.24.0, `eslint` ~10.14.0,
+  `globals` 17.14.0, `rubocop` 1.92.2, `ollama-ruby` 1.26.0,
+  `excon` 1.11.0, `sass-embedded` 1.108.1, `addressable` 2.9.2,
+  `csv` 3.3.7, `io-console` 0.9.5, `parser` 3.3.13.0,
+  `irb` 1.19.0, `tins` 1.62.0; `BUNDLED WITH` 4.0.9 → 4.0.24.
+
+### Changed
+
+- The live dropdown now follows the ARIA combobox/listbox pattern:
+  focused input with `aria-activedescendant`, uniquely identified plain
+  text options, and no nested links inside listbox options.
+- CI Node.js matrix is now `24` / `26` — matching the `engines:
+  >=24` floor. Node 22 dropped (maintenance-only).
+- CI action pins bumped: `ruby/setup-ruby` v1.338.0,
+  `sonarqube-scan-action` v8.4.1, `semgrep` image 1.183.0.
+- `spec/search_index_page_spec.rb` expanded — now covers the default
+  root-level output path (`search-index.json`), an empty document
+  list, and field/order preservation.
+- `test/meta.test.js` cross-engine check split into one named `test()`
+  per exact-match query — a single failure no longer hides the
+  remaining queries.
+
+### Fixed
+
+- Benchmark scripts access environment via `ENV.fetch("KEY", default)`
+  instead of `ENV["KEY"] || default` (SonarQube: environment variable
+  access without a default value).
+- SonarQube coverage denominator no longer counts `benchmarks/**` —
+  the ~850 lines of manual benchmark tooling are not instrumented by
+  SimpleCov, which diluted the reported project coverage to ~50%.
+
+### Security
+
+- `overrides` pins `re2js` 2.8.8 — markdownlint 0.42.0 (via
+  markdownlint-cli2 0.24.0) pins the vulnerable 2.8.6 (ReDoS in
+  lookbehind matching, GHSA-gg6h-894w-4m9c).
+- `nokogiri` 1.19.7 (dev-only, via `ollama-ruby`) — fixes
+  GHSA-3w22-6jfg-527w (use-after-free), GHSA-4p39-36wj-23h4
+  (mutation XSS), GHSA-v995-44v6-5fqm (JRuby SSRF).
+
+## 0.4.0 — 2026-10-24
+
+- Dev-tooling bump: `jsdom` 30.1.3 (patch).
+
+### Added
+
+- `benchmarks/embedding_model_benchmark.rb`,
+  `benchmarks/related_model_benchmark.rb`, and
+  `benchmarks/related_quality_judge.rb` — measure Ollama embedding
+  latency per model on a real site, compare `related` output across
+  models, and score judged relevance with a blind LLM judge
+  (10 local embedding models benchmarked on a 152-document site).
+- `embeddinggemma-2` document/query prefixes (same prompt format as
+  `embeddinggemma`), `voyage-4-nano` prefixes (open-weight Voyage
+  model via community GGUF), and `qwen3-embedding` prefixes (official
+  instruct-format query prefix; empty document prefix).
+- README model-selection guidance: measured per-document latency table,
+  LLM-judged quality ratings, quality-per-cost value index, amortized
+  yearly cost, `qwen3-embedding` build-time-only notes, and the
+  `localhost` → `127.0.0.1` loopback gotcha.
+- Split index/related embedding models: `semantic.index_model` selects
+  the Ollama model whose vectors go into `search-index.json` (must match
+  the browser query embedder); `related.index_model` selects the model
+  used for related-article analysis. Both default to `embedding.model`;
+  equal models share one embedding pass, divergent models embed each
+  document twice into separate cached vector fields.
+  `semantic.document_prefix` / `semantic.query_prefix` override the
+  index model's prefixes. Related-model vectors are cached separately
+  in `.jekyll-client-search-related-cache.json` and never written to
+  the index.
+- `embeddinggemma-2` (`:270m`, `:570m`, untagged) maps to
+  `onnx-community/embeddinggemma-2-ONNX` for the transformers.js query
+  embedder. `test/onnx-parity.test.js` is an opt-in check
+  (`ONNX_PARITY=1`, requires `@huggingface/transformers` and a running
+  Ollama) that compares ONNX and Ollama vectors and rankings;
+  `embeddinggemma:300m` remains the verified mapping.
+
+### Changed
+
+- Default `embedding.model` is now `embeddinggemma-2:570m` (was
+  `embeddinggemma:300m`) — the judged-quality leader among license-free
+  local models (111 vs 96) at ~2.5× the per-document latency; its text
+  vectors are byte-identical to `embeddinggemma-2:270m`. The
+  transformers.js query embedder maps it to
+  `onnx-community/embeddinggemma-2-ONNX`; sites that prefer the verified
+  browser mapping can set `semantic.index_model: embeddinggemma:300m`
+  while related analysis stays on the default model.
+- CI: Semgrep moved from an inline `pip3 install semgrep==1.176.0` pin to hashed `.github/requirements-ci.txt` (compiled from `requirements-ci.in`, Python 3.12), installed with `--require-hashes`. Bumped Semgrep to 1.180.0; the version is now Dependabot-visible via a new `pip` ecosystem entry for `/.github`.
+
+### Fixed
+
+- A `localhost` `embedding.base_url` (the default) is resolved once to
+  the loopback literal that accepts a TCP connection — `127.0.0.1` or
+  `[::1]` — because `ollama-ruby`/Excon does not fall back across
+  address families and Ollama commonly listens on IPv4 loopback only.
+  Embedding calls that died with `Excon::Error::Socket "Broken pipe"`
+  when `localhost` resolved to `::1` first now connect on both
+  IPv4-only and IPv6-only servers.
 
 ## 0.3.5 — 2026-10-06
 

data/README.developer.md

@@ -20,12 +20,27 @@ Both test suites pass with only the committed Wikipedia fixtures and the
 committed baseline JSON artifacts. No network access or external services
 are required for the default test run.
 
+Specs that need a Jekyll site use `jekyll-test-harness` (`jekyll_build` +
+`jekyll_files` DSL, installed in `spec/spec_helper.rb`) instead of hand-rolled
+`Dir.mktmpdir`/`Jekyll::Site.new` scaffolding — see
+`spec/support/site_helpers.rb` and `spec/generator_spec.rb` for the pattern.
+Note that the gem's `Jekyll::ClientSearch::Generator` subclasses
+`Jekyll::Generator`, so it runs automatically inside `jekyll_build`'s
+`site.process`; specs should assert on the built site directly and stub
+`build_embedding_adapter` (see `stub_embedding_adapter`) before building
+rather than calling `generate` manually. Specs that rebuild the same source
+directory multiple times (`spec/embedding_cache_spec.rb`,
+`spec/system_spec.rb`, Ollama integration) still use their own helpers,
+since the harness builds each site in a fresh temporary directory.
+
 ## Quality checks and git hooks
 
 The project uses a focused quality stack: RuboCop (style), bundler-audit
 (security), RSpec (Ruby tests), `npm test` (JavaScript tests), and Semgrep
 (security scanning). This covers the actionable ground without the
 maintenance burden of additional code-smell tools on a small focused gem.
+`npm test` also runs ESLint, Markdownlint, and jsdom tests for the browser
+runtime, including the dropdown combobox/listbox keyboard and ARIA contract.
 
 External automated code review services:
 
@@ -112,7 +127,7 @@ CI. Skip either with `git commit --no-verify` or `git push --no-verify`.
 ### CI checks
 
 The [CI workflow](.github/workflows/ci.yml) runs on every push and pull
-request across Ruby 3.3/3.4 and Node 22/24:
+request across Ruby 3.3/3.4 and Node 24/26:
 
 - `bundle exec rake ci` (rspec, rubocop, syntax checks, npm test, gem build)
 - `bundle exec bundle-audit check --update` (Ruby dependency security)
@@ -237,9 +252,10 @@ To run the full integration tests that call a real Ollama server:
 
 1. Install [Ollama](https://ollama.ai/)
 
-2. Pull the required model:
+2. Pull the required models:
 
    ```bash
+   ollama pull embeddinggemma-2:570m
    ollama pull embeddinggemma:300m
    ```
 
@@ -250,6 +266,16 @@ To run the full integration tests that call a real Ollama server:
    OLLAMA_INTEGRATION=1 bundle exec rspec spec/llm_injection_spec.rb
    ```
 
+To verify cross-runtime parity between the transformers.js ONNX twin and
+the Ollama build model (opt-in — needs the model downloaded once):
+
+```bash
+npm i -D @huggingface/transformers@3.8.1
+ONNX_PARITY=1 node --test test/onnx-parity.test.js
+```
+
+Set `OLLAMA_MODEL`, `ONNX_MODEL`, or `ONNX_DTYPE` to check other mappings.
+
 These tests:
 
 - Build the full 80-post index with real Ollama embeddings
@@ -450,7 +476,8 @@ This check also runs in the release workflow — the publish will fail if
    ```
 
    The Ollama integration tests require a running [Ollama](https://ollama.ai/)
-   server with the `embeddinggemma:300m` model pulled (`ollama pull
+   server with the `embeddinggemma-2:570m` and `embeddinggemma:300m` models
+   pulled (`ollama pull embeddinggemma-2:570m` and `ollama pull
    embeddinggemma:300m`). Do not publish a release until the Ollama
    integration tests pass locally — they are skipped by default and will
    not block CI, so they must be run manually before each release.

data/README.md

@@ -15,7 +15,6 @@
 [![Semgrep](https://img.shields.io/badge/semgrep-scanning-brightgreen.svg)](https://semgrep.dev)
 [![CodeFactor](https://www.codefactor.io/repository/github/gundestrup/jekyll-client-search/badge)](https://www.codefactor.io/repository/github/gundestrup/jekyll-client-search)
 [![SonarQube](https://sonarcloud.io/api/project_badges/measure?project=gundestrup_jekyll-client-search&metric=alert_status)](https://sonarcloud.io/project/overview?id=gundestrup_jekyll-client-search)
-[![codecov](https://codecov.io/gh/gundestrup/jekyll-client-search/branch/main/graph/badge.svg)](https://codecov.io/gh/gundestrup/jekyll-client-search)
 
 A Jekyll plugin that generates a JSON document index for client-side search.
 Supports lexical search ([MiniSearch](https://lucaong.github.io/minisearch/),
@@ -24,6 +23,19 @@ via pre-computed embeddings from a local [Ollama](https://ollama.ai) server.
 Related articles can be generated at build time from shared tags, categories,
 and vector similarity.
 
+<!-- markdownlint-disable MD033 -->
+<picture>
+  <source
+    srcset="docs/assets/jekyll-client-search-demo.avif"
+    type="image/avif">
+  <source
+    srcset="docs/assets/jekyll-client-search-demo.webp"
+    type="image/webp">
+  <img src="docs/assets/jekyll-client-search-demo.png"
+       alt="jekyll-client-search demo">
+</picture>
+<!-- markdownlint-enable MD033 -->
+
 ## Table of contents
 
 - [Lightning start](#lightning-start)
@@ -269,7 +281,8 @@ Tag modes:
   `/search/`) with `?q=...` for full results on the search page
 - Arrow Up/Down → highlight items, Enter on highlighted → navigate
 - Click an item → navigate to that document's URL
-- Escape or click outside → close dropdown
+- Escape → close the popup and keep focus in the combobox; click outside
+  → close the dropdown
 - Index is lazy-loaded on first keystroke (no cost on pages where the
   visitor doesn't search)
 
@@ -290,24 +303,32 @@ and the search index includes that field (e.g. from jekyll-documents),
 an `<img>` icon is rendered before each result title. Set `icon_field:
 null` to disable.
 
-**CSS styling:** The dropdown emits no framework classes. Style with:
+**CSS styling:** The dropdown emits no framework classes. Its input uses
+the ARIA combobox pattern; the popup is a listbox whose options are plain
+text containers (not nested links or controls). Style with:
 
 ```css
 .client-search-dropdown { position: relative; }
-.client-search-dropdown ul[role="listbox"] {
+.client-search-dropdown [role="listbox"] {
   position: absolute; top: 100%; right: 0;
   min-width: 300px; z-index: 30;
   background: white; box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+  margin: 0; padding: 0;
+}
+.client-search-dropdown [role="listbox"] ul[role="presentation"] {
   list-style: none; margin: 0; padding: 0;
 }
-.client-search-dropdown li { padding: 0.5rem 1rem; }
-.client-search-dropdown li:hover,
-.client-search-dropdown li[aria-selected="true"] { background: #f5f5f5; }
-.client-search-dropdown li a { text-decoration: none; color: inherit; }
+.client-search-dropdown [role="option"] {
+  cursor: pointer; padding: 0.5rem 1rem;
+}
+.client-search-dropdown [role="option"]:hover,
+.client-search-dropdown [role="option"][aria-selected="true"] {
+  background: #f5f5f5;
+}
 
 /* Type-based styling via data attributes */
-.client-search-dropdown li[data-source="documents"] { border-left: 3px solid #48c774; }
-.client-search-dropdown li[data-file-type="pdf"]::before {
+.client-search-dropdown [role="option"][data-source="documents"] { border-left: 3px solid #48c774; }
+.client-search-dropdown [role="option"][data-file-type="pdf"]::before {
   content: "PDF"; background: #ff0000; color: white;
   padding: 0 0.3em; font-size: 0.7em; margin-right: 0.3em;
 }
@@ -450,15 +471,18 @@ client_search:
     output: search-relations.json
     minimum_similarity: 0.55
     max_items: null
+    index_model: null             # default: embedding.model
   embedding:
     enabled: false
-    model: embeddinggemma:300m
+    model: embeddinggemma-2:570m
     base_url: http://localhost:11434
     connect_timeout: 5
     read_timeout: 120
     fail_on_error: true
     query_embedder:
       type: transformers
+  semantic:
+    index_model: null             # default: embedding.model
 ```
 
 All options:
@@ -487,9 +511,13 @@ All options:
 | `related.semantic` | `true` | Include vector relations when document embeddings are available. |
 | `related.minimum_similarity` | `0.55` | Cosine cutoff for semantic relations; no fixed relation count. |
 | `related.max_items` | `null` | Optional safety cap after cutoff; `null` keeps every matching relation. |
+| `related.index_model` | `embedding.model` | Ollama model for related-article similarity. May differ from the index model since relations never reach the browser. |
+| `semantic.index_model` | `embedding.model` | Ollama model whose vectors go into the index; must match the browser query model. |
+| `semantic.document_prefix` | Model-specific | Document prefix for `semantic.index_model` (defaults to `embedding.document_prefix` when the models match). |
+| `semantic.query_prefix` | Model-specific | Query prefix for `semantic.index_model` (defaults to `embedding.query_prefix` when the models match). |
 | `embedding.enabled` | `false` | Generate embedding vectors at build time via Ollama. |
-| `embedding.model` | `embeddinggemma:300m` | Ollama model name for embedding generation. |
-| `embedding.base_url` | `http://localhost:11434` | Ollama server URL. |
+| `embedding.model` | `embeddinggemma-2:570m` | Ollama model name for embedding generation. |
+| `embedding.base_url` | `http://localhost:11434` | Ollama server URL. `localhost` is resolved once to the loopback literal (`127.0.0.1` or `[::1]`) that accepts a TCP connection, so IPv4-only and IPv6-only servers both work. |
 | `embedding.connect_timeout` | `5` | Ollama connection timeout in seconds. |
 | `embedding.read_timeout` | `120` | Ollama response timeout in seconds. |
 | `embedding.fail_on_error` | `true` | Fail the build when an embedding cannot be generated. |
@@ -610,7 +638,7 @@ Jekyll build time using a local [Ollama](https://ollama.ai/) server and the
 1. Install [Ollama](https://ollama.ai/) and pull an embedding model:
 
    ```bash
-   ollama pull embeddinggemma:300m
+   ollama pull embeddinggemma-2:570m
    ```
 
 2. Add `ollama-ruby` to your site's Gemfile (optional dependency):
@@ -626,10 +654,18 @@ Jekyll build time using a local [Ollama](https://ollama.ai/) server and the
      engine: semantic
      embedding:
        enabled: true
-       model: embeddinggemma:300m
        base_url: http://localhost:11434
    ```
 
+   With `query_embedder.type: transformers` (the default), the build
+   model needs a packaged browser ONNX mapping — `embeddinggemma` and
+   `embeddinggemma-2` models have one (see
+   [Browser query models](#browser-query-models)); any other
+   `embedding.model` requires an explicit `query_embedder.model` or
+   `query_embedder.type: ollama_api`. For build-time-only embeddings — a
+   lexical engine with `related` analysis — any Ollama model works
+   as-is.
+
 ### How it works
 
 - At build time, the `OllamaEmbeddingAdapter` sends each document's text
@@ -642,34 +678,175 @@ Jekyll build time using a local [Ollama](https://ollama.ai/) server and the
 - A content-hash cache (`.jekyll-client-search-cache.json` in the site
   source) tracks which documents have already been embedded. Unchanged
   documents reuse the cached embedding — only new or modified documents
-  are sent to the model.
+  are sent to the model. When the index and related models differ, the
+  related vectors are cached separately in
+  `.jekyll-client-search-related-cache.json`.
 - Cache entries include the provider, model, endpoint, and cache schema. A
   model or embedding configuration change automatically invalidates old
   vectors and re-embeds the documents.
-- Cache writes are atomic. The cache file is git-ignored and safe to delete
-  (it will be rebuilt on the next `jekyll build`).
+- Cache writes are atomic. The cache files are git-ignored and safe to
+  delete (they will be rebuilt on the next `jekyll build`).
 - By default, an embedding failure fails the build rather than silently
   producing an unusable semantic index. Set `embedding.fail_on_error: false`
   only when warning-only behavior is intentional.
 
 ### Choosing a model
 
-Any Ollama-compatible embedding model works. Common choices:
-
-| Model | Dimensions | Good for |
-| --- | --- | --- |
-| `embeddinggemma:300m` | 768 | Default, multilingual, good quality |
-| `nomic-embed-text` | 768 | Multilingual, good quality |
-| `bge-m3` | 1024 | Multilingual, high quality |
-| `all-minilm` | 384 | English, fast, lightweight |
+Any Ollama-compatible embedding model works. Hosted embedding APIs (OpenAI
+`text-embedding-3-small`, Gemini Embedding, the Voyage API) are not
+supported — the adapter only speaks Ollama's `/api/embed` protocol, and
+local embeddings keep the corpus on your machine. Open-weight models that
+ship GGUF builds (e.g. `voyage-4-nano`) can still be tested through a
+local Ollama server.
+
+Measured on a 152-document site (Apple Silicon, sequential `/api/embed`
+calls, GPU-resident models, `related.minimum_similarity: 0.55`):
+
+| Model | Dims | ~ms/doc | Full corpus | Quality* | Value† | ~Cost/yr‡ | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `embeddinggemma-2:570m` | 768 | ~246 | ~37 s | 111 | 0.50 | ~63 s | **Default** — best judged relatedness short of non-commercial jina; text vectors byte-identical to 270m; ONNX twin packaged (verify parity) |
+| `embeddinggemma-2:270m` | 768 | ~260 | ~40 s | 111 | 0.47 | ~67 s | Same text vectors as 570m; shares its ONNX twin (verify parity) |
+| `embeddinggemma:300m` | 768 | ~105 | ~16 s | 96 | 1.00 | ~27 s | Fast; verified transformers.js browser mapping |
+| `nomic-embed-text` | 768 | ~100 | ~15 s | 105 | **1.16** | ~25 s | Fast; best measured value |
+| `voyage-4-nano` | 1024 | ~115 | ~17 s | 107 | 1.03 | ~29 s | Open-weight (Apache 2.0); community GGUF at its 1024-dim base — official 2048 dim (post-hoc linear head) retested, judged equivalent (103) |
+| `bge-m3` | 1024 | ~305 | ~46 s | 107 | 0.38 | ~78 s | Multilingual; strong judged quality |
+| `jina-embeddings-v3` | 1024 | ~241 | ~37 s | **112** | 0.51 | ~62 s | CC-BY-NC-4.0 (non-commercial); community GGUF base weights — best judged picks + 88% corroboration; text-matching LoRA tested via llama.cpp: worse (98) |
+| `bge-large` | 1024 | ~115 | ~17 s | 106 | 1.01 | ~29 s | English-only yet still strong judged quality |
+| `mxbai-embed-large` | 1024 | ~340 | ~52 s | 107 | 0.35 | ~87 s | Strong judged quality |
+| `snowflake-arctic-embed2` | 1024 | ~505 | ~77 s | 81 | 0.17 | ~130 s | Conservative scores — few edges pass the 0.55 cutoff, weakest judged picks |
+| `all-minilm` | 384 | — | — | — | — | — | English only; not measured |
+| `qwen3-embedding:0.6b` | 1024 | ~350 | ~53 s | 90 | 0.28 | ~89 s | Strong multilingual results upstream |
+| `qwen3-embedding:4b` | 2560 | ~4000 | ~10 min | 87 | 0.02 | ~17 min | Poor value: ~38× the cost for below-average judged picks |
+| `qwen3-embedding:8b` | 4096 | ~10800 | ~27 min | 100 | 0.01 | ~46 min | Reference quality but ~103× the cost; build-time only |
+
+\* judged relevance: `gpt-oss:120b-cloud` scored every deduplicated
+related-article suggestion 0–2, blind to which model proposed it
+(`benchmarks/related_quality_judge.rb`); mean precision normalized to
+`qwen3-embedding:8b` = 100. Raw mean scores ranged 0.70–0.96 of 2.00.
+† quality ÷ ms/doc, normalized to `embeddinggemma:300m` = 1.00.
+‡ amortized embedding time per year assuming one cold re-embed plus weekly
+builds changing two posts — at this scale every model is affordable, so
+quality dominates the choice.
+
+The index cache amortizes cold-corpus cost — only new or changed documents
+re-embed — but every changed post pays the per-document latency at each
+build.
+
+Judged quality inverted the earlier agreement-based ranking: models with
+"hot" similarity distributions (`embeddinggemma-2`, `nomic-embed-text`,
+`voyage-4-nano`, `bge-m3`, `mxbai-embed-large`) were not producing noise —
+the judge rated their novel picks as the *most* relevant. Conservative
+models (snowflake, the small Qwen3s) scored worst on judged precision
+despite high agreement with `qwen3-embedding:8b`. Practical takeaway for
+this corpus size: `nomic-embed-text`, `voyage-4-nano`, and
+`embeddinggemma:300m` offer the best measured value; the default
+`embeddinggemma-2:570m` (and its identical-text-vector twin `:270m`)
+trades ~2.5× the per-document latency for the best judged relatedness of
+any license-free model; the large Qwen3 models do not pay for themselves
+below several thousand documents.
+
+"Build-time only" models are too large to run in the browser for
+`engine: semantic` — use them only with a lexical engine, where embeddings
+serve `related` analysis and never reach the visitor's browser, or with
+`query_embedder.type: ollama_api` where every visitor can reach the API.
 
 The model used at build time must match the query model's weights, vector
 space, dimensions, and preprocessing. Cross-runtime compatibility is verified
-for the default `embeddinggemma:300m` mapping. An `all-minilm` mapping is also
-provided, but sites should independently verify ranking when changing models.
-For any other Ollama model, set `embedding.query_embedder.model` to a
-compatible Transformers.js model explicitly or use `ollama_api` so both paths
-call the same Ollama model.
+for the `embeddinggemma:300m` → `onnx-community/embeddinggemma-300m-ONNX`
+mapping. The `embeddinggemma-2` family maps to
+`onnx-community/embeddinggemma-2-ONNX` — packaged but not yet parity-verified
+against the Ollama vectors, so confirm ranking on your own corpus. An
+`all-minilm` mapping is also provided. For any other Ollama model, set
+`embedding.query_embedder.model` to a compatible transformers.js model
+explicitly or use `ollama_api` so both paths call the same Ollama model.
+
+### Splitting the index and related models
+
+`search-relations.json` is computed entirely at build time, so related
+analysis can use a different vector space than the semantic index — the
+index vectors are the only ones the browser query embedder must match.
+Two optional keys control this; both default to `embedding.model`:
+
+```yaml
+client_search:
+  engine: semantic
+  embedding:
+    enabled: true
+    model: embeddinggemma-2:570m      # default build model
+  semantic:
+    index_model: embeddinggemma:300m  # vectors written into the index
+  related:
+    enabled: true
+    index_model: embeddinggemma-2:570m # vectors used for related analysis
+```
+
+When `semantic.index_model` and `related.index_model` resolve to the same
+model, documents are embedded once and the vector serves both outputs —
+there is no extra cost. When they differ, each document is embedded twice
+(once per model) and the related vectors are kept in a separate field,
+analyzed by `RelatedAnalyzer`, then stripped before `search-index.json`
+is written. Each model gets its own content-hash cache, so per-model
+vectors still amortize across builds. `semantic.document_prefix` /
+`semantic.query_prefix` can override the index model's prefixes; explicit
+`embedding.document_prefix` / `embedding.query_prefix` apply to
+`embedding.model`.
+
+`semantic.index_model` matters whenever vectors go into the index —
+including a lexical engine with `embedding.include_in_index: true`. It
+must always match the browser query model; `semantic.index_model:
+embeddinggemma:300m` is the safe choice for the verified transformers.js
+mapping.
+
+### Browser query models
+
+With `query_embedder.type: transformers`, the query model runs in the
+visitor's browser and must be a transformers.js-compatible ONNX build of
+the *index* model's weights. These Ollama models have a packaged mapping:
+
+| `embedding.model` / `semantic.index_model` | transformers.js model |
+| --- | --- |
+| `embeddinggemma:300m` | `onnx-community/embeddinggemma-300m-ONNX` (verified) |
+| `embeddinggemma-2`, `embeddinggemma-2:270m`, `embeddinggemma-2:570m` | `onnx-community/embeddinggemma-2-ONNX` (verify parity) |
+| `all-minilm` | `Xenova/all-MiniLM-L6-v2` |
+
+For anything else, set `embedding.query_embedder.model` to a compatible
+transformers.js model or use `query_embedder.type: ollama_api`. The full
+set of supported architectures and tasks is in the
+[transformers.js docs](https://huggingface.co/docs/transformers.js/index);
+compatible ONNX weights are tagged
+[`library:transformers.js` on the Hub](https://huggingface.co/models?library=transformers.js).
+
+Document/query prefixes are applied automatically for `embeddinggemma`,
+`embeddinggemma-2`, `nomic-embed-text`, and `voyage-4-nano`; other models
+get no prefix.
+Qwen3 embedding models take no document prefix; for semantic search the
+instruct-format query prefix must be set via `embedding.query_prefix`.
+Cosine similarity distributions differ substantially per model — some run
+"narrow" (snowflake: almost nothing passes 0.55) and some run "hot"
+(nomic, embeddinggemma-2: nearly everything does) — so retune
+`related.minimum_similarity` and the semantic threshold when switching
+rather than comparing at the default.
+
+To benchmark your own site and corpus:
+
+```bash
+cd jekyll-client-search
+bundle install
+OLLAMA_BASE_URL=http://127.0.0.1:11434 \
+  EMBEDDING_MODELS="embeddinggemma:300m,nomic-embed-text,bge-m3" \
+  bundle exec ruby benchmarks/related_model_benchmark.rb /path/to/site
+```
+
+The script times `OllamaEmbeddingAdapter.embed` per document and runs the
+real `RelatedAnalyzer`, then diffs each model's related lists against the
+baseline (`BASELINE_MODEL` env, default `embeddinggemma-2:570m`). Raw vectors
+are cached under `benchmarks/.related-embeddings/` so re-runs are cheap.
+
+A `localhost` `base_url` is resolved automatically to the loopback literal
+that accepts a TCP connection (`127.0.0.1` or `[::1]`), because the HTTP
+client does not fall back across address families and Ollama often listens
+on IPv4 loopback only. If `ollama embed` calls still fail with a socket
+error, set `base_url: http://127.0.0.1:11434` explicitly.
 
 ## Related articles reference
 
@@ -977,7 +1154,7 @@ client_search:
   engine: semantic
   embedding:
     enabled: true
-    model: embeddinggemma:300m
+    model: embeddinggemma-2:570m
     query_embedder:
       type: ollama_api
       api_url: https://embeddings.example.com/api/embed