stylegallery 0.1.14 → 0.1.16

package/log.md

@@ -2,6 +2,24 @@
 
 ## 2026-10-19
 
+Understood as: release `stylegallery@0.1.16`, which ships hybrid search from PR #68: BM25F fused with an English embedding model so everyday wording finds documents that use different words.
+
+- `stylegallery search` and the MCP `search` tool take `--mode hybrid|lexical` (`mode`), default `hybrid`: weighted reciprocal rank fusion (k 60, semantic weight 0.5) of BM25F and bge-small-en-v1.5 (quantized ONNX, 34 MB). The result reports the `mode` that ran and a `mode_reason` on fallback.
+- The model is not packaged. The first hybrid search downloads it from a pinned revision into `~/.cache/stylegallery/models/` and checks its SHA-256; it runs on `onnxruntime-web`, an optional dependency. Offline (`STYLEGALLERY_OFFLINE=1`), without the dependency, or for Korean without `query_en`, search warns once and ranks with BM25F alone.
+- Document vectors ship precomputed in `consumer-reference/agent-native/v2/search-embeddings.json`; `generate-search-embeddings.mjs --check --vectors` runs in the Search evaluation workflow.
+- Search evaluation adds 20 vocabulary-mismatch questions (111 total). Hit@5 lexical to hybrid: overall 0.892 to 0.937, held-out 0.867 to 0.933, mismatch 0.50 to 0.70; must-pass 35/35 in both modes.
+
+Consumer reference: not_applicable
+Consumer reference reason: This release changes search ranking tooling and selects no consumer-reference profile or record.
+
+Understood as: release `stylegallery@0.1.15`, which ships OmO support for `stylegallery setup` from PR #66.
+
+- `stylegallery setup` adds `--agent omo`, detected by `~/.omo` or `omo` on PATH and included by default and in `all`. It registers `mcpServers.stylegallery` (`npx -y --package stylegallery stylegallery-mcp`) in `<agentDir>/mcp.json`, where agentDir is `$OMO_CODING_AGENT_DIR` or `~/.omo/agent`, with the same backup, `--force`, and idempotence rules as Claude Code and Codex. An identical hand-made entry is reported unchanged.
+- The skill copy in `~/.agents/skills/stylegallery-search/` is shared by Codex and OmO: it is written once, and the second agent is reported with `shared_with`. `--uninstall` keeps the shared skill (`kept`) while another detected agent that uses it is not part of the same uninstall run.
+
+Consumer reference: not_applicable
+Consumer reference reason: This release adds agent setup tooling and selects no consumer-reference profile or record.
+
 Understood as: release `stylegallery@0.1.14`, which ships `stylegallery setup` from PR #64 so an installed package can connect Claude Code and Codex in one command.
 
 - `stylegallery setup` copies `skills/stylegallery-search/SKILL.md` to `~/.claude/skills/stylegallery-search/` and `~/.agents/skills/stylegallery-search/` and registers `npx -y --package stylegallery stylegallery-mcp` as user-scope `mcpServers.stylegallery` in `~/.claude.json` and `[mcp_servers.stylegallery]` in `~/.codex/config.toml`. Options: `--dry-run`, `--agent claude|codex|all`, `--only skill|mcp`, `--uninstall`, `--force`. Reruns change nothing, modified config files are backed up as `<file>.bak-stylegallery-<timestamp>`, other settings are preserved, and a different same-name entry is left alone without `--force`. Sources: https://code.claude.com/docs/en/mcp, https://code.claude.com/docs/en/skills, https://developers.openai.com/codex/mcp, https://developers.openai.com/codex/skills, read 2026-10-19.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylegallery",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "A governed gallery of portable interface knowledge with knowledge CLIs, website compilation, and MCP servers.",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,7 @@
     "consumer-reference/agent-native/v2/schema/admission-policy.schema.json",
     "consumer-reference/agent-native/v2/schema/material-manifest.schema.json",
     "consumer-reference/agent-native/v2/schema/material-record.schema.json",
+    "consumer-reference/agent-native/v2/search-embeddings.json",
     "consumer-reference/contract.md",
     "consumer-reference/index.md",
     "design-engineering/component-contract.md",
@@ -265,6 +266,7 @@
     "scripts/agent-native/v2/material-queries.mjs",
     "scripts/agent-native/v2/material-registry.mjs",
     "scripts/agent-native/v2/material-search-v3.mjs",
