diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index ab9860bd3..cdc2b79dd 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -1,6 +1,7 @@
 import { defineConfig } from 'astro/config';
 import tailwindcss from '@tailwindcss/vite';
 import { remarkRewriteLinks } from './src/plugins/remark-rewrite-links.mjs';
+import { rehypePagefindAttrs } from './src/plugins/rehype-pagefind-attrs.mjs';
 
 export default defineConfig({
   site: 'https://bradygaster.github.io',
@@ -10,6 +11,7 @@ export default defineConfig({
   },
   markdown: {
     remarkPlugins: [remarkRewriteLinks],
+    rehypePlugins: [rehypePagefindAttrs],
     shikiConfig: {
       themes: {
         light: 'github-light',
diff --git a/docs/package.json b/docs/package.json
index 51b4d5702..c0e858c85 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -7,7 +7,10 @@
     "dev": "astro dev",
     "build": "astro build && npx pagefind --site dist",
     "preview": "astro preview",
-    "astro": "astro"
+    "astro": "astro",
+    "test": "node --test tests/build-output.test.mjs && npx playwright test",
+    "test:build": "node --test tests/build-output.test.mjs",
+    "test:e2e": "npx playwright test"
   },
   "dependencies": {
     "@tailwindcss/vite": "^4.1.0",
diff --git a/docs/pagefind.yml b/docs/pagefind.yml
new file mode 100644
index 000000000..282352e74
--- /dev/null
+++ b/docs/pagefind.yml
@@ -0,0 +1,12 @@
+# Pagefind configuration for Squad docs
+# See: https://pagefind.app/docs/config-options/
+
+# Exclude navigation, footers, and code blocks from indexing
+exclude_selectors:
+  - "nav"
+  - "footer"
+  - "aside"
+  - "pre"
+  - ".astro-code"
+
+
diff --git a/docs/playwright.config.mjs b/docs/playwright.config.mjs
new file mode 100644
index 000000000..2c69a1ac9
--- /dev/null
+++ b/docs/playwright.config.mjs
@@ -0,0 +1,13 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.mjs',
+  timeout: 30_000,
+  retries: 0,
+  use: {
+    baseURL: 'http://localhost:4321/squad/',
+    browserName: 'chromium',
+    headless: true,
+  },
+});
diff --git a/docs/screenshots/before-search-agent.png b/docs/screenshots/before-search-agent.png
new file mode 100644
index 000000000..b7832127e
Binary files /dev/null and b/docs/screenshots/before-search-agent.png differ
diff --git a/docs/screenshots/before-search-ceremony.png b/docs/screenshots/before-search-ceremony.png
new file mode 100644
index 000000000..dc20655a0
Binary files /dev/null and b/docs/screenshots/before-search-ceremony.png differ
diff --git a/docs/screenshots/before-search-install.png b/docs/screenshots/before-search-install.png
new file mode 100644
index 000000000..9fe563b35
Binary files /dev/null and b/docs/screenshots/before-search-install.png differ
diff --git a/docs/screenshots/search-agent.png b/docs/screenshots/search-agent.png
new file mode 100644
index 000000000..73d9897b1
Binary files /dev/null and b/docs/screenshots/search-agent.png differ
diff --git a/docs/screenshots/search-ceremony.png b/docs/screenshots/search-ceremony.png
new file mode 100644
index 000000000..7939af7e9
Binary files /dev/null and b/docs/screenshots/search-ceremony.png differ
diff --git a/docs/screenshots/search-install.png b/docs/screenshots/search-install.png
new file mode 100644
index 000000000..656e20bd7
Binary files /dev/null and b/docs/screenshots/search-install.png differ
diff --git a/docs/src/components/Footer.astro b/docs/src/components/Footer.astro
index f44ae621e..e7ffa8e88 100644
--- a/docs/src/components/Footer.astro
+++ b/docs/src/components/Footer.astro
@@ -4,7 +4,7 @@ import squadLogo from '../assets/images/squad-logo.png';
 const base = import.meta.env.BASE_URL;
 ---
 
-<footer class="border-t border-surface-200 dark:border-surface-800 mt-16">
+<footer class="border-t border-surface-200 dark:border-surface-800 mt-16" data-pagefind-ignore>
   <div class="max-w-7xl mx-auto px-4 py-8 sm:px-6 lg:px-8">
     <div class="grid grid-cols-1 md:grid-cols-4 gap-8">
       <div>
diff --git a/docs/src/components/Header.astro b/docs/src/components/Header.astro
index c553ea458..a50e168a9 100644
--- a/docs/src/components/Header.astro
+++ b/docs/src/components/Header.astro
@@ -46,7 +46,7 @@ const mobileNavBase = "block px-3 py-2 rounded-md text-base transition-colors";
     </a>
 
     <!-- Top nav links (desktop) -->
-    <nav class="hidden md:flex items-center gap-1 text-base">
+    <nav class="hidden md:flex items-center gap-1 text-base" data-pagefind-ignore>
       <a href={`${base}docs/get-started/installation/`} class:list={[navBase, isDocsActive ? navActive : navInactive]}>Docs</a>
       <a href={`${base}blog/`} class:list={[navBase, isBlogActive ? navActive : navInactive]}>Blog</a>
       <a href="https://github.com/bradygaster/squad" class:list={[navBase, navInactive]} target="_blank" rel="noopener">GitHub</a>
@@ -71,7 +71,7 @@ const mobileNavBase = "block px-3 py-2 rounded-md text-base transition-colors";
   </div>
 
   <!-- Mobile nav dropdown -->
-  <nav id="mobile-nav" class="hidden md:hidden border-t border-surface-200 dark:border-surface-800 bg-white dark:bg-surface-950">
+  <nav id="mobile-nav" class="hidden md:hidden border-t border-surface-200 dark:border-surface-800 bg-white dark:bg-surface-950" data-pagefind-ignore>
     <div class="px-4 py-3 space-y-1">
       <a href={`${base}docs/get-started/installation/`} class:list={[mobileNavBase, isDocsActive ? navActive : navInactive]}>Docs</a>
       <a href={`${base}blog/`} class:list={[mobileNavBase, isBlogActive ? navActive : navInactive]}>Blog</a>
diff --git a/docs/src/components/Search.astro b/docs/src/components/Search.astro
index f756cc81e..cac07914b 100644
--- a/docs/src/components/Search.astro
+++ b/docs/src/components/Search.astro
@@ -36,11 +36,13 @@ 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>
+      <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">
           Start typing to search…
         </div>
       </div>
+
     </div>
   </div>
 </div>
@@ -69,6 +71,25 @@ const base = import.meta.env.BASE_URL;
   const searchResults = document.getElementById('search-results');
   const searchEmpty = document.getElementById('search-empty');
   const searchCloseKbd = document.getElementById('search-close-kbd');
+  const searchStatus = document.getElementById('search-status');
+
+  // Section badge color mapping
+  const SECTION_COLORS = {
+    'Get Started': 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400',
+    'Guide': 'bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-400',
+    'Features': 'bg-purple-100 text-purple-800 dark:bg-purple-900/30 dark:text-purple-400',
+    'Reference': 'bg-amber-100 text-amber-800 dark:bg-amber-900/30 dark:text-amber-400',
+    'Scenarios': 'bg-cyan-100 text-cyan-800 dark:bg-cyan-900/30 dark:text-cyan-400',
+    'Concepts': 'bg-rose-100 text-rose-800 dark:bg-rose-900/30 dark:text-rose-400',
+    'Cookbook': 'bg-orange-100 text-orange-800 dark:bg-orange-900/30 dark:text-orange-400',
+    'Blog': 'bg-pink-100 text-pink-800 dark:bg-pink-900/30 dark:text-pink-400',
+  };
+
+  function getSectionBadge(section) {
+    if (!section) return '';
+    const colors = SECTION_COLORS[section] || 'bg-surface-100 text-surface-700 dark:bg-surface-800 dark:text-surface-300';
+    return `<span class="inline-flex items-center px-1.5 py-0.5 rounded text-xs font-medium ${colors}">${section}</span>`;
+  }
 
   function openSearch() {
     searchModal?.classList.remove('hidden');
@@ -84,6 +105,7 @@ const base = import.meta.env.BASE_URL;
       searchResults?.appendChild(searchEmpty);
       searchEmpty.textContent = 'Start typing to search…';
     }
+    searchStatus?.classList.add('hidden');
     document.body.style.overflow = '';
   }
 
@@ -91,6 +113,8 @@ 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();
@@ -117,6 +141,7 @@ const base = import.meta.env.BASE_URL;
         searchEmpty.textContent = 'Start typing to search…';
         searchResults.appendChild(searchEmpty);
       }
+      searchStatus?.classList.add('hidden');
       return;
     }
 
@@ -133,15 +158,27 @@ const base = import.meta.env.BASE_URL;
         noResults.className = 'p-8 text-center text-surface-400 text-sm';
         noResults.textContent = `No results for "${query}"`;
         searchResults.appendChild(noResults);
+        searchStatus?.classList.add('hidden');
         return;
       }
 
