simple-dynamsoft-mcp 7.6.1 → 7.7.1

package/README.md

@@ -305,6 +305,8 @@ The server exposes this minimal tool surface:
 
 Typical doc Q&A flow: `search` -> `read_document` with the exact `doc://` URI -> answer from the returned text and cite its public URL. Clients that support MCP resources can also fetch the same `doc://` / `sample://` URIs with `resources/read`.
 
+DBR searches also cover the shared Capture Vision API pages that the DBR docs link to (for example `CaptureVisionRouter.capture()` and `getSimplifiedSettings()`/`updateSettings()`); these hits keep their official `capture-vision/docs` URL and are labelled `shared Capture Vision API used by DBR` in search results. Doc URIs are path-based (`doc://dbr/web/web/<version>/user-guide/use-in-framework`) and change only when the docs move or the SDK version changes.
+
 ## Advanced Configuration And Operator Docs
 
 Advanced settings, CI/runbook details, and maintenance workflows live in:

package/data/metadata/data-manifest.json

@@ -28,8 +28,8 @@
       "branch": "main",
       "owner": "dynamsoft-docs",
       "repo": "barcode-reader-docs-server",
-      "commit": "7aa8985f9918460466b3dde1426f5ad1342fa93e",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/barcode-reader-docs-server/zip/7aa8985f9918460466b3dde1426f5ad1342fa93e"
+      "commit": "f82b5b92fb039064be3d355f9aeaacf0947b7096",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/barcode-reader-docs-server/zip/f82b5b92fb039064be3d355f9aeaacf0947b7096"
     },
     {
       "name": "data/documentation/capture-vision-docs",
@@ -38,8 +38,8 @@
       "branch": "main",
       "owner": "dynamsoft-docs",
       "repo": "capture-vision-docs",
-      "commit": "f3ddf9614ca3d5f153bdc780cd740732d30d3de9",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/capture-vision-docs/zip/f3ddf9614ca3d5f153bdc780cd740732d30d3de9"
+      "commit": "428c0080975aee70f15e09deda09ca548a4f9a93",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/capture-vision-docs/zip/428c0080975aee70f15e09deda09ca548a4f9a93"
     },
     {
       "name": "data/documentation/capture-vision-docs-js",
@@ -68,8 +68,8 @@
       "branch": "main",
       "owner": "dynamsoft-docs",
       "repo": "capture-vision-docs-server",
-      "commit": "1e7455238c8fe8f935640c1c31c0c433798ce1f0",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/capture-vision-docs-server/zip/1e7455238c8fe8f935640c1c31c0c433798ce1f0"
+      "commit": "4138672377f9ac99380bc985d28fbbe457c31c2b",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/capture-vision-docs-server/zip/4138672377f9ac99380bc985d28fbbe457c31c2b"
     },
     {
       "name": "data/documentation/document-viewer-docs",
@@ -108,8 +108,8 @@
       "branch": "master",
       "owner": "dynamsoft-docs",
       "repo": "web-twain-docs",
-      "commit": "3cb367e1e733a6556902f328b6b51fad0280d2b9",
-      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/3cb367e1e733a6556902f328b6b51fad0280d2b9"
+      "commit": "256fe47f8b83c79cbf8f23034fe77eab65a3fc7b",
+      "archiveUrl": "https://codeload.github.com/dynamsoft-docs/web-twain-docs/zip/256fe47f8b83c79cbf8f23034fe77eab65a3fc7b"
     },
     {
       "name": "data/samples/document-scanner-javascript",
@@ -148,8 +148,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "barcode-reader-c-cpp-samples",
-      "commit": "8d4b48cc525d65569ae63c2317c907a06b5e8322",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-c-cpp-samples/zip/8d4b48cc525d65569ae63c2317c907a06b5e8322"
+      "commit": "96e6242b43253a930b1edf6bbe5b0dbcadf1bb5a",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-c-cpp-samples/zip/96e6242b43253a930b1edf6bbe5b0dbcadf1bb5a"
     },
     {
       "name": "data/samples/dynamsoft-barcode-reader-dotnet",
@@ -158,8 +158,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "barcode-reader-dotnet-samples",
-      "commit": "641cdf391b514e67a75f5bb6bc25ace068af8b38",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-dotnet-samples/zip/641cdf391b514e67a75f5bb6bc25ace068af8b38"
+      "commit": "49e205da121046998d8633c80ff2e31d3d3594f3",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-dotnet-samples/zip/49e205da121046998d8633c80ff2e31d3d3594f3"
     },
     {
       "name": "data/samples/dynamsoft-barcode-reader-flutter",
@@ -178,8 +178,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "barcode-reader-java-samples",
-      "commit": "caab3b6c1737f465047f84bbb77f827f19bb8523",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-java-samples/zip/caab3b6c1737f465047f84bbb77f827f19bb8523"
+      "commit": "fbadec4609803fb3ec542b20b630adb99481cfe2",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-java-samples/zip/fbadec4609803fb3ec542b20b630adb99481cfe2"
     },
     {
       "name": "data/samples/dynamsoft-barcode-reader-maui",
@@ -208,8 +208,8 @@
       "branch": "master",
       "owner": "Dynamsoft",
       "repo": "barcode-reader-python-samples",
-      "commit": "a754aab9e4fb9630519382402f32250c94d8643b",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-python-samples/zip/a754aab9e4fb9630519382402f32250c94d8643b"
+      "commit": "bd63acaaf5d8b427aee7d3d1c8b316dc3021b9f5",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/barcode-reader-python-samples/zip/bd63acaaf5d8b427aee7d3d1c8b316dc3021b9f5"
     },
     {
       "name": "data/samples/dynamsoft-barcode-reader-react-native",
@@ -228,8 +228,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "capture-vision-cpp-samples",
-      "commit": "9bd516bc1961425eed02b2308505a9a6c775b38d",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-cpp-samples/zip/9bd516bc1961425eed02b2308505a9a6c775b38d"
+      "commit": "cfd0fc6f4fee070e188955dd0cccfab39ff2c02d",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-cpp-samples/zip/cfd0fc6f4fee070e188955dd0cccfab39ff2c02d"
     },
     {
       "name": "data/samples/dynamsoft-capture-vision-dotnet",
@@ -238,8 +238,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "capture-vision-dotnet-samples",
-      "commit": "871ffea41164e08ed1315157c3feb7912915fa40",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-dotnet-samples/zip/871ffea41164e08ed1315157c3feb7912915fa40"
+      "commit": "f3fe6aecc7c3c628f4241fe3a52ed448680c9d64",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-dotnet-samples/zip/f3fe6aecc7c3c628f4241fe3a52ed448680c9d64"
     },
     {
       "name": "data/samples/dynamsoft-capture-vision-flutter",
@@ -258,8 +258,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "capture-vision-java-samples",
-      "commit": "760f9e3f5fed9c74d813ffc30fbcd9a5a96bf576",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-java-samples/zip/760f9e3f5fed9c74d813ffc30fbcd9a5a96bf576"
+      "commit": "83660139a8d32b0b319b6bc0b213b827437ddc43",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-java-samples/zip/83660139a8d32b0b319b6bc0b213b827437ddc43"
     },
     {
       "name": "data/samples/dynamsoft-capture-vision-maui",
@@ -298,8 +298,8 @@
       "branch": "main",
       "owner": "Dynamsoft",
       "repo": "capture-vision-python-samples",
-      "commit": "f54b2d281b8325e8765f535be8ef6ebf157f4a54",
-      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-python-samples/zip/f54b2d281b8325e8765f535be8ef6ebf157f4a54"
+      "commit": "6f350f5d68e3ddcd90041bf46cac5541677f04b5",
+      "archiveUrl": "https://codeload.github.com/Dynamsoft/capture-vision-python-samples/zip/6f350f5d68e3ddcd90041bf46cac5541677f04b5"
     },
     {
       "name": "data/samples/dynamsoft-capture-vision-react-native",

package/data/metadata/dynamsoft_sdks.json

@@ -120,7 +120,7 @@
     "dbr-server": {
       "name": "Dynamsoft Barcode Reader Server/Desktop SDK",
       "description": "Barcode scanning for server/desktop platforms including Python, .NET, Java, C++, and Node.js.",
-      "version": "11.6.4000",
+      "version": "11.6.5000",
       "default_platform": "python",
       "snippet_path": "dynamsoft-barcode-reader/server",
       "platforms": {
@@ -255,7 +255,7 @@
     "dcv-core": {
       "name": "Dynamsoft Capture Vision Core",
       "description": "Unified architecture documentation for Capture Vision capabilities across barcode, MRZ, document normalization, and parsing workflows.",
-      "version": "3.6.4000",
+      "version": "3.6.5000",
       "default_platform": "core",
       "snippet_path": "dynamsoft-capture-vision/core",
       "platforms": {
@@ -270,7 +270,7 @@
     "dcv-server": {
       "name": "Dynamsoft Capture Vision Server/Desktop SDK",
       "description": "Capture Vision workflows for Python, .NET, Java, C++, and Node.js, including MRZ, document normalization, and driver license scenarios.",
-      "version": "3.6.4000",
+      "version": "3.6.5000",
       "default_platform": "python",
       "snippet_path": "dynamsoft-capture-vision/server",
       "platforms": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.6.1",
+  "version": "7.7.1",
   "description": "MCP server for Dynamsoft SDKs - Capture Vision, Barcode Reader (Mobile/Python/Web), Dynamic Web TWAIN, and Document Viewer. Provides documentation, code snippets, and API guidance.",
   "license": "MIT",
   "repository": {
@@ -24,13 +24,15 @@
   "scripts": {
     "start": "node src/index.js",
     "test": "npm run test:lite",
-    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/request-logging.test.js test/unit/request-log-file.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/update-sdk-versions.test.js test/unit/version-policy.test.js test/unit/query-expansion.test.js test/unit/docs-loader-enrich.test.js",
+    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/request-logging.test.js test/unit/request-log-file.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/update-sdk-versions.test.js test/unit/version-policy.test.js test/unit/query-expansion.test.js test/unit/docs-loader-enrich.test.js test/unit/shared-docs.test.js test/unit/vector-cache.test.js test/unit/doc-slugs.test.js",
     "test:lite": "npm run test:stdio && npm run test:http && npm run test:package",
     "test:lexical": "node --test test/integration/stdio.test.js test/integration/http.test.js",
     "test:gemini": "node scripts/run-gemini-tests.mjs",
     "test:stdio": "node --test test/integration/stdio.test.js",
     "test:http": "node --test test/integration/http.test.js",
     "test:package": "node --test test/integration/package-runtime.test.js",
+    "test:retrieval": "node --test test/integration/retrieval-quality.test.js",
+    "eval:retrieval": "node scripts/eval-retrieval.mjs",
     "test:contract": "node --test test/contract/contract.test.js",
     "check:version-drift": "node scripts/check-version-drift.mjs",
     "test:lazy": "node --test test/integration/lazy-hydration.test.js",

package/scripts/eval-retrieval.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Measures search relevance against the golden query set.
+//
+//   node scripts/eval-retrieval.mjs [--provider=lexical|gemini] [--case=<id>] [--show] [--json=<path>]
+//
+// The provider is passed through RAG_PROVIDER before the RAG layer loads, with
+// fallback disabled so a failing provider is reported instead of masked.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = Object.fromEntries(
+  process.argv.slice(2).map((arg) => {
+    const [key, ...rest] = arg.replace(/^--/, "").split("=");
+    return [key, rest.length ? rest.join("=") : "true"];
+  })
+);
+const provider = args.provider || "lexical";
+process.env.RAG_PROVIDER = provider;
+process.env.RAG_FALLBACK = "none";
+process.env.RAG_PREWARM = "false";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const goldenPath = args.golden || join(repoRoot, "test", "fixtures", "retrieval-golden.json");
+const golden = JSON.parse(readFileSync(goldenPath, "utf8"));
+const cases = args.case ? golden.cases.filter((item) => item.id === args.case) : golden.cases;
+if (cases.length === 0) {
+  console.error(`No golden cases matched ${args.case}`);
+  process.exit(1);
+}
+
+const { ensureResourceIndexReady } = await import("../src/server/resource-index.js");
+const { searchResources } = await import("../src/rag/index.js");
+const { runRetrievalEval } = await import("./lib/retrieval-eval.mjs");
+const { isResultInScope } = await import("./lib/scope-matcher.mjs");
+
+ensureResourceIndexReady();
+const report = await runRetrievalEval({ searchResources, cases, k: golden.k || 5, isInScope: isResultInScope });
+report.provider = provider;
+
+const fmt = (value) => (value === null || value === undefined ? "n/a" : value.toFixed(3));
+for (const item of report.cases) {
+  const flag = item.gap ? "GAP " : item.requiredHit === false ? "MISS" : "ok  ";
+  console.log(`${flag} ${item.id.padEnd(34)} recall=${fmt(item.recall)} mrr=${fmt(item.mrr)} ndcg=${fmt(item.ndcg)} dup=${item.duplicates} off=${item.offScope} rn=${item.releaseNotes} ms=${item.latencyMs.toFixed(0)}`);
+  if (args.show || item.requiredHit === false) {
+    for (const hit of item.top) {
+      console.log(`       ${hit.rank}. [g${hit.grade}] [${hit.product}] ${hit.title} :: ${hit.url || hit.uri}`);
+    }
+    for (const url of item.requiredMissing) console.log(`       missing: ${url}`);
+  }
+}
+
+const s = report.summary;
+console.log(`\nprovider=${provider} cases=${s.cases} (gap=${s.gapCases}) k=${report.k}`);
+console.log(`recall@${report.k}=${fmt(s.recallAtK)} mrr=${fmt(s.mrr)} ndcg@${report.k}=${fmt(s.ndcgAtK)} required_hit=${fmt(s.requiredHitRate)}`);
+console.log(`duplicate_rate=${fmt(s.duplicateRate)} off_scope_rate=${fmt(s.offScopeRate)} release_notes_rate=${fmt(s.releaseNotesRate)}`);
+const lat = s.latencyMs;
+console.log(`latency_ms first_query=${lat.firstQuery.toFixed(0)} first_pass p50=${lat.p50FirstPass.toFixed(0)} p95=${lat.p95FirstPass.toFixed(0)} | warm p50=${lat.p50Warm.toFixed(0)} p95=${lat.p95Warm.toFixed(0)}`);
+
+if (args.json) {
+  writeFileSync(args.json, JSON.stringify(report, null, 2));
+  console.log(`wrote ${args.json}`);
+}

package/scripts/lib/retrieval-eval.mjs

@@ -0,0 +1,134 @@
+// Retrieval-quality metrics for the golden query set (test/fixtures/retrieval-golden.json).
+// Cases grade relevant documents by public URL (not doc:// URI) so judgments
+// survive URI-scheme and index-order changes.
+
+function normalizeUrl(url) {
+  return String(url || "").split("#")[0].split("?")[0].replace(/\/index\.html$/i, "/").toLowerCase();
+}
+
+function gradeOf(result, relevant) {
+  const key = normalizeUrl(result.url);
+  if (!key) return 0;
+  return relevant.get(key) || 0;
+}
+
+function dcg(gains) {
+  return gains.reduce((sum, gain, index) => sum + ((2 ** gain) - 1) / Math.log2(index + 2), 0);
+}
+
+function percentile(values, p) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[Math.max(0, index)];
+}
+
+// `isInScope(result, filters)` (when given) applies the server's own
+// product/edition/platform matching so cross-platform leakage is counted too.
+function isOffScope(result, testCase, isInScope) {
+  const product = testCase.filters?.product;
+  if (product && result.product !== product) return true;
+  if (isInScope && !isInScope(result, testCase.filters || {})) return true;
+  const prefixes = testCase.allowedUrlPrefixes;
+  if (Array.isArray(prefixes) && prefixes.length > 0 && result.url) {
+    return !prefixes.some((prefix) => String(result.url).startsWith(prefix));
+  }
+  return false;
+}
+
+function isReleaseNotes(result) {
+  return /\/release-notes?\//i.test(String(result.url || ""));
+}
+
+function scoreCase(testCase, results, k, isInScope) {
+  const relevant = new Map(
+    Object.entries(testCase.relevant || {}).map(([url, grade]) => [normalizeUrl(url), Number(grade) || 0])
+  );
+  const top = results.slice(0, k);
+  const gains = top.map((result) => gradeOf(result, relevant));
+  const positiveGains = [...relevant.values()].filter((g) => g > 0).sort((a, b) => b - a);
+  const idealGains = positiveGains.slice(0, k);
+  const relevantCount = positiveGains.length;
+
+  const firstHit = gains.findIndex((gain) => gain > 0);
+  const found = new Set(top.filter((result) => gradeOf(result, relevant) > 0).map((r) => normalizeUrl(r.url)));
+  const required = [...relevant.entries()].filter(([, grade]) => grade >= 3).map(([url]) => url);
+  const requiredFound = required.filter((url) => found.has(url));
+
+  const urls = top.map((result) => normalizeUrl(result.url || result.uri));
+  const duplicates = urls.length - new Set(urls).size;
+
+  return {
+    id: testCase.id,
+    gap: relevantCount === 0,
+    recall: relevantCount ? found.size / relevantCount : null,
+    mrr: relevantCount ? (firstHit >= 0 ? 1 / (firstHit + 1) : 0) : null,
+    ndcg: relevantCount ? dcg(gains) / dcg(idealGains) : null,
+    requiredHit: required.length ? requiredFound.length === required.length : null,
+    requiredMissing: required.filter((url) => !found.has(url)),
+    duplicates,
+    offScope: top.filter((result) => isOffScope(result, testCase, isInScope)).length,
+    releaseNotes: top.filter(isReleaseNotes).length,
+    returned: top.length,
+    top: top.map((result, index) => ({
+      rank: index + 1,
+      grade: gains[index],
+      product: result.product,
+      title: result.title,
+      url: result.url || "",
+      uri: result.uri
+    }))
+  };
+}
+
+function mean(values) {
+  const present = values.filter((value) => value !== null && value !== undefined);
+  if (present.length === 0) return null;
+  return present.reduce((sum, value) => sum + value, 0) / present.length;
+}
+
+function summarize(caseScores, firstPass, warmPass) {
+  const totalReturned = caseScores.reduce((sum, item) => sum + item.returned, 0) || 1;
+  const required = caseScores.filter((item) => item.requiredHit !== null);
+  return {
+    cases: caseScores.length,
+    gapCases: caseScores.filter((item) => item.gap).length,
+    recallAtK: mean(caseScores.map((item) => item.recall)),
+    mrr: mean(caseScores.map((item) => item.mrr)),
+    ndcgAtK: mean(caseScores.map((item) => item.ndcg)),
+    requiredHitRate: required.length ? required.filter((item) => item.requiredHit).length / required.length : null,
+    duplicateRate: caseScores.reduce((sum, item) => sum + item.duplicates, 0) / totalReturned,
+    offScopeRate: caseScores.reduce((sum, item) => sum + item.offScope, 0) / totalReturned,
+    releaseNotesRate: caseScores.reduce((sum, item) => sum + item.releaseNotes, 0) / totalReturned,
+    // First pass pays index loading and per-scope index builds; the warm pass
+    // repeats the same queries, so it reflects steady-state search cost.
+    latencyMs: {
+      firstQuery: firstPass[0] ?? 0,
+      p50FirstPass: percentile(firstPass, 50),
+      p95FirstPass: percentile(firstPass, 95),
+      p50Warm: percentile(warmPass, 50),
+      p95Warm: percentile(warmPass, 95)
+    }
+  };
+}
+
+async function runRetrievalEval({ searchResources, cases, k = 5, isInScope }) {
+  const caseScores = [];
+  const firstPass = [];
+  const warmPass = [];
+  for (const testCase of cases) {
+    const startedAt = performance.now();
+    const results = await searchResources({ query: testCase.query, ...(testCase.filters || {}), limit: k, throwOnError: true });
+    const latencyMs = performance.now() - startedAt;
+    firstPass.push(latencyMs);
+    caseScores.push({ ...scoreCase(testCase, results, k, isInScope), latencyMs });
+  }
+  for (const testCase of cases) {
+    const startedAt = performance.now();
+    await searchResources({ query: testCase.query, ...(testCase.filters || {}), limit: k, throwOnError: true });
+    warmPass.push(performance.now() - startedAt);
+  }
+  return { k, summary: summarize(caseScores, firstPass, warmPass), cases: caseScores };
+}
+
+export { normalizeUrl, scoreCase, summarize, runRetrievalEval };

package/scripts/lib/scope-matcher.mjs

@@ -0,0 +1,17 @@
+// Scope check for retrieval evaluation, using the same normalizers and
+// matchers the search path applies to filters.
+import {
+  normalizeProduct,
+  normalizePlatform,
+  normalizeEdition,
+  editionMatches,
+  platformMatches
+} from "../../src/server/resource-index.js";
+import { normalizeSearchFilters, entryMatchesScope } from "../../src/rag/search-utils.js";
+
+function isResultInScope(result, rawFilters) {
+  const filters = normalizeSearchFilters(rawFilters, { normalizeProduct, normalizePlatform, normalizeEdition });
+  return entryMatchesScope(result, filters, { editionMatches, platformMatches });
+}
+
+export { isResultInScope };

package/scripts/prebuild-rag-index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 
 function toPosixPath(path) {
@@ -32,7 +32,11 @@ if (!existsSync(cacheDir)) {
   throw new Error(`RAG cache directory not found after prebuild: ${cacheDir}`);
 }
 
-const cacheFiles = readdirSync(cacheDir, { withFileTypes: true })
+// Each cache is a JSON header plus a sibling `.f32` vector file (see
+// src/rag/vector-cache.js); both ship in the release archive. A header with no
+// `.f32` is a pre-7.7 all-JSON cache (e.g. restored from an older CI cache):
+// the runtime cannot load it, so it is deleted rather than shipped.
+const allHeaders = readdirSync(cacheDir, { withFileTypes: true })
   .filter((entry) => entry.isFile())
   .map((entry) => join(cacheDir, entry.name))
   .filter((path) => {
@@ -44,10 +48,23 @@ const cacheFiles = readdirSync(cacheDir, { withFileTypes: true })
   })
   .sort();
 
+const toVectorFile = (path) => path.replace(/\.json$/i, ".f32");
+const cacheFiles = [];
+for (const path of allHeaders) {
+  if (existsSync(toVectorFile(path))) {
+    cacheFiles.push(path);
+  } else {
+    rmSync(path, { force: true });
+    console.log(`[rag-prebuild] removed legacy cache without vectors: ${basename(path)}`);
+  }
+}
+
 if (cacheFiles.length === 0) {
-  throw new Error(`No cache JSON files found in ${cacheDir}.`);
+  throw new Error(`No cache files with vectors found in ${cacheDir}.`);
 }
 
+const vectorFiles = cacheFiles.map(toVectorFile);
+
 let indexSignature = "";
 let indexCacheKey = "";
 const geminiCacheFile = cacheFiles.find((path) => /rag-gemini-.*\.json$/i.test(path));
@@ -69,7 +86,7 @@ const manifest = {
   indexSignature,
   indexCacheKey,
   cacheDir: toPosixPath(cacheDir),
-  files: cacheFiles.map((path) => {
+  files: [...cacheFiles, ...vectorFiles].sort().map((path) => {
     const stats = statSync(path);
     return {
       name: toPosixPath(path.slice(cacheDir.length + 1)),

package/scripts/verify-doc-resources.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { resourceIndex, readResourceContent } from "../src/server/resource-index.js";
+import { ensureResourceIndexReady, resourceIndex, readResourceContent } from "../src/server/resource-index.js";
 
 function parsePositiveInt(value, fallback) {
   const parsed = Number.parseInt(String(value ?? ""), 10);
@@ -9,6 +9,7 @@ function parsePositiveInt(value, fallback) {
 }
 
 async function main() {
+  ensureResourceIndexReady();
   const concurrency = parsePositiveInt(process.env.DOC_VERIFY_CONCURRENCY, 8);
   const docs = resourceIndex.filter((entry) => entry.type === "doc");
   const total = docs.length;

package/src/data/repo-map.js

@@ -3,14 +3,33 @@ import { getHydrationProduct } from "../server/public-offerings.js";
 
 const REPO_MAP = {
   dbr: {
+    // DBR docs index the Capture Vision pages they link to (shared APIs such as
+    // CaptureVisionRouter), so each DBR edition also needs the matching DCV
+    // edition repo plus DCV core.
     docs: {
-      web: ["documentation/barcode-reader-docs-js"],
-      mobile: ["documentation/barcode-reader-docs-mobile"],
-      server: ["documentation/barcode-reader-docs-server"],
+      web: [
+        "documentation/barcode-reader-docs-js",
+        "documentation/capture-vision-docs-js",
+        "documentation/capture-vision-docs"
+      ],
+      mobile: [
+        "documentation/barcode-reader-docs-mobile",
+        "documentation/capture-vision-docs-mobile",
+        "documentation/capture-vision-docs"
+      ],
+      server: [
+        "documentation/barcode-reader-docs-server",
+        "documentation/capture-vision-docs-server",
+        "documentation/capture-vision-docs"
+      ],
       any: [
         "documentation/barcode-reader-docs-js",
         "documentation/barcode-reader-docs-mobile",
-        "documentation/barcode-reader-docs-server"
+        "documentation/barcode-reader-docs-server",
+        "documentation/capture-vision-docs",
+        "documentation/capture-vision-docs-js",
+        "documentation/capture-vision-docs-mobile",
+        "documentation/capture-vision-docs-server"
       ]
     },
     samples: {

package/src/rag/config.js

@@ -63,12 +63,10 @@ const ragConfig = {
   modelCacheDir: readEnvValue("RAG_MODEL_CACHE_DIR", join(dataRoot, ".rag-cache", "models")),
   chunkSize: readIntEnv("RAG_CHUNK_SIZE", 1200),
   chunkOverlap: readIntEnv("RAG_CHUNK_OVERLAP", 200),
-  // Keep the total embedded-chunk count within V8's ~512MB max-string limit,
-  // which the prebuilt Gemini cache hits via a single JSON.stringify of ~3072-dim
-  // vectors. At 24 the release prebuild overflowed ("Invalid string length"); 6 is
-  // the count the pre-v7.4 release built successfully on this data. Raising this
-  // needs the ceiling-proof cache format tracked in the v7.5 follow-ups.
-  maxChunksPerDoc: readIntEnv("RAG_MAX_CHUNKS_PER_DOC", 6),
+  // 0 = embed every chunk of every doc (~19.7k chunks vs ~10.3k at the old cap
+  // of 6). Each chunk is one Gemini embedding per release prebuild; the vector
+  // cache is header + float32 (src/rag/vector-cache.js), so there is no size cap.
+  maxChunksPerDoc: readIntEnv("RAG_MAX_CHUNKS_PER_DOC", 0),
   maxTextChars: readIntEnv("RAG_MAX_TEXT_CHARS", 4000),
   minScore: readFloatEnv("RAG_MIN_SCORE", 0.2),
   includeScore: readBoolEnv("RAG_INCLUDE_SCORE", false),

package/src/rag/index.js

@@ -102,7 +102,22 @@ function refreshRagIndexes() {
   logRag(`indexes refreshed resources=${resourceIndex.length}`);
 }
 
-async function searchResources({ query, product, edition, platform, type, limit }) {
+function dedupeByPublicUrl(results, limit) {
+  const seen = new Set();
+  const unique = [];
+  for (const entry of results) {
+    const key = entry.url || entry.uri;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(entry);
+    if (limit && unique.length >= limit) break;
+  }
+  return unique;
+}
+
+// `throwOnError` makes an all-providers failure throw instead of returning [];
+// evaluation uses it so a broken provider cannot pass as zero relevance.
+async function searchResources({ query, product, edition, platform, type, limit, throwOnError = false }) {
   const startedAt = Date.now();
   const filters = normalizeSearchFilters({ product, edition, platform, type }, {
     normalizeProduct,
@@ -133,7 +148,11 @@ async function searchResources({ query, product, edition, platform, type, limit
   for (const name of providers) {
     try {
       const provider = await providerOrchestrator.loadSearchProvider(name);
-      const results = await provider.search(searchQuery, filters, maxResults);
+      // Shared pages (e.g. Capture Vision core reference) are indexed once per
+      // DBR edition, so an edition-less search can hit the same public page
+      // several times. Over-fetch, then keep the best hit per public URL.
+      const candidates = await provider.search(searchQuery, filters, maxResults ? maxResults * 3 : undefined);
+      const results = dedupeByPublicUrl(candidates, maxResults);
       if (!ragLogState.providerFirstUse.has(name)) {
         ragLogState.providerFirstUse.add(name);
         logRag("provider_selected", {
@@ -191,6 +210,7 @@ async function searchResources({ query, product, edition, platform, type, limit
       latency_bucket: latencyBucket(elapsedMs),
       error: lastError.message
     }, { level: "error" });
+    if (throwOnError) throw lastError;
   }
   return [];
 }