+    "scripts/agent-native/v2/search-embeddings.mjs",
     "scripts/compiler/README.md",
     "scripts/compiler/cli.mjs",
     "scripts/compiler/mcp.mjs",
@@ -339,7 +341,8 @@
     "stylegallery": "node scripts/sg-entry.mjs",
     "test:search": "node --test scripts/test-stylegallery-search.mjs",
     "test:setup": "node --test scripts/test-stylegallery-setup.mjs",
-    "eval:search": "node scripts/search-eval.mjs --gate"
+    "eval:search": "node scripts/agent-native/v2/generate-search-embeddings.mjs --check && node scripts/search-eval.mjs --gate",
+    "generate:search-embeddings": "node scripts/agent-native/v2/generate-search-embeddings.mjs"
   },
   "devDependencies": {
     "@playwright/test": "1.61.0",
@@ -356,5 +359,8 @@
   },
   "overrides": {
     "brace-expansion": "5.0.9"
+  },
+  "optionalDependencies": {
+    "onnxruntime-web": "1.30.0"
   }
 }

package/scripts/agent-native/v2/material-search-v3.mjs

@@ -1,7 +1,9 @@
-// Search v3: readable IDs, BM25F field ranking, section-aware read.
-// Offline and deterministic: no model, no network, stable tie-breaks.
+// Search v3: readable IDs, BM25F field ranking fused with embedding similarity
+// (hybrid mode), section-aware read. Deterministic with stable tie-breaks; when
+// the embedding model is unavailable, search falls back to BM25F alone.
 import { deepFreeze } from "../canonical-json.mjs";
 import { MaterialQueryError, materialCorpus, tokenizeMaterialText } from "./material-queries.mjs";
+import { EMBEDDING_MODEL, documentTextHash, loadEmbedder, loadStoredEmbeddings } from "./search-embeddings.mjs";
 
 export const SEARCH_SCHEMA_VERSION = "3.0";
 export const SEARCH_DEFAULT_LIMIT = 5;
@@ -24,6 +26,9 @@ export const SEARCH_FIELDS = deepFreeze({
   ko: { w: 1.5, b: 0.3 },
 });
 export const SEARCH_K1 = 1.2;
+export const SEARCH_MODES = Object.freeze(["hybrid", "lexical"]);
+// Weighted reciprocal rank fusion of the BM25F and embedding rankings.
+export const SEARCH_FUSION = deepFreeze({ method: "RRF", k: 60, lexical_weight: 1, semantic_weight: 0.5, depth: 50 });
 
 const STOPWORDS = new Set(("a an and are as at be by can do does for from how i in into is it its me my of on or should "
   + "so that the this to use using what when where which with you your").split(" "));