+      // Update status bar
+      if (searchStatus) {
+        searchStatus.textContent = `${search.results.length} result${search.results.length === 1 ? '' : 's'}`;
+        searchStatus.classList.remove('hidden');
+      }
+
+      // Render results with section badges
       results.forEach((result) => {
+        const section = result.meta?.section || '';
         const a = document.createElement('a');
         a.href = result.url;
         a.className = 'block px-3 py-2.5 rounded-lg hover:bg-surface-100 dark:hover:bg-surface-800 transition-colors group';
         a.innerHTML = `
-          <div 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'}</div>
+          <div class="flex items-center gap-2">
+            <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>
         `;
         a.addEventListener('click', closeSearch);
diff --git a/docs/src/components/Sidebar.astro b/docs/src/components/Sidebar.astro
index 7b5ccc392..a631d562c 100644
--- a/docs/src/components/Sidebar.astro
+++ b/docs/src/components/Sidebar.astro
@@ -12,6 +12,7 @@ const base = import.meta.env.BASE_URL;
 <aside
   id="sidebar"
   class="fixed inset-y-0 left-0 z-50 w-72 bg-white dark:bg-surface-950 border-r border-surface-200 dark:border-surface-800 transform -translate-x-full lg:translate-x-0 lg:static lg:z-auto transition-transform duration-200 ease-in-out overflow-y-auto pt-14 lg:pt-0 lg:h-[calc(100vh-3.5rem)] lg:sticky lg:top-14 lg:shrink-0"
+  data-pagefind-ignore
 >
   <div class="p-4 space-y-6">
     {NAV_SECTIONS.map((section) => (
diff --git a/docs/src/layouts/DocsLayout.astro b/docs/src/layouts/DocsLayout.astro
index 63cf0d150..6d1ee85c1 100644
--- a/docs/src/layouts/DocsLayout.astro
+++ b/docs/src/layouts/DocsLayout.astro
@@ -3,6 +3,7 @@ import BaseLayout from './BaseLayout.astro';
 import Header from '../components/Header.astro';
 import Sidebar from '../components/Sidebar.astro';
 import Footer from '../components/Footer.astro';
+import { NAV_SECTIONS } from '../navigation';
 
 interface Props {
   title: string;
@@ -11,6 +12,11 @@ interface Props {
 }
 
 const { title, description, currentSlug } = Astro.props;
+
+// Derive section name from the URL path for Pagefind metadata
+const sectionDir = currentSlug?.split('/')[0] || '';
+const navSection = NAV_SECTIONS.find(s => s.dir === sectionDir);
+const section = navSection?.title || 'Docs';
 ---
 
 <BaseLayout title={title} description={description}>
@@ -19,7 +25,7 @@ const { title, description, currentSlug } = Astro.props;
     <Sidebar currentSlug={currentSlug} />
     <main class="flex-1 min-w-0">
       <div class="max-w-4xl mx-auto px-4 py-8 sm:px-6 lg:px-8">
-        <article class="prose" data-pagefind-body>
+        <article class="prose" data-pagefind-body data-pagefind-meta={`section:${section}`}>
           <slot />
         </article>
       </div>
diff --git a/docs/src/pages/blog/[...slug].astro b/docs/src/pages/blog/[...slug].astro
index 4a2b8ae9e..ecf22fa86 100644
--- a/docs/src/pages/blog/[...slug].astro
+++ b/docs/src/pages/blog/[...slug].astro
@@ -36,7 +36,7 @@ const title = entry.data.title || extractTitle(entry.id);
       </svg>
       Back to Blog
     </a>
-    <article class="prose" data-pagefind-body>
+    <article class="prose" data-pagefind-body data-pagefind-meta="section:Blog">
       <Content />
     </article>
   </main>
diff --git a/docs/src/plugins/rehype-pagefind-attrs.mjs b/docs/src/plugins/rehype-pagefind-attrs.mjs
new file mode 100644
index 000000000..cbd09914b
--- /dev/null
+++ b/docs/src/plugins/rehype-pagefind-attrs.mjs
@@ -0,0 +1,21 @@
+import { visit } from 'unist-util-visit';
+
+/**
+ * Rehype plugin that adds Pagefind attributes to rendered markdown HTML.
+ * - Adds data-pagefind-weight="2" to h2 and h3 for search ranking boost
+ * - Adds data-pagefind-ignore to pre elements to exclude code blocks
+ */
+export function rehypePagefindAttrs() {
+  return (tree) => {
+    visit(tree, 'element', (node) => {
+      if (node.tagName === 'h2' || node.tagName === 'h3') {
+        node.properties = node.properties || {};
+        node.properties.dataPagefindWeight = '2';
+      }
+      if (node.tagName === 'pre') {
+        node.properties = node.properties || {};
+        node.properties.dataPagefindIgnore = '';
+      }
+    });
+  };
+}
diff --git a/docs/tests/build-output.test.mjs b/docs/tests/build-output.test.mjs
new file mode 100644
index 000000000..029587ee4
--- /dev/null
+++ b/docs/tests/build-output.test.mjs
@@ -0,0 +1,231 @@
+/**
+ * Build output tests for Phase 1 search improvements.
+ * Validates that pagefind attributes are correctly applied in the built HTML.
+ * Run with: node --test tests/build-output.test.mjs
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DOCS_ROOT = path.resolve(import.meta.dirname, '..');
+const DIST = path.join(DOCS_ROOT, 'dist');
+
+// Collect HTML files from dist for reuse across tests
+function findHtmlFiles(dir, files = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory() && entry.name !== '_astro' && entry.name !== 'pagefind') {
+      findHtmlFiles(full, files);
+    } else if (entry.isFile() && entry.name.endsWith('.html')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+const allHtmlFiles = findHtmlFiles(DIST);
+
+// Exclude top-level pages (404, home, blog index) which use different layouts
+const EXCLUDED_PAGES = ['404.html', `blog${path.sep}index.html`, 'index.html'];
+function isContentPage(file) {
+  const rel = path.relative(DIST, file);
+  return !EXCLUDED_PAGES.some(exc => rel === exc || rel === exc.replace(/\//g, path.sep));
+}
+
+const docsHtmlFiles = allHtmlFiles.filter(f =>
+  f.includes(`${path.sep}docs${path.sep}`) && isContentPage(f)
+);
+const blogHtmlFiles = allHtmlFiles.filter(f =>
+  f.includes(`${path.sep}blog${path.sep}`) && isContentPage(f)
+);
+
+// ── pagefind.yml ──────────────────────────────────────────────────────────────
+
+describe('pagefind.yml configuration', () => {
+  it('exists in the docs root', () => {
+    assert.ok(
+      fs.existsSync(path.join(DOCS_ROOT, 'pagefind.yml')),
+      'pagefind.yml should exist at docs root'
+    );
+  });
+
+  it('contains exclude_selectors for nav, footer, aside, pre, .astro-code', () => {
+    const content = fs.readFileSync(path.join(DOCS_ROOT, 'pagefind.yml'), 'utf-8');
+    for (const selector of ['nav', 'footer', 'aside', 'pre', '.astro-code']) {
+      assert.ok(
+        content.includes(`"${selector}"`) || content.includes(`'${selector}'`) || content.includes(`- ${selector}`) || content.includes(`- "${selector}"`),
+        `pagefind.yml should exclude selector: ${selector}`
+      );
+    }
+  });
+});
+
+// ── Pagefind index output ─────────────────────────────────────────────────────
+
+describe('pagefind build output', () => {
+  it('pagefind directory exists in dist/', () => {
+    assert.ok(
+      fs.existsSync(path.join(DIST, 'pagefind')),
+      'dist/pagefind/ directory should exist after build'
+    );
+  });
+
+  it('pagefind.js is present in pagefind directory', () => {
+    assert.ok(
+      fs.existsSync(path.join(DIST, 'pagefind', 'pagefind.js')),
+      'dist/pagefind/pagefind.js should exist'
+    );
+  });
+});
+
+// ── data-pagefind-body on article elements ────────────────────────────────────
+
+describe('data-pagefind-body attribute', () => {
+  it('docs pages contain data-pagefind-body on article elements', () => {
+    assert.ok(docsHtmlFiles.length > 0, 'Should have docs HTML files to test');
+    const missing = [];
+    for (const file of docsHtmlFiles) {
+      const html = fs.readFileSync(file, 'utf-8');
+      if (!html.includes('data-pagefind-body')) {
+        missing.push(path.relative(DIST, file));
+      }
+    }
+    assert.equal(missing.length, 0, `These docs pages lack data-pagefind-body: ${missing.join(', ')}`);
+  });
+
+  it('blog post pages contain data-pagefind-body on article elements', () => {
+    assert.ok(blogHtmlFiles.length > 0, 'Should have blog HTML files to test');
+    for (const file of blogHtmlFiles) {
+      const html = fs.readFileSync(file, 'utf-8');
+      assert.ok(
+        html.includes('data-pagefind-body'),
+        `Blog page missing data-pagefind-body: ${path.relative(DIST, file)}`
+      );
+    }
+  });
+});
+
+// ── data-pagefind-meta with section values ────────────────────────────────────
+
+describe('data-pagefind-meta section attribute', () => {
+  it('docs pages have data-pagefind-meta with a section value', () => {
+    assert.ok(docsHtmlFiles.length > 0, 'Should have docs HTML files to test');
+    const sectionPattern = /data-pagefind-meta="section:([^"]+)"/;
+    const missing = [];
+    for (const file of docsHtmlFiles) {
+      const html = fs.readFileSync(file, 'utf-8');
+      if (!sectionPattern.test(html)) {
+        missing.push(path.relative(DIST, file));
+      }
+    }
+    assert.equal(
+      missing.length, 0,
+      `These docs pages lack data-pagefind-meta section: ${missing.join(', ')}`
+    );
+  });
+
+  it('section values match expected categories', () => {
+    const knownSections = new Set([
+      'Get Started', 'Guide', 'Features', 'Reference',
+      'Scenarios', 'Concepts', 'Cookbook', 'Blog', 'Docs', 'Community'
+    ]);
+    const sectionPattern = /data-pagefind-meta="section:([^"]+)"/g;
+    const foundSections = new Set();
+    for (const file of [...docsHtmlFiles, ...blogHtmlFiles]) {
+      const html = fs.readFileSync(file, 'utf-8');
+      for (const match of html.matchAll(sectionPattern)) {
+        foundSections.add(match[1]);
+      }
+    }
+    assert.ok(foundSections.size > 0, 'Should find at least one section value');
+    for (const section of foundSections) {
+      assert.ok(
+        knownSections.has(section),
+        `Unexpected section value "${section}" — expected one of: ${[...knownSections].join(', ')}`
+      );
+    }
+  });
+
+  it('blog pages have section:Blog', () => {
+    assert.ok(blogHtmlFiles.length > 0, 'Should have blog HTML files to test');
+    for (const file of blogHtmlFiles) {
+      const html = fs.readFileSync(file, 'utf-8');
+      assert.ok(
+        html.includes('data-pagefind-meta="section:Blog"'),
+        `Blog page missing section:Blog — ${path.relative(DIST, file)}`
+      );
+    }
+  });
+});
+
+// ── data-pagefind-weight on headings ──────────────────────────────────────────
+
+describe('data-pagefind-weight on headings', () => {
+  it('docs pages have data-pagefind-weight="2" on h2 or h3 elements inside article', () => {
+    const weightPattern = /<h[23][^>]*data-pagefind-weight="2"/;
+    // Only check pages that have h2/h3 inside a prose article (standard content pages)
+    const articleHeadingPattern = /data-pagefind-body[\s\S]*?<h[23][\s>]/;
+    const pagesWithArticleHeadings = docsHtmlFiles.filter(f => {
+      const html = fs.readFileSync(f, 'utf-8');
+      return articleHeadingPattern.test(html);
+    });
+    assert.ok(pagesWithArticleHeadings.length > 0, 'Should have docs pages with h2/h3 inside article');
+
+    const missing = [];
+    for (const file of pagesWithArticleHeadings) {
+      const html = fs.readFileSync(file, 'utf-8');
+      if (!weightPattern.test(html)) {
+        missing.push(path.relative(DIST, file));
+      }
+    }
+    assert.equal(
+      missing.length, 0,
+      `These pages with article headings lack data-pagefind-weight="2": ${missing.join(', ')}`
+    );
+  });
+});
+
+// ── data-pagefind-ignore on nav, footer, pre ──────────────────────────────────
+
+describe('data-pagefind-ignore attributes', () => {
+  // Use one representative docs page that has all elements
+  const sampleFile = docsHtmlFiles.find(f => f.includes('built-in-roles'));
+  const sampleHtml = sampleFile ? fs.readFileSync(sampleFile, 'utf-8') : '';
+
+  it('nav elements have data-pagefind-ignore', () => {
+    assert.ok(sampleFile, 'Sample file (built-in-roles) should exist');
+    const navTags = [...sampleHtml.matchAll(/<nav[^>]*>/g)].map(m => m[0]);
+    assert.ok(navTags.length > 0, 'Page should contain nav elements');
+    for (const tag of navTags) {
+      assert.ok(
+        tag.includes('data-pagefind-ignore'),
+        `nav element missing data-pagefind-ignore: ${tag.substring(0, 80)}`
+      );
+    }
+  });
+
+  it('footer elements have data-pagefind-ignore', () => {
+    assert.ok(sampleFile, 'Sample file should exist');
+    const footerTags = [...sampleHtml.matchAll(/<footer[^>]*>/g)].map(m => m[0]);
+    assert.ok(footerTags.length > 0, 'Page should contain footer elements');
+    for (const tag of footerTags) {
+      assert.ok(
+        tag.includes('data-pagefind-ignore'),
+        `footer element missing data-pagefind-ignore: ${tag.substring(0, 80)}`
+      );
+    }
+  });
+
+  it('pre (code block) elements have data-pagefind-ignore', () => {
+    assert.ok(sampleFile, 'Sample file should exist');
+    const preTags = [...sampleHtml.matchAll(/<pre[^>]*>/g)].map(m => m[0]);
+    assert.ok(preTags.length > 0, 'Page should contain pre elements');
+    for (const tag of preTags) {
+      assert.ok(
+        tag.includes('data-pagefind-ignore'),
+        `pre element missing data-pagefind-ignore: ${tag.substring(0, 80)}`
+      );
+    }
+  });
+});
diff --git a/docs/tests/search.spec.mjs b/docs/tests/search.spec.mjs
new file mode 100644
index 000000000..93109efa7
--- /dev/null
+++ b/docs/tests/search.spec.mjs
@@ -0,0 +1,164 @@
+/**
+ * Playwright e2e tests for Phase 1 search improvements.
+ * Tests run against the live preview at http://localhost:4321/squad/
+ * Run with: npx playwright test
+ */
+import { test, expect } from '@playwright/test';
+
+const BASE = '/squad/';
+
+// Helper: open search modal via button click
+async function openSearchViaButton(page) {
+  await page.goto(BASE);
+  const searchBtn = page.locator('#search-btn');
+  await expect(searchBtn).toBeVisible();
+  await searchBtn.click();
+  const modal = page.locator('#search-modal');
+  await expect(modal).not.toHaveClass(/hidden/);
+  return modal;
+}
+
+test.describe('Search modal interactions', () => {
+
+  test('search modal opens when clicking the search button', async ({ page }) => {
+    const modal = await openSearchViaButton(page);
+    await expect(modal).toBeVisible();
+    const input = page.locator('#search-input');
+    await expect(input).toBeFocused();
+  });
+
+  test('search modal opens on Ctrl+K keyboard shortcut', async ({ page }) => {
+    await page.goto(BASE);
+    const modal = page.locator('#search-modal');
+    await expect(modal).toHaveClass(/hidden/);
+
+    await page.keyboard.press('Control+k');
+    await expect(modal).not.toHaveClass(/hidden/);
+    await expect(page.locator('#search-input')).toBeFocused();
+  });
+
+  test('pressing Escape closes the search modal', async ({ page }) => {
+    await openSearchViaButton(page);
+    const modal = page.locator('#search-modal');
+    await expect(modal).not.toHaveClass(/hidden/);
+
+    await page.keyboard.press('Escape');
+    await expect(modal).toHaveClass(/hidden/);
+  });
+
+  test('clicking backdrop closes the search modal', async ({ page }) => {
+    await openSearchViaButton(page);
+    const modal = page.locator('#search-modal');
+    await expect(modal).not.toHaveClass(/hidden/);
+
+    // The dialog container intercepts pointer events over the backdrop center,
+    // so we dispatch a click event directly on the backdrop element
+    await page.evaluate(() => document.getElementById('search-backdrop').click());
+    await expect(modal).toHaveClass(/hidden/);
+  });
+});
+
+test.describe('Search results', () => {
+
+  test('typing a query shows results', async ({ page }) => {
+    await openSearchViaButton(page);
+    const input = page.locator('#search-input');
+    await input.fill('agent');
+
+    // Wait for results to appear (debounce is 200ms + pagefind load)
+    const results = page.locator('#search-results a');
+    await expect(results.first()).toBeVisible({ timeout: 10_000 });
+    const count = await results.count();
+    expect(count).toBeGreaterThan(0);
+  });
+
+  test('results display section badges', async ({ page }) => {
+    await openSearchViaButton(page);
+    await page.locator('#search-input').fill('agent');
+
+    // Wait for results
+    const resultLinks = page.locator('#search-results a');
+    await expect(resultLinks.first()).toBeVisible({ timeout: 10_000 });
+
+    // Look for section badge spans within results
+    const badges = page.locator('#search-results a span.inline-flex');
+    const badgeCount = await badges.count();
+    expect(badgeCount).toBeGreaterThan(0);
+
+    // Verify badge text is a known section
+    const knownSections = [
+      'Get Started', 'Guide', 'Features', 'Reference',
+      'Scenarios', 'Concepts', 'Cookbook', 'Blog', 'Docs', 'Community'
+    ];
+    const firstBadgeText = await badges.first().textContent();
+    expect(knownSections).toContain(firstBadgeText.trim());
+  });
+
+  test('each result has a title and excerpt', async ({ page }) => {
+    await openSearchViaButton(page);
+    await page.locator('#search-input').fill('agent');
+
+    const resultLinks = page.locator('#search-results a');
+    await expect(resultLinks.first()).toBeVisible({ timeout: 10_000 });
+
+    // Check first result has a title (text-base span) and excerpt (text-sm div)
+    const firstResult = resultLinks.first();
+    const title = firstResult.locator('span.text-base');
+    await expect(title).toBeVisible();
+    const titleText = await title.textContent();
+    expect(titleText.trim().length).toBeGreaterThan(0);
+
+    const excerpt = firstResult.locator('div.text-sm');
+    await expect(excerpt).toBeVisible();
+  });
+
+  test('result count text is visible', async ({ page }) => {
+    await openSearchViaButton(page);
+    await page.locator('#search-input').fill('agent');
+
+    // Wait for status bar showing result count
+    const status = page.locator('#search-status');
+    await expect(status).toBeVisible({ timeout: 10_000 });
+
+    const statusText = await status.textContent();
+    // Should match pattern like "5 results" or "1 result"
+    expect(statusText).toMatch(/\d+ results?/);
+  });
+
+  test('clicking a result navigates to that page', async ({ page }) => {
+    await openSearchViaButton(page);
+    await page.locator('#search-input').fill('agent');
+
+    const resultLinks = page.locator('#search-results a');
+    await expect(resultLinks.first()).toBeVisible({ timeout: 10_000 });
+
+    // Get the href of the first result
+    const href = await resultLinks.first().getAttribute('href');
+    expect(href).toBeTruthy();
+
+    // Click it and verify navigation
+    await resultLinks.first().click();
+
+    // Modal should close, and we should navigate to the result page
+    await page.waitForURL(new RegExp(href.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')), { timeout: 10_000 });
+    expect(page.url()).toContain(href);
+  });
+
+  test('no results state shows appropriate message', async ({ page }) => {
+    await openSearchViaButton(page);
+    const input = page.locator('#search-input');
+    // Use a single random character that pagefind won't match
+    await input.fill('ÿ');
+
+    // Wait for search debounce, then check for either "No results" or
+    // the default "Start typing" (pagefind may not index this character).
+    // The search executes and either shows "No results for..." or results.
+    // We verify the search system responds to input.
+    await page.waitForTimeout(1500);
+    const resultsContainer = page.locator('#search-results');
+    const text = await resultsContainer.textContent();
+    // Either we get "No results" or actual results — either way the
+    // search pipeline processed the query (not still on "Start typing")
+    expect(text.trim()).not.toBe('Start typing to search…');
+  });
+});