jekyll-client-search 0.3.4 → 0.4.0

data/README.developer.md

@@ -8,13 +8,12 @@ See [README.md](README.md) for user-facing configuration and usage docs.
 ## Quick start
 
 ```bash
-rbenv install 3.4.10       # if not already installed
-rbenv local 3.4.10
+rbenv install            # reads .ruby-version
 bundle install
 npm ci
-bundle exec rspec                          # Ruby tests (248 examples; 7 Ollama pending)
+bundle exec rspec                          # Ruby tests
 OLLAMA_INTEGRATION=1 bundle exec rspec     # all tests including Ollama integration
-npm test                                   # JavaScript tests (134 tests)
+npm test                                   # JavaScript tests
 ```
 
 Both test suites pass with only the committed Wikipedia fixtures and the
@@ -29,16 +28,22 @@ The project uses a focused quality stack: RuboCop (style), bundler-audit
 maintenance burden of additional code-smell tools on a small focused gem.
 
 External automated code review services:
+
 - [CodeQL](https://codeql.github.com) — GitHub native security scanning
   (Ruby + JavaScript), runs on every push.
 - [Semgrep](https://semgrep.dev) — CI security scan using the Semgrep Pro
-  engine with the organization's full policy (2,900+ rules). Runs as a CI
+  engine with the organization's full policy ruleset. Runs as a CI
   job (`semgrep ci`) and in the pre-commit hook (custom rules only). See
   `.semgrep.yml` for local configuration and usage instructions.
 - [CodeFactor](https://www.codefactor.io/repository/github/gundestrup/jekyll-client-search) —
   automated code review (RuboCop, Brakeman, bundler-audit, duplication).
 - [Dependabot](https://docs.github.com/en/code-security/dependabot) — weekly
   GitHub Actions version updates (SHA-pinned actions updated automatically).
+- [Codecov](https://codecov.io/gh/gundestrup/jekyll-client-search) — coverage
+  reporting. CI uploads Cobertura XML generated by `simplecov-cobertura` from
+  the Ruby 3.4 / Node 24 matrix job; status check thresholds live in
+  `codecov.yml`. Uploads authenticate via OIDC (`id-token: write`), with the
+  `CODECOV_TOKEN` secret as a fallback.
 
 ### Semgrep usage
 
@@ -85,8 +90,9 @@ comments. Dependabot updates the SHAs and version comments automatically.
 
 ### Git hooks
 
-Git hooks are not committed to the repository. Install them locally after
-cloning:
+Hooks are tracked in `bin/hooks/`; `bin/install-hooks.sh` points git at
+them via `core.hooksPath` (no copying — tracked hooks can't drift from
+installed ones). Run once after cloning:
 
 ```bash
 bin/install-hooks.sh
@@ -106,11 +112,11 @@ 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.2/3.3/3.4 and Node 22/24:
+request across Ruby 3.3/3.4 and Node 22/24:
 
 - `bundle exec rake ci` (rspec, rubocop, syntax checks, npm test, gem build)
 - `bundle exec bundle-audit check --update` (Ruby dependency security)
-- `npm audit --audit-level=high` (JavaScript dependency security)
+- `npm run audit` (JavaScript dependency security gate — see `scripts/npm-audit.mjs`)
 - `npm outdated` (non-blocking — warns about outdated npm packages)
 - `semgrep ci` (security scan with custom rules from `.semgrep.yml`)
 
@@ -163,7 +169,7 @@ test files are `spec/related_analyzer_spec.rb`, `spec/related_tag_spec.rb`,
 ## What is committed
 
 | Artifact | Committed? | Why |
-|---|---|---|
+| --- | --- | --- |
 | Wikipedia fixture posts (40) | Yes | CC BY-SA 3.0 allows redistribution with attribution |
 | arXiv fixture posts (40) | **No** | Mixed/restrictive licenses — see below |
 | Baseline search-index JSON | Yes | Generated test artifact (indexed data, not raw text) |
@@ -193,6 +199,7 @@ ruby spec/fixtures/download_arxiv.rb
 ```
 
 This script:
+
 - Fetches 40 recent arXiv papers from 5 CS/AI subfields
 - Downloads each PDF and extracts text with `pdftotext`
 - Records the actual per-paper license in each post's frontmatter
@@ -230,9 +237,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
    ```
 
@@ -243,7 +251,18 @@ 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
 - Verify embedding dimensions and validity
 - Test semantic search quality with concept queries
@@ -272,7 +291,7 @@ ruby spec/fixtures/generate_semantic_gold.rb
 ## Test categories
 
 | Tag | Description | Requires arXiv? | Requires Ollama? |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `:unit` | Ruby unit tests | No | No |
 | `:system` | Ruby system tests (build fixture site) | Partially | No |
 | `:integration` | Ruby integration tests | No | No |
@@ -298,7 +317,9 @@ always return an asset).
 
 The coverage report is generated at `coverage/index.html` after each RSpec
 run. Raw data is in `coverage/.resultset.json` (SimpleCov 1.0+ format with
-`lines` and `branches` keys per file).
+`lines` and `branches` keys per file). In CI (`ENV["CI"]`), SimpleCov emits
+Cobertura XML at `coverage/coverage.xml` instead, which is uploaded to
+Codecov by the `codecov/codecov-action` step in `ci.yml`.
 
 To check remaining uncovered lines and branches after a run:
 
@@ -440,7 +461,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.
@@ -492,7 +514,7 @@ The [`release.yml`](.github/workflows/release.yml) workflow, triggered by
 pushing a `v*` tag:
 
 1. Checks out the repository at the release tag (`persist-credentials: false`).
-2. Sets up Ruby 3.4.10.
+2. Sets up Ruby from `.ruby-version`.
 3. Verifies the tag name matches `v<gem version>` (fails on mismatch).
 4. Verifies `CHANGELOG.md` has a `## X.Y.Z` entry for the version
    (`rake version:check_changelog` — fails if missing).

data/README.md

@@ -1,12 +1,16 @@
 # 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)
+
+
 ![jekyll-client-search logo](docs/assets/icon-256.png)
 
 [![CI](https://github.com/gundestrup/jekyll-client-search/actions/workflows/ci.yml/badge.svg)](https://github.com/gundestrup/jekyll-client-search/actions/workflows/ci.yml)
-[![Ruby](https://img.shields.io/badge/ruby-%E2%89%A5%203.2-red.svg)](https://www.ruby-lang.org/)
+[![Gem Version](https://img.shields.io/gem/v/jekyll-client-search)](https://rubygems.org/gems/jekyll-client-search)
+[![Ruby](https://img.shields.io/badge/ruby-%E2%89%A5%203.3-red.svg)](https://www.ruby-lang.org/)
 [![Jekyll](https://img.shields.io/badge/jekyll-4.x-blue.svg)](https://jekyllrb.com/)
 [![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)
-[![DeepWiki](https://img.shields.io/badge/DeepWiki-docs-7B68EE.svg)](https://deepwiki.com/gundestrup/jekyll-client-search)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gundestrup/jekyll-client-search)
 [![Coverage](https://img.shields.io/badge/coverage-100%25%20branches-brightgreen.svg)](#testing-strategy)
 [![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)
@@ -445,15 +449,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:
@@ -482,9 +489,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. |
@@ -603,23 +614,36 @@ Jekyll build time using a local [Ollama](https://ollama.ai/) server and the
 ### Setup
 
 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):
+
    ```ruby
    gem "ollama-ruby", "~> 1.23"
    ```
+
 3. Enable embeddings in `_config.yml`:
+
    ```yaml
    client_search:
      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
@@ -632,34 +656,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
 
@@ -967,7 +1132,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
@@ -1012,18 +1177,18 @@ Recommended policy:
 
 ## License
 
+Copyright (C) 2026 Svend Gundestrup.
+
 This project is licensed under the GNU Affero General Public License v3.0 or
 later (`AGPL-3.0-or-later`). See [LICENSE](LICENSE).
 
 ## Development
 
-Development uses Ruby 3.4.10 through rbenv, while the gem supports Ruby 3.2
-and newer. The development version is stored in `.ruby-version`, and CI tests
-Ruby 3.2, 3.3, and 3.4.
+Development uses the Ruby version pinned in `.ruby-version` (via rbenv),
+while the gem supports Ruby 3.3 and newer. CI tests Ruby 3.3 and 3.4.
 
 ```bash
-rbenv install 3.4.10       # if not already installed
-rbenv local 3.4.10
+rbenv install            # reads .ruby-version
 bundle install
 npm ci
 bundle exec rake ci
@@ -1153,7 +1318,7 @@ Additional automated code quality and security services:
 - [CodeQL](https://codeql.github.com) — GitHub native code scanning for
   security vulnerabilities (Ruby + JavaScript).
 - [Semgrep](https://semgrep.dev) — CI security scan using the Semgrep Pro
-  engine with the organization's full policy (2,900+ rules). Custom ReDoS
+  engine with the organization's full policy ruleset. Custom ReDoS
   detection rules are defined in `.semgrep.yml`. Findings are triaged on the
   [Semgrep AppSec Platform](https://semgrep.dev) dashboard. False positives
   and acceptable risks are annotated inline with `# nosemgrep: rule.id`.

data/assets/includes/related-articles.html

@@ -15,8 +15,10 @@
 #   scripts: true (default) to load runtime scripts, false to skip
 ---
 
-{% assign related_sort = include.sort | default: "relevance" %}
-{% assign include_scripts = include.scripts | default: true %}
+{% comment %}Bracket access: bare include.sort falls back to Hash#sort on
+non-empty param hashes, so the default would silently stop applying.{% endcomment %}
+{% assign related_sort = include["sort"] | default: "relevance" %}
+{% assign include_scripts = include["scripts"] | default: true %}
 {% if include_scripts == false or include_scripts == "false" %}
   {% assign include_scripts = false %}
 {% endif %}

data/assets/query-embedders/ollama-api.js

@@ -2,7 +2,7 @@
     "use strict";
 
     var config = window.ClientSearchEmbedderConfig || {};
-    var model = config.model || config.buildModel || "embeddinggemma:300m";
+    var model = config.model || config.buildModel || "embeddinggemma-2:570m";
     var apiUrl = config.apiUrl || "http://localhost:11434/api/embed";
     var activeController = null;
 

data/lib/jekyll/client_search/configuration.rb

@@ -27,7 +27,7 @@ module Jekyll
         "icon_field" => "icon_url",
         "embedding" => {
           "enabled" => false,
-          "model" => "embeddinggemma:300m",
+          "model" => "embeddinggemma-2:570m",
           "base_url" => "http://localhost:11434",
           "connect_timeout" => 5,
           "read_timeout" => 120,
@@ -41,9 +41,7 @@ module Jekyll
       def initialize(site)
         configured = normalize_configured(site.config["client_search"])
         @values = DEFAULTS.merge(configured)
-        @live_search = LiveSearchConfiguration.new(configured["live_search"] || {}, engine: engine)
-        @related = RelatedConfiguration.new(configured["related"] || {})
-        @dropdown = DropdownConfiguration.new(configured["dropdown"] || {})
+        build_sub_configurations(configured)
         merge_embedding_config(configured["embedding"])
         validate_engine!
         return unless embedding_enabled?
@@ -54,6 +52,13 @@ module Jekyll
 
       private
 
+      def build_sub_configurations(configured)
+        @live_search = LiveSearchConfiguration.new(configured["live_search"] || {}, engine: engine)
+        @related = RelatedConfiguration.new(configured["related"] || {})
+        @semantic = SemanticConfiguration.new(configured["semantic"] || {})
+        @dropdown = DropdownConfiguration.new(configured["dropdown"] || {})
+      end
+
       def normalize_configured(value)
         return { "enabled" => false } if value == false
         return value if value.is_a?(Hash)
@@ -70,13 +75,9 @@ module Jekyll
                 "client_search embedding configuration must be a mapping"
         end
         @values["embedding"] = DEFAULTS.fetch("embedding").merge(embedding)
-        merge_query_embedder_config(embedding["query_embedder"])
-      end
-
-      def merge_query_embedder_config(configured_query_embedder)
         @query_embedder = QueryEmbedderConfiguration.new(
-          configured_query_embedder || {},
-          build_model: embedding_model,
+          embedding["query_embedder"] || {},
+          build_model: embedding_index_model,
           build_base_url: embedding_base_url,
           query_prefix: embedding_query_prefix
         )

data/lib/jekyll/client_search/configuration_accessors.rb

@@ -20,6 +20,19 @@ module Jekyll
         @related
       end
 
+      # The Ollama model whose vectors are written into the search index and
+      # must match the browser query embedder's vector space. Defaults to
+      # embedding.model; override with semantic.index_model.
+      def embedding_index_model
+        @semantic.index_model || embedding_model
+      end
+
+      # The Ollama model used for related-article similarity analysis.
+      # Defaults to embedding.model; override with related.index_model.
+      def embedding_related_model
+        @related.index_model || embedding_model
+      end
+
       def query_embedder_type
         @query_embedder.type
       end