From d3f38ed1854bff9704be126da71651d44b638f9d Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Fri, 27 Mar 2026 09:19:09 -0700
Subject: [PATCH] feat(docs): enhance search with TF-IDF relevance ranking
 (#40)

Search improvements:
- TF-IDF relevance ranking toggle (localStorage persistent)
- Pagefind basePath fix for dev mode
- Conditional keyword highlights (on when relevance off)
- Playwright e2e tests with self-contained webServer
- build:pagefind convenience script for dev
- CI: docs search index build step for test suite

Team review: Flight approve, FIDO approve
Relates to diberry/squad#40

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/squad-ci.yml      |   3 +
 docs/.gitignore                     |   2 +
 docs/package.json                   |   4 +-
 docs/playwright.config.mjs          |   8 +-
 docs/scripts/build-search-index.mjs | 153 +++++++++++++++++++
 docs/src/components/Search.astro    | 180 +++++++++++++++++++++--
 docs/src/styles/global.css          |   2 +-
 docs/tests/search.spec.mjs          |   2 +-
 test/docs-search.test.ts            | 218 ++++++++++++++++++++++++++++
 9 files changed, 559 insertions(+), 13 deletions(-)
 create mode 100644 docs/scripts/build-search-index.mjs
 create mode 100644 test/docs-search.test.ts

diff --git a/.github/workflows/squad-ci.yml b/.github/workflows/squad-ci.yml
index 773754e39..01b0f491e 100644
--- a/.github/workflows/squad-ci.yml
+++ b/.github/workflows/squad-ci.yml
@@ -179,6 +179,9 @@ jobs:
       - name: Build
         run: npm run build
 
+      - name: Build docs search index
+        run: cd docs && npm ci && npm run build:search && mkdir -p dist && cp public/search-index.json dist/search-index.json
+
       - name: Run tests
         run: npm test
 
diff --git a/docs/.gitignore b/docs/.gitignore
index ddce69b68..6ec296f6a 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,3 +1,5 @@
 node_modules/
 dist/
 .astro/
+public/search-index.json
+public/pagefind/
diff --git a/docs/package.json b/docs/package.json
index 488a4890d..7e0853063 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -5,7 +5,9 @@
   "private": true,
   "scripts": {
     "dev": "astro dev",
-    "build": "astro build && npx pagefind --site dist",
+    "build:search": "node scripts/build-search-index.mjs",
+    "build:pagefind": "npm run build && node -e \"require('fs').cpSync('dist/pagefind','public/pagefind',{recursive:true,force:true});console.log('Pagefind index copied to public/pagefind — dev search ready')\"",
+    "build": "node scripts/build-search-index.mjs && astro build && npx pagefind --site dist",
     "preview": "astro preview",
     "astro": "astro",
     "test": "node --test tests/build-output.test.mjs && npx playwright test",
diff --git a/docs/playwright.config.mjs b/docs/playwright.config.mjs
index 2c69a1ac9..fd04fe182 100644
--- a/docs/playwright.config.mjs
+++ b/docs/playwright.config.mjs
@@ -6,8 +6,14 @@ export default defineConfig({
   timeout: 30_000,
   retries: 0,
   use: {
-    baseURL: 'http://localhost:4321/squad/',
+    baseURL: 'http://localhost:4322/squad/',
     browserName: 'chromium',
     headless: true,
   },
+  webServer: {
+    command: 'npm run build && npx astro preview --port 4322',
+    port: 4322,
+    timeout: 120_000,
+    reuseExistingServer: !process.env.CI,
+  },
 });
diff --git a/docs/scripts/build-search-index.mjs b/docs/scripts/build-search-index.mjs
new file mode 100644
index 000000000..00e082849
--- /dev/null
+++ b/docs/scripts/build-search-index.mjs
@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * build-search-index.mjs
+ * Reads all .md files from docs/src/content/docs/, chunks by ## headings,
+ * and outputs a static search-index.json for client-side TF-IDF search.
+ */
+
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, relative, dirname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DOCS_ROOT = join(__dirname, '..', 'src', 'content', 'docs');
+const OUTPUT_DIR = join(__dirname, '..', 'public');
+const OUTPUT_FILE = join(OUTPUT_DIR, 'search-index.json');
+
+// Section display names derived from directory
+const SECTION_NAMES = {
+  'get-started': 'Get Started',
+  guide: 'Guide',
+  features: 'Features',
+  reference: 'Reference',
+  scenarios: 'Scenarios',
+  concepts: 'Concepts',
+  cookbook: 'Cookbook',
+};
+
+async function collectMdFiles(dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await collectMdFiles(full)));
+    } else if (entry.name.endsWith('.md')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+function stripFrontmatter(content) {
+  const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+  return match ? content.slice(match[0].length) : content;
+}
+
+function extractTitle(content) {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : 'Untitled';
+}
+
+function deriveSlug(filePath) {
+  let rel = relative(DOCS_ROOT, filePath)
+    .replace(/\\/g, '/')
+    .replace(/\.md$/, '');
+  if (rel.endsWith('/index')) rel = rel.replace(/\/index$/, '');
+  return rel;
+}
+
+function deriveSection(slug) {
+  const first = slug.split('/')[0];
+  return SECTION_NAMES[first] || first.charAt(0).toUpperCase() + first.slice(1);
+}
+
+function stripMarkdown(text) {
+  return text
+    .replace(/!\[.*?\]\(.*?\)/g, '')        // images
+    .replace(/\[([^\]]*)\]\(.*?\)/g, '$1')   // links → text
+    .replace(/(`{1,3})[\s\S]*?\1/g, '')      // inline/fenced code
+    .replace(/^>\s?/gm, '')                  // blockquotes
+    .replace(/[*_~]{1,3}/g, '')              // bold/italic/strikethrough
+    .replace(/^[-*+]\s/gm, '')               // unordered list markers
+    .replace(/^\d+\.\s/gm, '')               // ordered list markers
+    .replace(/\|/g, ' ')                     // table pipes
+    .replace(/^-{3,}$/gm, '')               // horizontal rules
+    .replace(/<[^>]+>/g, '')                 // HTML tags
+    .replace(/\n{2,}/g, '\n')               // collapse blank lines
+    .trim();
+}
+
+function chunkByHeadings(content, pageTitle, slug) {
+  const body = stripFrontmatter(content);
+  const section = deriveSection(slug);
+  const lines = body.split('\n');
+  const chunks = [];
+  let currentHeading = pageTitle;
+  let buffer = [];
+
+  function flush() {
+    const raw = buffer.join('\n').trim();
+    if (!raw) return;
+    const text = stripMarkdown(raw);
+    if (text.length < 20) return; // skip tiny chunks
+    chunks.push({
+      title: pageTitle,
+      slug,
+      section,
+      heading: currentHeading,
+      text,
+    });
+  }
+
+  for (const line of lines) {
+    const headingMatch = line.match(/^#{2,3}\s+(.+)/);
+    if (headingMatch) {
+      flush();
+      currentHeading = headingMatch[1].trim();
+      buffer = [];
+    } else {
+      buffer.push(line);
+    }
+  }
+  flush();
+
+  // If no chunks were produced, add the whole page as one chunk
+  if (chunks.length === 0) {
+    const text = stripMarkdown(body);
+    if (text.length >= 20) {
+      chunks.push({ title: pageTitle, slug, section, heading: pageTitle, text });
+    }
+  }
+
+  return chunks;
+}
+
+async function main() {
+  console.log('Building search index...');
+  const files = await collectMdFiles(DOCS_ROOT);
+  console.log(`Found ${files.length} markdown files`);
+
+  const allChunks = [];
+
+  for (const file of files) {
+    const content = await readFile(file, 'utf-8');
+    const title = extractTitle(content);
+    const slug = deriveSlug(file);
+    const chunks = chunkByHeadings(content, title, slug);
+    allChunks.push(...chunks);
+  }
+
+  await mkdir(OUTPUT_DIR, { recursive: true });
+  const json = JSON.stringify(allChunks);
+  await writeFile(OUTPUT_FILE, json, 'utf-8');
+
+  const sizeKB = (Buffer.byteLength(json) / 1024).toFixed(1);
+  console.log(`✓ ${allChunks.length} chunks from ${files.length} files`);
+  console.log(`✓ Output: search-index.json (${sizeKB} KB)`);
+}
+
+main().catch((err) => {
+  console.error('Build search index failed:', err);
+  process.exit(1);
+});
diff --git a/docs/src/components/Search.astro b/docs/src/components/Search.astro
index cac07914b..5bcbe4276 100644
--- a/docs/src/components/Search.astro
+++ b/docs/src/components/Search.astro
@@ -36,6 +36,17 @@ const base = import.meta.env.BASE_URL;
         />
         <kbd class="text-xs border border-surface-300 dark:border-surface-600 rounded px-1.5 py-0.5 text-surface-400 cursor-pointer" id="search-close-kbd">Esc</kbd>
       </div>
+      <!-- Relevance ranking toggle -->
+      <div class="flex items-center gap-2 px-4 py-1.5 border-b border-surface-100 dark:border-surface-800">
+        <label class="flex items-center gap-1.5 cursor-pointer select-none text-xs text-surface-500 dark:text-surface-400 hover:text-surface-700 dark:hover:text-surface-300 transition-colors">
+          <input
+            id="relevance-toggle"
+            type="checkbox"
+            class="w-3.5 h-3.5 rounded border-surface-300 dark:border-surface-600 text-squad-600 focus:ring-squad-500 focus:ring-offset-0"
+          />
+          <span>✨ Relevance ranking</span>
+        </label>
+      </div>
       <div id="search-status" class="hidden px-4 py-2 text-xs text-surface-500 dark:text-surface-400 border-b border-surface-100 dark:border-surface-800"></div>
       <div id="search-results" class="max-h-[60vh] overflow-y-auto p-2">
         <div class="p-8 text-center text-surface-400 text-sm" id="search-empty">
@@ -50,7 +61,121 @@ const base = import.meta.env.BASE_URL;
 <script define:vars={{ base }}>
   let pagefind = null;
 
-  // Detect OS and update shortcut badge
+  // --- TF-IDF relevance ranking engine ---
+  let tfidfIndex = null;
+  let tfidfLoading = false;
+
+  function tokenize(text) {
+    return text
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, ' ')
+      .split(/\s+/)
+      .filter(t => t.length > 1);
+  }
+
+  function computeTF(tokens) {
+    const tf = {};
+    for (const t of tokens) {
+      tf[t] = (tf[t] || 0) + 1;
+    }
+    const len = tokens.length || 1;
+    for (const t in tf) tf[t] /= len;
+    return tf;
+  }
+
+  function computeIDF(docs) {
+    const df = {};
+    const N = docs.length;
+    for (const doc of docs) {
+      const seen = new Set(doc.tokens);
+      for (const t of seen) {
+        df[t] = (df[t] || 0) + 1;
+      }
+    }
+    const idf = {};
+    for (const t in df) {
+      idf[t] = Math.log((N + 1) / (df[t] + 1)) + 1;
+    }
+    return idf;
+  }
+
+  function cosineSimilarity(queryTF, docTF, idf) {
+    let dot = 0, qMag = 0, dMag = 0;
+    const allTerms = new Set([...Object.keys(queryTF), ...Object.keys(docTF)]);
+    for (const t of allTerms) {
+      const qVal = (queryTF[t] || 0) * (idf[t] || 1);
+      const dVal = (docTF[t] || 0) * (idf[t] || 1);
+      dot += qVal * dVal;
+      qMag += qVal * qVal;
+      dMag += dVal * dVal;
+    }
+    if (qMag === 0 || dMag === 0) return 0;
+    return dot / (Math.sqrt(qMag) * Math.sqrt(dMag));
+  }
+
+  async function loadTfidfIndex() {
+    if (tfidfIndex) return tfidfIndex;
+    if (tfidfLoading) return null;
+    tfidfLoading = true;
+    try {
+      const resp = await fetch(`${base}search-index.json`);
+      const data = await resp.json();
+      const docs = data.map(d => ({
+        ...d,
+        tokens: tokenize(d.text + ' ' + d.title + ' ' + d.heading),
+      }));
+      const idf = computeIDF(docs);
+      for (const doc of docs) {
+        doc.tf = computeTF(doc.tokens);
+      }
+      tfidfIndex = { docs, idf };
+      return tfidfIndex;
+    } catch (err) {
+      console.error('Failed to load TF-IDF index:', err);
+      return null;
+    } finally {
+      tfidfLoading = false;
+    }
+  }
+
+  function scoreTfidf(query, index) {
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0) return new Map();
+
+    const queryTF = computeTF(queryTokens);
+    const scoreMap = new Map();
+    const lowerQuery = query.toLowerCase();
+
+    for (const doc of index.docs) {
+      let score = cosineSimilarity(queryTF, doc.tf, index.idf);
+
+      // Boost: exact phrase match
+      if (doc.text.toLowerCase().includes(lowerQuery)) score += 0.3;
+      if (doc.title.toLowerCase().includes(lowerQuery)) score += 0.2;
+      if (doc.heading.toLowerCase().includes(lowerQuery)) score += 0.15;
+
+      // Boost individual query term matches in title/heading
+      const titleLower = doc.title.toLowerCase();
+      const headingLower = doc.heading.toLowerCase();
+      for (const term of queryTokens) {
+        if (titleLower.includes(term)) score *= 1.3;
+        if (headingLower.includes(term)) score *= 1.15;
+      }
+
+      if (score > 0.01) {
+        scoreMap.set(doc.slug, score);
+      }
+    }
+    return scoreMap;
+  }
+
+  // Extract slug from a Pagefind result URL (e.g. "/squad/docs/guide/foo/" → "guide/foo")
+  function extractSlugFromUrl(url) {
+    const match = url.match(/\/docs\/(.+?)\/?$/);
+    return match ? match[1] : '';
+  }
+
+  // --- Detect OS and update shortcut badge ---
   const isMac = /Mac|iPhone|iPad|iPod/.test(navigator.platform);
   const modifierEl = document.getElementById('search-modifier');
   if (modifierEl) {
@@ -60,7 +185,7 @@ const base = import.meta.env.BASE_URL;
   async function loadPagefind() {
     if (pagefind) return pagefind;
     pagefind = await import(`${base}pagefind/pagefind.js`);
-    await pagefind.init();
+    await pagefind.init({ basePath: `${base}pagefind/` });
     return pagefind;
   }
 
@@ -72,6 +197,21 @@ const base = import.meta.env.BASE_URL;
   const searchEmpty = document.getElementById('search-empty');
   const searchCloseKbd = document.getElementById('search-close-kbd');
   const searchStatus = document.getElementById('search-status');
+  const relevanceToggle = document.getElementById('relevance-toggle');
+
+  // Persist toggle state in localStorage
+  const RELEVANCE_KEY = 'squad-search-relevance';
+  if (relevanceToggle) {
+    relevanceToggle.checked = localStorage.getItem(RELEVANCE_KEY) === 'true';
+    relevanceToggle.addEventListener('change', () => {
+      localStorage.setItem(RELEVANCE_KEY, relevanceToggle.checked);
+      // Re-run search with new setting if there's a query
+      if (searchInput?.value?.trim()) {
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => performSearch(), 100);
+      }
+    });
+  }
 
   // Section badge color mapping
   const SECTION_COLORS = {
@@ -95,6 +235,8 @@ const base = import.meta.env.BASE_URL;
     searchModal?.classList.remove('hidden');
     searchInput?.focus();
     document.body.style.overflow = 'hidden';
+    // Pre-load TF-IDF index if relevance is enabled
+    if (relevanceToggle?.checked) loadTfidfIndex();
   }
 
   function closeSearch() {
@@ -113,8 +255,6 @@ const base = import.meta.env.BASE_URL;
   searchBackdrop?.addEventListener('click', closeSearch);
   searchCloseKbd?.addEventListener('click', closeSearch);
 
-
-
   document.addEventListener('keydown', (e) => {
     if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
       e.preventDefault();
@@ -148,12 +288,33 @@ const base = import.meta.env.BASE_URL;
     try {
       const pf = await loadPagefind();
       const search = await pf.search(query);
-      const results = await Promise.all(search.results.slice(0, 8).map(r => r.data()));
+      const useRelevance = relevanceToggle?.checked;
+
+      // Fetch more results when re-ranking so we have a larger pool to sort
+      const fetchCount = useRelevance ? Math.min(search.results.length, 20) : Math.min(search.results.length, 8);
+      const results = await Promise.all(search.results.slice(0, fetchCount).map(r => r.data()));
+
+      // Re-rank with TF-IDF if relevance toggle is on
+      if (useRelevance) {
+        const index = await loadTfidfIndex();
+        if (index) {
+          const scores = scoreTfidf(query, index);
+          results.sort((a, b) => {
+            const slugA = extractSlugFromUrl(a.url);
+            const slugB = extractSlugFromUrl(b.url);
+            const scoreA = scores.get(slugA) || 0;
+            const scoreB = scores.get(slugB) || 0;
+            return scoreB - scoreA;
+          });
+        }
+      }
+
+      const displayResults = results.slice(0, 8);
 
       if (!searchResults) return;
       searchResults.innerHTML = '';
 
-      if (results.length === 0) {
+      if (displayResults.length === 0) {
         const noResults = document.createElement('div');
         noResults.className = 'p-8 text-center text-surface-400 text-sm';
         noResults.textContent = `No results for "${query}"`;
@@ -164,12 +325,13 @@ const base = import.meta.env.BASE_URL;
 
       // Update status bar
       if (searchStatus) {
-        searchStatus.textContent = `${search.results.length} result${search.results.length === 1 ? '' : 's'}`;
+        const mode = useRelevance ? ' — ranked by relevance' : '';
+        searchStatus.textContent = `${search.results.length} result${search.results.length === 1 ? '' : 's'}${mode}`;
         searchStatus.classList.remove('hidden');
       }
 
       // Render results with section badges
-      results.forEach((result) => {
+      displayResults.forEach((result) => {
         const section = result.meta?.section || '';
         const a = document.createElement('a');
         a.href = result.url;
@@ -179,7 +341,7 @@ const base = import.meta.env.BASE_URL;
             <span class="font-medium text-base text-surface-900 dark:text-white group-hover:text-squad-600 dark:group-hover:text-squad-400 transition-colors">${result.meta?.title || 'Untitled'}</span>
             ${getSectionBadge(section)}
           </div>
-          <div class="text-sm text-surface-500 dark:text-surface-400 mt-0.5 line-clamp-2">${result.excerpt || ''}</div>
+          <div class="text-sm text-surface-500 dark:text-surface-400 mt-0.5 line-clamp-2">${useRelevance ? (result.excerpt || '').replace(/<\/?mark[^>]*>/gi, '') : (result.excerpt || '')}</div>
         `;
         a.addEventListener('click', closeSearch);
         searchResults.appendChild(a);
diff --git a/docs/src/styles/global.css b/docs/src/styles/global.css
index 40bb14dae..842fc6d48 100644
--- a/docs/src/styles/global.css
+++ b/docs/src/styles/global.css
@@ -231,7 +231,7 @@ html.dark .astro-code span {
   background-color: var(--shiki-dark-bg) !important;
 }
 
-/* Pagefind search result highlights */
+/* Pagefind in-page highlights (after navigating to a result) */
 mark[data-pagefind-highlight] {
   @apply bg-squad-200 dark:bg-squad-800 text-surface-900 dark:text-white rounded-sm px-0.5;
 }
diff --git a/docs/tests/search.spec.mjs b/docs/tests/search.spec.mjs
index 93109efa7..36caff77d 100644
--- a/docs/tests/search.spec.mjs
+++ b/docs/tests/search.spec.mjs
@@ -1,6 +1,6 @@
 /**
  * Playwright e2e tests for Phase 1 search improvements.
- * Tests run against the live preview at http://localhost:4321/squad/
+ * The Playwright config starts a build+preview server on port 4322 automatically.
  * Run with: npx playwright test
  */
 import { test, expect } from '@playwright/test';
diff --git a/test/docs-search.test.ts b/test/docs-search.test.ts
new file mode 100644
index 000000000..113dd4ca1
--- /dev/null
+++ b/test/docs-search.test.ts
@@ -0,0 +1,218 @@
+/**
+ * TDD tests for docs semantic search MVP (issue #40).
+ *
+ * These tests define the expected contract for the search-index.json
+ * that EECOM's build script will generate. They validate schema,
+ * coverage, relevance scoring, and data quality.
+ *
+ * RED PHASE — tests will fail until the search index generator is built.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DOCS_DIR = join(process.cwd(), 'docs');
+const DIST_DIR = join(DOCS_DIR, 'dist');
+const SEARCH_INDEX_PATH = join(DIST_DIR, 'search-index.json');
+
+interface SearchChunk {
+  title: string;
+  slug: string;
+  section: string;
+  heading: string;
+  text: string;
+}
+
+function loadSearchIndex(): SearchChunk[] {
+  if (!existsSync(SEARCH_INDEX_PATH)) {
+    return [];
+  }
+  return JSON.parse(readFileSync(SEARCH_INDEX_PATH, 'utf-8'));
+}
+
+/**
+ * Simple TF-IDF scoring for search relevance testing.
+ * Includes title/heading boost to match the production scoring in SemanticSearch.astro.
+ * Returns chunks sorted by descending relevance to the query.
+ */
+function tfidfSearch(chunks: SearchChunk[], query: string): SearchChunk[] {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const N = chunks.length;
+
+  // Document frequency: how many chunks contain each term
+  const df = new Map<string, number>();
+  for (const term of terms) {
+    let count = 0;
+    for (const chunk of chunks) {
+      const text = `${chunk.title} ${chunk.heading || ''} ${chunk.text}`.toLowerCase();
+      if (text.includes(term)) count++;
+    }
+    df.set(term, count);
+  }
+
+  // Score each chunk
+  const scored = chunks.map(chunk => {
+    const text = `${chunk.title} ${chunk.heading || ''} ${chunk.text}`.toLowerCase();
+    const words = text.split(/\s+/);
+    let score = 0;
+
+    for (const term of terms) {
+      // Term frequency
+      const tf = words.filter(w => w.includes(term)).length / (words.length || 1);
+      // Inverse document frequency
+      const idf = Math.log(N / (1 + (df.get(term) ?? 0)));
+      score += tf * idf;
+    }
+
+    // Title/heading boost: individual query terms appearing in title/heading
+    const titleLower = chunk.title.toLowerCase();
+    const headingLower = (chunk.heading || '').toLowerCase();
+    for (const term of terms) {
+      if (titleLower.includes(term)) score *= 1.3;
+      if (headingLower.includes(term)) score *= 1.15;
+    }
+
+    return { chunk, score };
+  });
+
+  return scored
+    .sort((a, b) => b.score - a.score)
+    .map(s => s.chunk);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+const indexAvailable = existsSync(SEARCH_INDEX_PATH);
+
+describe.skipIf(!indexAvailable)('Docs Search Index — search-index.json', () => {
+
+  it('has correct schema: array of {title, slug, section, text}', () => {
+    const index = loadSearchIndex();
+
+    expect(Array.isArray(index)).toBe(true);
+    expect(index.length).toBeGreaterThan(0);
+
+    for (const chunk of index) {
+      expect(chunk).toHaveProperty('title');
+      expect(chunk).toHaveProperty('slug');
+      expect(chunk).toHaveProperty('section');
+      expect(chunk).toHaveProperty('text');
+
+      expect(typeof chunk.title).toBe('string');
+      expect(typeof chunk.slug).toBe('string');
+      expect(typeof chunk.section).toBe('string');
+      expect(typeof chunk.text).toBe('string');
+    }
+  });
+});
+
+describe.skipIf(!indexAvailable)('Docs Search Index — chunk coverage', () => {
+  // Pages listed in navigation.ts that are generated at build time
+  // and don't have corresponding .md source files
+  const KNOWN_GENERATED_PAGES = new Set([
+    'reference/api',
+  ]);
+
+  it('every page in navigation.ts has at least one chunk in the index', async () => {
+    const { NAV_SECTIONS, STANDALONE_PAGES } = await import(
+      '../docs/src/navigation.ts'
+    );
+    const index = loadSearchIndex();
+    const indexedSlugs = new Set(index.map((c: SearchChunk) => c.slug));
+
+    // Collect all slugs from navigation
+    const navSlugs: string[] = [];
+    for (const section of NAV_SECTIONS) {
+      for (const item of section.items) {
+        navSlugs.push(item.slug);
+      }
+    }
+    for (const page of STANDALONE_PAGES) {
+      navSlugs.push(page.slug);
+    }
+
+    const missingSlugs: string[] = [];
+    for (const slug of navSlugs) {
+      if (KNOWN_GENERATED_PAGES.has(slug)) continue;
+      if (!indexedSlugs.has(slug)) {
+        missingSlugs.push(slug);
+      }
+    }
+
+    expect(
+      missingSlugs,
+      `Pages missing from search index:\n  ${missingSlugs.join('\n  ')}`
+    ).toEqual([]);
+  });
+});
+
+describe.skipIf(!indexAvailable)('Docs Search Index — search relevance', () => {
+  it('query "persistent model preferences" returns the model-selection page as top result', () => {
+    const index = loadSearchIndex();
+    const results = tfidfSearch(index, 'persistent model preferences');
+
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].slug).toContain('model-selection');
+  });
+
+  it('query "parallel execution" returns parallel-execution page first', () => {
+    const index = loadSearchIndex();
+    const results = tfidfSearch(index, 'parallel execution');
+
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].slug).toContain('parallel-execution');
+  });
+
+  it('query "install" returns installation page in top 3', () => {
+    const index = loadSearchIndex();
+    const results = tfidfSearch(index, 'install');
+    const top3Slugs = results.slice(0, 3).map(r => r.slug);
+
+    expect(
+      top3Slugs.some(s => s.includes('installation')),
+      `Expected "installation" in top 3 results, got: ${top3Slugs.join(', ')}`
+    ).toBe(true);
+  });
+});
+
+describe.skipIf(!indexAvailable)('Docs Search Index — data quality', () => {
+  it('no chunk has an empty text field', () => {
+    const index = loadSearchIndex();
+    const emptyChunks = index.filter(
+      (c: SearchChunk) => !c.text || c.text.trim().length === 0
+    );
+
+    expect(
+      emptyChunks,
+      `Found ${emptyChunks.length} chunks with empty text:\n` +
+      emptyChunks.map((c: SearchChunk) => `  ${c.slug} — "${c.title}"`).join('\n')
+    ).toEqual([]);
+  });
+
+  it('no chunk has an empty title field', () => {
+    const index = loadSearchIndex();
+    const emptyTitles = index.filter(
+      (c: SearchChunk) => !c.title || c.title.trim().length === 0
+    );
+
+    expect(
+      emptyTitles,
+      `Found ${emptyTitles.length} chunks with empty title`
+    ).toEqual([]);
+  });
+
+  it('no chunk has an empty slug field', () => {
+    const index = loadSearchIndex();
+    const emptySlugs = index.filter(
+      (c: SearchChunk) => !c.slug || c.slug.trim().length === 0
+    );
+
+    expect(
+      emptySlugs,
+      `Found ${emptySlugs.length} chunks with empty slug`
+    ).toEqual([]);
+  });
+});