@@ -275,7 +280,7 @@ function bestSnippet(document, terms) {
 
 function validateSearchInput(input) {
   if (!input || typeof input !== "object" || Array.isArray(input)) fail("material_input_invalid", "input must be an object");
-  const allowed = new Set(["query", "query_en", "limit", "paths_only", "response_format"]);
+  const allowed = new Set(["query", "query_en", "limit", "paths_only", "response_format", "mode"]);
   if (Object.keys(input).some((key) => !allowed.has(key))) fail("material_input_unknown", "input contains an unsupported field");
   for (const key of ["query", "query_en"]) {
     const value = input[key];
@@ -289,12 +294,39 @@ function validateSearchInput(input) {
   if (input.paths_only !== undefined && typeof input.paths_only !== "boolean") fail("material_paths_only_invalid", "paths_only must be a boolean");
   const format = input.response_format ?? "concise";
   if (!["concise", "detailed"].includes(format)) fail("search_response_format_invalid", "response_format must be concise or detailed");
-  return { query: input.query, queryEn: input.query_en, limit, pathsOnly: input.paths_only === true, detailed: format === "detailed" };
+  const mode = input.mode ?? "hybrid";
+  if (!SEARCH_MODES.includes(mode)) fail("search_mode_invalid", "mode must be hybrid or lexical");
+  return { query: input.query, queryEn: input.query_en, limit, pathsOnly: input.paths_only === true, detailed: format === "detailed", mode };
 }
 
-/** Rank documents for a query. Pure over an index; exported for evaluation. */
-export function rankSearchIndex(index, query, queryEn) {
-  const terms = queryTerms(query, queryEn);
+/** The text embedded for a query: the English rewrite when given, else the query unless it is Korean. */
+export function semanticQueryText(query, queryEn) {
+  if (queryEn) return queryEn;
+  return /[\p{Script=Hangul}]/u.test(query) ? null : query;
+}
+
+/**
+ * Prepare the semantic half of a hybrid search. Resolves to { mode, semantic, reason }:
+ * mode "lexical" with a reason whenever hybrid was requested but cannot run.
+ */
+export async function prepareSemantic(index, query, queryEn, requestedMode = "hybrid", options = {}) {
+  if (requestedMode === "lexical") return { mode: "lexical", semantic: null };
+  const text = semanticQueryText(query, queryEn);
+  if (text === null) return { mode: "lexical", semantic: null, reason: "Korean query without query_en; the embedding model reads English only" };
+  const stored = loadStoredEmbeddings(options.embeddingsPath);
+  if (!stored) return { mode: "lexical", semantic: null, reason: "precomputed document embeddings are missing" };
+  const embedder = await loadEmbedder(options);
+  if (embedder.error) return { mode: "lexical", semantic: null, reason: `embedding model unavailable: ${embedder.error}` };
+  const vectors = new Map();
+  for (const document of index.documents) {
+    const entry = stored.get(document.record.repository_path);
+    // A document edited after the vectors were built ranks on BM25F alone.
+    if (entry && entry.textHash === documentTextHash(document)) vectors.set(document.id, entry.vector);
+  }
+  return { mode: "hybrid", semantic: { queryVector: await embedder.embed(`${EMBEDDING_MODEL.query_prefix}${text}`), vectors } };
+}
+
+function lexicalRanking(index, terms) {
   const idf = inverseDocumentFrequency(index, terms);
   const ranked = [];
   for (const document of index.documents) {
@@ -302,23 +334,64 @@ export function rankSearchIndex(index, query, queryEn) {
     if (score > 0) ranked.push({ document, score, matched });
   }
   ranked.sort((left, right) => right.score - left.score || compare(left.document.id, right.document.id));
-  return { terms, ranked };
+  return ranked;
+}
+
+function fuse(index, lexical, semantic) {
+  const { k, lexical_weight: lexicalWeight, semantic_weight: semanticWeight, depth } = SEARCH_FUSION;
+  const similarity = [];
+  for (const document of index.documents) {
+    const vector = semantic.vectors.get(document.id);
+    if (!vector) continue;
+    let dot = 0;
+    for (let position = 0; position < vector.length; position += 1) dot += vector[position] * semantic.queryVector[position];
+    similarity.push({ document, similarity: Math.round(dot * 1e6) / 1e6 });
+  }
+  similarity.sort((left, right) => right.similarity - left.similarity || compare(left.document.id, right.document.id));
+  const fused = new Map();
+  lexical.slice(0, depth).forEach(({ document, score, matched }, rank) => {
+    fused.set(document.id, { document, lexical_score: score, matched: new Set(matched), score: lexicalWeight / (k + rank + 1) });
+  });
+  similarity.slice(0, depth).forEach(({ document, similarity: value }, rank) => {
+    const entry = fused.get(document.id) ?? { document, matched: new Set(), score: 0 };
+    entry.matched.add("semantic");
+    entry.similarity = value;
+    entry.score += semanticWeight / (k + rank + 1);
+    fused.set(document.id, entry);
+  });
+  return [...fused.values()].map((entry) => ({ ...entry, score: Math.round(entry.score * 1e9) / 1e9 }))
+    .sort((left, right) => right.score - left.score || compare(left.document.id, right.document.id));
+}
+
+/** Rank documents for a query. Pure over an index and an optional semantic input; exported for evaluation. */
+export function rankSearchIndex(index, query, queryEn, semantic = null) {
+  const terms = queryTerms(query, queryEn);
+  const lexical = lexicalRanking(index, terms);
+  return { terms, ranked: semantic ? fuse(index, lexical, semantic) : lexical };
 }
 
 function readCommand(document, section) {
   return `stylegallery read ${document.id}${section && section.level > 1 ? ` --section ${section.slug}` : ""}`;
 }
 
-export function searchIndex(index, input) {
+/**
+ * Search a built index. `prepared` is the result of prepareSemantic; without it
+ * the search is lexical. Synchronous and deterministic for a given input.
+ */
+export function searchIndex(index, input, prepared = null) {
   const normalized = validateSearchInput(input);
-  const { terms, ranked } = rankSearchIndex(index, normalized.query, normalized.queryEn);
+  const semantic = normalized.mode === "hybrid" ? prepared?.semantic ?? null : null;
+  const mode = semantic ? "hybrid" : "lexical";
+  const reason = normalized.mode === "hybrid" && !semantic ? prepared?.reason ?? "embedding model not loaded" : null;
+  const { terms, ranked } = rankSearchIndex(index, normalized.query, normalized.queryEn, semantic);
   const selected = ranked.slice(0, normalized.limit);
   const query = { text: normalized.query, ...(normalized.queryEn ? { query_en: normalized.queryEn } : {}) };
   const page = { returned: selected.length, total: ranked.length, next_cursor: null };
+  const modeFields = { mode, ...(reason ? { mode_reason: reason } : {}) };
   if (normalized.pathsOnly) {
-    return deepFreeze({ schema_version: SEARCH_SCHEMA_VERSION, query, snapshot: index.manifestVersionId, paths: selected.map(({ document }) => document.record.repository_path), page });
+    return deepFreeze({ schema_version: SEARCH_SCHEMA_VERSION, query, ...modeFields, snapshot: index.manifestVersionId, paths: selected.map(({ document }) => document.record.repository_path), page });
   }
-  const results = selected.map(({ document, score, matched }) => {
+  const results = selected.map(({ document, score, matched, lexical_score: lexicalScore, similarity }) => {
     const best = bestSnippet(document, terms);
     return {
       id: document.id,
@@ -329,11 +402,14 @@ export function searchIndex(index, input) {
       matched_fields: [...matched].sort(),
       snippets: best ? [best.snippet] : [],
       next: { read: readCommand(document, best?.section) },
-      ...(normalized.detailed ? { score, source_ref: document.record.stable_ref, version_id: document.record.version_id, material_ref: document.identity.stable_ref } : {}),
+      ...(normalized.detailed ? { score, ...(semantic ? { lexical_score: lexicalScore ?? 0, ...(similarity !== undefined ? { similarity } : {}) } : {}), source_ref: document.record.stable_ref, version_id: document.record.version_id, material_ref: document.identity.stable_ref } : {}),
     };
   });
-  const envelope = { schema_version: SEARCH_SCHEMA_VERSION, query, snapshot: index.manifestVersionId, results, page, coverage: { truncated: false } };
-  if (normalized.detailed) envelope.ranking = { method: "BM25F", k1: SEARCH_K1, fields: SEARCH_FIELDS, terms };
+  const envelope = { schema_version: SEARCH_SCHEMA_VERSION, query, ...modeFields, snapshot: index.manifestVersionId, results, page, coverage: { truncated: false } };
+  if (normalized.detailed) {
+    envelope.ranking = { method: "BM25F", k1: SEARCH_K1, fields: SEARCH_FIELDS, terms };
+    if (semantic) envelope.ranking.fusion = { ...SEARCH_FUSION, model: EMBEDDING_MODEL.source, revision: EMBEDDING_MODEL.revision };
+  }
   while (Buffer.byteLength(JSON.stringify(envelope), "utf8") > SEARCH_BUDGET_BYTES && envelope.results.length > 1) {
     envelope.results.pop();
     envelope.page.returned = envelope.results.length;
@@ -394,13 +470,19 @@ export function loadSearchIndex(options) {
 
 const PUBLIC_CODES = new Set(["material_input_invalid", "material_input_unknown", "material_query_invalid", "material_query_oversized",
   "material_query_empty", "search_limit_invalid", "material_paths_only_invalid", "search_response_format_invalid", "read_reference_required",
-  "read_reference_not_found", "read_section_invalid", "read_outline_invalid", "read_mode_conflict", "read_section_not_found", "search_id_collision"]);
+  "read_reference_not_found", "read_section_invalid", "read_outline_invalid", "read_mode_conflict", "read_section_not_found", "search_id_collision",
+  "search_mode_invalid"]);
 
 /** Run `search` or `read` and wrap it in the ok/failures envelope shared by CLI and MCP. */
-export function invokeSearchOperation(operation, input, options) {
+export async function invokeSearchOperation(operation, input, options) {
   try {
     const index = loadSearchIndex(options);
-    const result = operation === "search" ? searchIndex(index, input) : readIndex(index, input);
+    let result;
+    if (operation === "search") {
+      validateSearchInput(input);
+      const prepared = await prepareSemantic(index, input.query, input.query_en, input.mode ?? "hybrid", options?.semantic);
+      result = searchIndex(index, input, prepared);
+    } else result = readIndex(index, input);
     return deepFreeze({ ok: true, operation, result });
   } catch (error) {
     const known = typeof error?.code === "string" && (PUBLIC_CODES.has(error.code) || error.code.startsWith("material_"));

package/scripts/agent-native/v2/search-embeddings.mjs

@@ -0,0 +1,224 @@
+// Semantic half of hybrid search: a small English embedding model run with
+// onnxruntime-web (WebAssembly, an optional dependency). The model is never
+// packaged: it is downloaded once into a cache directory and checked against
+// pinned SHA-256 hashes. Document vectors are precomputed at build time into
+// search-embeddings.json. Any failure leaves search on BM25F alone.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+export const EMBEDDINGS_PATH = path.join(repositoryRoot, "consumer-reference/agent-native/v2/search-embeddings.json");
+
+export const EMBEDDING_MODEL = Object.freeze({
+  id: "bge-small-en-v1.5-q8",
+  source: "Xenova/bge-small-en-v1.5",
+  revision: "ea104dacec62c0de699686887e3f920caeb4f3e3",
+  dims: 384,
+  pooling: "cls",
+  query_prefix: "Represent this sentence for searching relevant passages: ",
+  max_tokens: 512,
+  files: Object.freeze({
+    "model_quantized.onnx": Object.freeze({ remote: "onnx/model_quantized.onnx", sha256: "6c9c6101a956d62dfb5e7190c538226c0c5bb9cb27b651234b6df063ee7dbfe4", bytes: 34014426 }),
+    "tokenizer.json": Object.freeze({ remote: "tokenizer.json", sha256: "d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66", bytes: 711396 }),
+  }),
+});
+export const DOCUMENT_TEXT_CHARS = 1500;
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+
+export function cacheDirectory(env = process.env) {
+  if (env.STYLEGALLERY_CACHE_DIR) return env.STYLEGALLERY_CACHE_DIR;
+  const base = env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  return path.join(base, "stylegallery");
+}
+
+export function modelDirectory(env = process.env) {
+  return path.join(cacheDirectory(env), "models", EMBEDDING_MODEL.id);
+}
+
+const sha256 = (buffer) => crypto.createHash("sha256").update(buffer).digest("hex");
+
+/** The text a document is embedded from: title, description, headings, then prose without code. */
+export function documentEmbeddingText(document) {
+  const body = document.text.replace(/^---\n[\s\S]*?\n---\n/, "").replace(/```[\s\S]*?```/g, " ")
+    .replace(/[#*`|>-]+/g, " ").replace(/\s+/g, " ").trim();
+  return [document.title, document.description, document.sections.map((section) => section.title).join("; "), body]
+    .filter(Boolean).join(". ").slice(0, DOCUMENT_TEXT_CHARS);
+}
+
+export function documentTextHash(document) {
+  return sha256(Buffer.from(documentEmbeddingText(document), "utf8"));
+}
+
+// ---- BERT uncased WordPiece tokenizer (matches the model's tokenizer.json) ----
+
+function isPunctuation(code, char) {
+  return (code >= 33 && code <= 47) || (code >= 58 && code <= 64) || (code >= 91 && code <= 96) || (code >= 123 && code <= 126) || /\p{P}/u.test(char);
+}
+
+function isCjk(code) {
+  return (code >= 0x4e00 && code <= 0x9fff) || (code >= 0x3400 && code <= 0x4dbf) || (code >= 0x20000 && code <= 0x2a6df)
+    || (code >= 0x2a700 && code <= 0x2b73f) || (code >= 0x2b740 && code <= 0x2b81f) || (code >= 0x2b820 && code <= 0x2ceaf)
+    || (code >= 0xf900 && code <= 0xfaff) || (code >= 0x2f800 && code <= 0x2fa1f);
+}
+
+function basicTokens(text) {
+  let cleaned = "";
+  for (const char of text) {
+    const code = char.codePointAt(0);
+    if (code === 0 || code === 0xfffd || (/\p{Cc}|\p{Cf}/u.test(char) && !/[\t\n\r]/.test(char))) continue;
+    if (/\s/u.test(char)) cleaned += " ";
+    else if (isCjk(code)) cleaned += ` ${char} `;
+    else cleaned += char;
+  }
+  cleaned = cleaned.toLowerCase().normalize("NFD").replace(/\p{Mn}/gu, "");
+  const tokens = [];
+  for (const word of cleaned.split(" ")) {
+    let current = "";
+    for (const char of word) {
+      if (isPunctuation(char.codePointAt(0), char)) {
+        if (current) tokens.push(current);
+        tokens.push(char);
+        current = "";
+      } else current += char;
+    }
+    if (current) tokens.push(current);
+  }
+  return tokens;
+}
+
+export function createTokenizer(tokenizerJson) {
+  const vocab = new Map(Object.entries(tokenizerJson.model.vocab));
+  const unk = vocab.get("[UNK]");
+  const cls = vocab.get("[CLS]");
+  const sep = vocab.get("[SEP]");
+  const wordPiece = (word) => {
+    const chars = [...word];
+    if (chars.length > 100) return [unk];
+    const pieces = [];
+    let start = 0;
+    while (start < chars.length) {
+      let end = chars.length;
+      let found;
+      while (start < end) {
+        const piece = `${start > 0 ? "##" : ""}${chars.slice(start, end).join("")}`;
+        if (vocab.has(piece)) { found = vocab.get(piece); break; }
+        end -= 1;
+      }
+      if (found === undefined) return [unk];
+      pieces.push(found);
+      start = end;
+    }
+    return pieces;
+  };
+  return (text) => {
+    const ids = basicTokens(text).flatMap(wordPiece).slice(0, EMBEDDING_MODEL.max_tokens - 2);
+    return [cls, ...ids, sep];
+  };
+}
+
+// ---- model download and loading ----
+
+async function download(url, target, expected, log) {
+  log(`stylegallery: downloading ${path.basename(target)} (${Math.round(expected.bytes / 1e6)} MB) for hybrid search into ${path.dirname(target)}`);
+  const response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS), redirect: "follow" });
+  if (!response.ok) throw new Error(`download failed: HTTP ${response.status}`);
+  const buffer = Buffer.from(await response.arrayBuffer());
+  if (sha256(buffer) !== expected.sha256) throw new Error(`download of ${path.basename(target)} failed its SHA-256 check`);
+  const temporary = `${target}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, buffer);
+  fs.renameSync(temporary, target);
+  return buffer;
+}
+
+async function modelFile(name, options) {
+  const expected = EMBEDDING_MODEL.files[name];
+  const directory = modelDirectory(options.env);
+  const target = path.join(directory, name);
+  if (fs.existsSync(target)) {
+    const buffer = fs.readFileSync(target);
+    if (sha256(buffer) === expected.sha256) return buffer;
+    fs.rmSync(target, { force: true });
+  }
+  if (options.env.STYLEGALLERY_OFFLINE === "1") throw new Error("model not cached and STYLEGALLERY_OFFLINE=1");
+  fs.mkdirSync(directory, { recursive: true });
+  const url = `https://huggingface.co/${EMBEDDING_MODEL.source}/resolve/${EMBEDDING_MODEL.revision}/${expected.remote}`;
+  return download(url, target, expected, options.log);
+}
+
+let embedderPromise = null;
+
+/**
+ * Load the query embedder once per process. Resolves to { embed } or to
+ * { error } with a one-line reason; never rejects.
+ */
+export function loadEmbedder(options = {}) {
+  const resolved = { env: options.env ?? process.env, log: options.log ?? ((line) => process.stderr.write(`${line}\n`)) };
+  embedderPromise ??= (async () => {
+    let ort;
+    try { ort = await import("onnxruntime-web"); } catch { throw new Error("optional dependency onnxruntime-web is not installed"); }
+    const tokenizerBuffer = await modelFile("tokenizer.json", resolved);
+    const modelBuffer = await modelFile("model_quantized.onnx", resolved);
+    ort.env.logLevel = "error";
+    ort.env.wasm.numThreads = 1;
+    const session = await ort.InferenceSession.create(modelBuffer);
+    const tokenize = createTokenizer(JSON.parse(tokenizerBuffer.toString("utf8")));
+    const embed = async (text) => {
+      const ids = tokenize(text);
+      const shape = [1, ids.length];
+      const output = await session.run({
+        input_ids: new ort.Tensor("int64", BigInt64Array.from(ids, BigInt), shape),
+        attention_mask: new ort.Tensor("int64", new BigInt64Array(ids.length).fill(1n), shape),
+        token_type_ids: new ort.Tensor("int64", new BigInt64Array(ids.length), shape),
+      });
+      const vector = Array.from(output.last_hidden_state.data.subarray(0, EMBEDDING_MODEL.dims));
+      const norm = Math.hypot(...vector) || 1;
+      return vector.map((value) => value / norm);
+    };
+    return { embed };
+  })().catch((error) => ({ error: error.message }));
+  return embedderPromise;
+}
+
+// ---- stored document vectors ----
+
+/** int8 quantization keeps the file small and makes stored vectors byte-stable across platforms. */
+export function quantize(vector) {
+  return Buffer.from(Int8Array.from(vector, (value) => Math.max(-127, Math.min(127, Math.round(value * 127)))).buffer).toString("base64");
+}
+
+export function dequantize(encoded) {
+  const bytes = Buffer.from(encoded, "base64");
+  return Float32Array.from(new Int8Array(bytes.buffer, bytes.byteOffset, bytes.length), (value) => value / 127);
+}
+
+let storedCache = null;
+
+/** Stored document vectors keyed by repository path, or null when the file is missing or for another model. */
+export function loadStoredEmbeddings(file = EMBEDDINGS_PATH) {
+  if (storedCache?.file === file) return storedCache.value;
+  let value = null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (parsed.model?.id === EMBEDDING_MODEL.id && parsed.model?.revision === EMBEDDING_MODEL.revision) {
+      value = new Map(Object.entries(parsed.documents).map(([key, entry]) => [key, { textHash: entry.text_sha256, vector: dequantize(entry.vector) }]));
+    }
+  } catch { value = null; }
+  storedCache = { file, value };
+  return value;
+}
+
+export function embeddingsFileContent(entries) {
+  const documents = Object.fromEntries([...entries].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
+  const { files, ...model } = EMBEDDING_MODEL;
+  return `${JSON.stringify({
+    schema_version: "1.0",
+    description: "Precomputed document vectors for hybrid search. Regenerate with node scripts/agent-native/v2/generate-search-embeddings.mjs.",
+    model: { ...model, files: Object.fromEntries(Object.entries(files).map(([name, { sha256: hash }]) => [name, hash])) },
+    document_text_chars: DOCUMENT_TEXT_CHARS,
+    quantization: "int8, value = byte / 127",
+    documents,
+  }, null, 1)}\n`;
+}

package/scripts/compiler/mcp.mjs

@@ -13,7 +13,7 @@ const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: t
 export const searchToolDefinitions = Object.freeze([
   {
     name: "search",
-    description: "Search the StyleGallery Markdown corpus (layout patterns, recipes, motion, design engineering, platform guides, terminology, expression). Offline BM25F ranking. Returns light results: id, path, title, description, a verbatim snippet, and the next read command. When the question is not in English, also pass query_en with an English rewrite; Korean-only queries match only documents with Korean aliases.",
+    description: "Search the StyleGallery Markdown corpus (layout patterns, recipes, motion, design engineering, platform guides, terminology, expression). Hybrid ranking by default: BM25F fused with an English embedding model (downloaded once, then offline); falls back to BM25F alone when the model is unavailable, and the result's mode field says which ran. Returns light results: id, path, title, description, a verbatim snippet, and the next read command. When the question is not in English, also pass query_en with an English rewrite; Korean-only queries match only documents with Korean aliases.",
     inputSchema: {
       type: "object", additionalProperties: false, required: ["query"],
       properties: {
@@ -21,6 +21,7 @@ export const searchToolDefinitions = Object.freeze([
         query_en: { type: "string", description: "English rewrite of query. Strongly recommended when query is not English." },
         limit: { type: "integer", minimum: 1, maximum: 50, default: 5 },
         paths_only: { type: "boolean", description: "Return repository-relative paths only." },
+        mode: { type: "string", enum: ["hybrid", "lexical"], default: "hybrid", description: "hybrid fuses BM25F with embedding similarity; lexical is BM25F only." },
         response_format: { type: "string", enum: ["concise", "detailed"], default: "concise", description: "detailed adds scores, hash identities, and ranking terms." },
       },
     },
@@ -72,7 +73,7 @@ export function createSgMcpServer(config = {}) {
     let input = request.params.arguments ?? {};
     let report;
     if (operation === "search" || operation === "read") {
-      report = invokeSearchOperation(operation, input, materialRuntimeOptions());
+      report = await invokeSearchOperation(operation, input, materialRuntimeOptions());
     } else if (Object.hasOwn(compilerOperations, operation) || operation === "workflow") {
       const signals = [lifetime.signal, extra.signal, config.signal].filter(Boolean);
       report = await executeCompiler(operation, input, { ...config, signal: AbortSignal.any(signals) });

package/scripts/stylegallery-cli.mjs

@@ -22,6 +22,9 @@ Find and read documents (offline, deterministic):
       --limit <n>               Results to return, 1-50 (default 5).
       --paths-only              Print repository-relative paths only.
       --detailed                Add scores, hash identities, and ranking terms.
+      --mode <hybrid|lexical>   hybrid (default) fuses BM25F with an English embedding model downloaded
+                                once to ~/.cache/stylegallery; lexical is BM25F only. Falls back to
+                                lexical with a warning when the model cannot load.
   read <id|path>                Read one document by id (sg:layout/sticky-header), path, or StableRef.
       --outline                 List headings with section slugs instead of the content.
       --section <slug>          Read one section only.
@@ -38,8 +41,8 @@ Governed records:
   registrar | conservator       Check claim records | measure Layout patterns in Chromium.
 
 Connect your agents:
-  setup                         Install the search skill and register stylegallery-mcp for Claude Code and Codex.
-      --agent <claude|codex|all> Agents to configure (default: the ones detected on this machine).
+  setup                         Install the search skill and register stylegallery-mcp for Claude Code, Codex, and OmO.
+      --agent <claude|codex|omo|all> Agents to configure (default: the ones detected on this machine).
       --only <skill|mcp>        Configure only the skill or only the MCP server.
       --dry-run                 Print the planned changes without writing anything.
       --uninstall               Remove what setup installed.
@@ -83,7 +86,7 @@ function parseOptions(command, args, specs) {
 async function runSearch(args) {
   const parsed = parseOptions("search", args, {
     "--query": { field: "query" }, "--query-en": { field: "query_en" }, "--limit": { field: "limit", integer: true },
-    "--paths-only": { field: "paths_only", flag: true }, "--detailed": { field: "detailed", flag: true },
+    "--paths-only": { field: "paths_only", flag: true }, "--detailed": { field: "detailed", flag: true }, "--mode": { field: "mode" },
   });
   if (parsed.error) return parsed.error;
   const { values, positional } = parsed;
@@ -94,7 +97,9 @@ async function runSearch(args) {
   const input = { ...rest, query, ...(detailed ? { response_format: "detailed" } : {}) };
   const { invokeSearchOperation } = await import("./agent-native/v2/material-search-v3.mjs");
   const { materialRuntimeOptions } = await import("./agent-native/v2/material-cli-adapter.mjs");
-  return report(invokeSearchOperation("search", input, materialRuntimeOptions()));
+  const outcome = await invokeSearchOperation("search", input, materialRuntimeOptions());
+  if (outcome.ok && outcome.result.mode_reason) process.stderr.write(`stylegallery: hybrid search unavailable (${outcome.result.mode_reason}); using lexical BM25F ranking\n`);
+  return report(outcome);
 }
 
 async function runRead(args) {
@@ -103,7 +108,7 @@ async function runRead(args) {
   if (parsed.positional.length !== 1) return failure("read", "argument_value_required", "give exactly one id, path, or StableRef: stylegallery read sg:layout/sticky-header");
   const { invokeSearchOperation } = await import("./agent-native/v2/material-search-v3.mjs");
   const { materialRuntimeOptions } = await import("./agent-native/v2/material-cli-adapter.mjs");
-  return report(invokeSearchOperation("read", { reference: parsed.positional[0], ...parsed.values }, materialRuntimeOptions()));
+  return report(await invokeSearchOperation("read", { reference: parsed.positional[0], ...parsed.values }, materialRuntimeOptions()));
 }
 
 async function runRetrieve(args) {