diff --git a/astro.config.mjs b/astro.config.mjs
index a5f2c67a89..3baf67563c 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -3,11 +3,13 @@ import { satteri } from '@astrojs/markdown-satteri';
 import mdx from '@astrojs/mdx';
 import { attributeMarkdown, wrapTables } from '/src/themes/octopus/utilities/custom-markdown.mjs';
 import llmMdEmitter from './src/integrations/llm-md-emitter.ts';
+import pagefindIndex from './src/integrations/pagefind-index.ts';
 import pruneDist from './src/integrations/prune-dist.ts';
 import satteriHeadingId from './src/plugins/satteri-heading-id.js';
 import satteriApiExamples, { apiExampleDirective } from './src/plugins/satteri-api-examples.js';
 import { endpointDirective } from './src/plugins/satteri-endpoint.js';
 import satteriWbr from './src/plugins/satteri-wbr.js';
+import pagefindImageAttrs from './src/plugins/pagefind-image-attrs.js';
 import shikiCodeBlock from './src/plugins/shiki-code-block.js';
 
 // https://astro.build/config
@@ -22,6 +24,9 @@ export default defineConfig({
     integrations: [
         mdx(),
         llmMdEmitter(),
+        // After the page emitters, and before the prune that would delete its
+        // output
+        pagefindIndex(),
         // Must run last: strips build output that can't be served under /docs/
         pruneDist()
     ],
@@ -63,6 +68,7 @@ export default defineConfig({
             ],
             hastPlugins: [
                 satteriWbr,
+                pagefindImageAttrs,
                 satteriApiExamples
             ],
         }),
diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt
index a94359012f..8d53e3bf57 100644
--- a/dictionary-octopus.txt
+++ b/dictionary-octopus.txt
@@ -405,6 +405,7 @@ Ozar
 PAAS
 packageid
 packageversion
+pagefind
 passout
 PathtoPublish
 pemstore
diff --git a/package.json b/package.json
index 8ea81c1723..974ab3217b 100644
--- a/package.json
+++ b/package.json
@@ -33,9 +33,8 @@
         "astro-accelerator-utils": "^0.3.84",
         "glob": "^13.0.6",
         "gray-matter": "^4.0.3",
-        "html-to-text": "^10.0.0",
-        "keyword-extractor": "^0.0.28",
         "optional": "^0.1.4",
+        "pagefind": "^1.5.2",
         "satteri": "^0.9.5",
         "sharp": "^0.34.5"
     },
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 715655b317..6ecb480a8a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -39,15 +39,12 @@ importers:
       gray-matter:
         specifier: ^4.0.3
         version: 4.0.3
-      html-to-text:
-        specifier: ^10.0.0
-        version: 10.0.0
-      keyword-extractor:
-        specifier: ^0.0.28
-        version: 0.0.28
       optional:
         specifier: ^0.1.4
         version: 0.1.4
+      pagefind:
+        specifier: ^1.5.2
+        version: 1.5.2
       satteri:
         specifier: ^0.9.5
         version: 0.9.5
@@ -821,6 +818,41 @@ packages:
   '@oxc-project/types@0.144.0':
     resolution: {integrity: sha512-nuhZIOLuI6TFQ32I/WnUx+SCPY7SdSKwgnFHydAuoS1+Z4BRcaP+RRJmGzl9lw+0OFF7UmaESf7KQRXaNLHypg==}
 
+  '@pagefind/darwin-arm64@1.5.2':
+    resolution: {integrity: sha512-MXpI+7HsAdPkvJ0gk9xj9g541BCqBZOBbdwj9g6lB5LCj6kSV6nqDSjzcAJwvOsfu0fjwvC8hQU+ecfhp+MpiQ==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@pagefind/darwin-x64@1.5.2':
+    resolution: {integrity: sha512-IojxFWMEJe0RQ7PQ3KXQsPIImNsbpPYpoZ+QUDrL8fAl/O27IX+LVLs74/UzEZy5uA2LD8Nz1AiwKr72vrkZQw==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@pagefind/freebsd-x64@1.5.2':
+    resolution: {integrity: sha512-7EVzo9+0w+2cbe671BtMj10UlNo83I+HrLVLfRxO731svHRJKUfJ/mo05gU14pe9PCfpKNQT8FS3Xc/oDN6pOA==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@pagefind/linux-arm64@1.5.2':
+    resolution: {integrity: sha512-Ovt9+K35sqzn8H3ZMXGwls4TD/wMJuvRtShHIsmUQREmaxjrDEX7gHckRCrwYJ4XE1H1p6HkLz3wukrAnsfXQw==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@pagefind/linux-x64@1.5.2':
+    resolution: {integrity: sha512-V+tFqHKXhQKq/WqPBD67AFy7scn1/aZID00ws4fSDd+1daSi5UHR9VVlRrOUYKxn3VuFQYRD7lYXdZK1WED1YA==}
+    cpu: [x64]
+    os: [linux]
+
+  '@pagefind/windows-arm64@1.5.2':
+    resolution: {integrity: sha512-hN9Nh90fNW61nNRCW9ZyQrAj/mD0eRvmJ8NlTUzkbuW8kIzGJUi3cxjFkEcMZ5h/8FsKWD/VcouZl4yo1F7B6g==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@pagefind/windows-x64@1.5.2':
+    resolution: {integrity: sha512-Fa2Iyw7kaDRzGMfNYNUXNW2zbL5FQVDgSOcbDHdzBrDEdpqOqg8TcZ68F22ol6NJ9IGzvUdmeyZypLW5dyhqsg==}
+    cpu: [x64]
+    os: [win32]
+
   '@pkgjs/parseargs@0.11.0':
     resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
     engines: {node: '>=14'}
@@ -1008,11 +1040,6 @@ packages:
   '@rolldown/pluginutils@1.0.1':
     resolution: {integrity: sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==}
 
-  '@selderee/plugin-htmlparser2@0.12.0':
-    resolution: {integrity: sha512-oELmoyA6ML9jDRMV3kgcMQFKxUfBU0yFVn6yTctVaLT5ygXnxH52I3TZEgV9EhXJC68/uFvE5Daj1/25c0Xa/A==}
-    peerDependencies:
-      selderee: ~0.12.0
-
   '@shikijs/core@4.4.3':
     resolution: {integrity: sha512-QCR4q2ZO/ILJEuwiBMel4wdcTDb1JGwfjKTxPDF6x8ixOaluPrVqIn06C99AcRPhmYlBR56d/Fb+GN58GzExpg==}
     engines: {node: '>=20'}
@@ -1398,10 +1425,6 @@ packages:
   decode-named-character-reference@1.3.0:
     resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
 
-  deepmerge-ts@7.1.5:
-    resolution: {integrity: sha512-HOJkrhaYsweh+W+e74Yn7YStZOilkoPb6fycpwNLKzSPtruFs48nYis0zy5yJz1+ktUhHxoRDJ27RQAWLIJVJw==}
-    engines: {node: '>=16.0.0'}
-
   define-data-property@1.1.4:
     resolution: {integrity: sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A==}
     engines: {node: '>= 0.4'}
@@ -1778,10 +1801,6 @@ packages:
   html-escaper@3.0.3:
     resolution: {integrity: sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ==}
 
-  html-to-text@10.0.0:
-    resolution: {integrity: sha512-2OH59Gtprdczel+7Rxgpz9hGVJREaf8Lt1H4kZwWHpEn70VQKRuMNGsb2eDbwaTzrYzb0hheiOG1P7Dim0B4dQ==}
-    engines: {node: '>=20.19.0'}
-
   html-void-elements@3.0.0:
     resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==}
 
@@ -1979,17 +1998,10 @@ packages:
   jsonc-parser@3.3.1:
     resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==}
 
-  keyword-extractor@0.0.28:
-    resolution: {integrity: sha512-oi7dSPpYtW/3fE0vZiqQgZ8mW3F1V9K4+rBJ0FcVrdXBEQuhZ0zKj7sX74eqGASuepLHf9aYdeonyKHWhYpHQA==}
-    engines: {node: '>= 0.10.0'}
-
   kind-of@6.0.3:
     resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==}
     engines: {node: '>=0.10.0'}
 
-  leac@0.7.0:
-    resolution: {integrity: sha512-qMrZeyEekgdRQ9o6a4NAB2EQZrv827GJdn1vnapwSJ90hWRB4TzUSunvacPkxQ2TnNqHNI1/zSt0hlo0crG8Jw==}
-
   lightningcss-android-arm64@1.33.0:
     resolution: {integrity: sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg==}
     engines: {node: '>= 12.0.0'}
@@ -2392,6 +2404,10 @@ packages:
   package-manager-detector@1.8.0:
     resolution: {integrity: sha512-yQA4H19AmPEoMUeavPMDIe1higySl/gH/yaQrkT/s07Qp+7pp2hYz30N3z2l5BkjVkF9Ow6o0wjJamm2y7Sn0A==}
 
+  pagefind@1.5.2:
+    resolution: {integrity: sha512-XTUaK0hXMCu2jszWE584JGQT7y284TmMV9l/HX3rnG5uo3rHI/uHU56XTyyyPFjeWEBxECbAi0CaFDJOONtG0Q==}
+    hasBin: true
+
   parse-entities@4.0.2:
     resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==}
 
@@ -2405,9 +2421,6 @@ packages:
   parse5@7.3.0:
     resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==}
 
-  parseley@0.13.1:
-    resolution: {integrity: sha512-uNBJZzmb60l6p6VWLTmevizNAGnE0xoSf1n0B4q3ntegDNzcS68NRCcBDZTcyXHxt2XhBChsCuqj4M+nChvE/A==}
-
   path-key@2.0.1:
     resolution: {integrity: sha512-fEHGKCSmUSDPv4uoj8AlD+joPlq3peND+HRYyxFz4KPw4z926S/b8rIuFs2FYJg3BwsxJf6A9/3eIdLaYC+9Dw==}
     engines: {node: '>=4'}
@@ -2431,9 +2444,6 @@ packages:
     resolution: {integrity: sha512-T2ZUsdZFHgA3u4e5PfPbjd7HDDpxPnQb5jN0SrDsjNSuVXHJqtwTnWqG0B1jZrgmJ/7lj1EmVIByWt1gxGkWvg==}
     engines: {node: '>=4'}
 
-  peberminta@0.10.0:
-    resolution: {integrity: sha512-80B2AsU+I4Qdb0ZAPSfe9UwvGzwkM37IKIFEvdS3D/3Ndgv2bsuJ0bfG1+iEYO+l7Gfd4EUJmuRyq7efLgRMzQ==}
-
   piccolore@0.1.3:
     resolution: {integrity: sha512-o8bTeDWjE086iwKrROaDf31K0qC/BENdm15/uH9usSC/uZjJOKb2YGiVHfLY4GhwsERiPI1jmwI2XrA7ACOxVw==}
 
@@ -2634,9 +2644,6 @@ packages:
     resolution: {integrity: sha512-vfD3pmTzGpufjScBh50YHKzEu2lxBWhVEHsNGoEXmCmn2hKGfeNLYMzCJpe8cD7gqX7TJluOVpBkAequ6dgMmA==}
     engines: {node: '>=4'}
 
-  selderee@0.12.0:
-    resolution: {integrity: sha512-b1YMh3+DHZp59DLna3qVwQ5iOla/nrI6mLBNW02XxU77M3046Df6VLkoaJyFz20VsGIG5kkp+FK0kg4K4HnUFw==}
-
   semver@5.7.2:
     resolution: {integrity: sha512-cBznnQ9KjJqU67B52RMC65CMarK2600WFnbkcaiwWq3xy/5haFJlshgnpjovMVJ+Hff49d8GEn0b87C5pDQ10g==}
     hasBin: true
@@ -3796,6 +3803,27 @@ snapshots:
 
   '@oxc-project/types@0.144.0': {}
 
+  '@pagefind/darwin-arm64@1.5.2':
+    optional: true
+
+  '@pagefind/darwin-x64@1.5.2':
+    optional: true
+
+  '@pagefind/freebsd-x64@1.5.2':
+    optional: true
+
+  '@pagefind/linux-arm64@1.5.2':
+    optional: true
+
+  '@pagefind/linux-x64@1.5.2':
+    optional: true
+
+  '@pagefind/windows-arm64@1.5.2':
+    optional: true
+
+  '@pagefind/windows-x64@1.5.2':
+    optional: true
+
   '@pkgjs/parseargs@0.11.0':
     optional: true
 
@@ -3916,12 +3944,6 @@ snapshots:
 
   '@rolldown/pluginutils@1.0.1': {}
 
-  '@selderee/plugin-htmlparser2@0.12.0(selderee@0.12.0)':
-    dependencies:
-      domelementtype: 2.3.0
-      domhandler: 5.0.3
-      selderee: 0.12.0
-
   '@shikijs/core@4.4.3':
     dependencies:
       '@shikijs/primitive': 4.4.3
@@ -4437,8 +4459,6 @@ snapshots:
     dependencies:
       character-entities: 2.0.2
 
-  deepmerge-ts@7.1.5: {}
-
   define-data-property@1.1.4:
     dependencies:
       es-define-property: 1.0.1
@@ -4998,14 +5018,6 @@ snapshots:
 
   html-escaper@3.0.3: {}
 
-  html-to-text@10.0.0:
-    dependencies:
-      '@selderee/plugin-htmlparser2': 0.12.0(selderee@0.12.0)
-      deepmerge-ts: 7.1.5
-      dom-serializer: 2.0.0
-      htmlparser2: 10.1.0
-      selderee: 0.12.0
-
   html-void-elements@3.0.0: {}
 
   htmlparser2@10.1.0:
@@ -5193,12 +5205,8 @@ snapshots:
 
   jsonc-parser@3.3.1: {}
 
-  keyword-extractor@0.0.28: {}
-
   kind-of@6.0.3: {}
 
-  leac@0.7.0: {}
-
   lightningcss-android-arm64@1.33.0:
     optional: true
 
@@ -5851,6 +5859,16 @@ snapshots:
 
   package-manager-detector@1.8.0: {}
 
+  pagefind@1.5.2:
+    optionalDependencies:
+      '@pagefind/darwin-arm64': 1.5.2
+      '@pagefind/darwin-x64': 1.5.2
+      '@pagefind/freebsd-x64': 1.5.2
+      '@pagefind/linux-arm64': 1.5.2
+      '@pagefind/linux-x64': 1.5.2
+      '@pagefind/windows-arm64': 1.5.2
+      '@pagefind/windows-x64': 1.5.2
+
   parse-entities@4.0.2:
     dependencies:
       '@types/unist': 2.0.11
@@ -5879,11 +5897,6 @@ snapshots:
     dependencies:
       entities: 6.0.1
 
-  parseley@0.13.1:
-    dependencies:
-      leac: 0.7.0
-      peberminta: 0.10.0
-
   path-key@2.0.1: {}
 
   path-key@3.1.1: {}
@@ -5904,8 +5917,6 @@ snapshots:
     dependencies:
       pify: 3.0.0
 
-  peberminta@0.10.0: {}
-
   piccolore@0.1.3: {}
 
   picocolors@1.1.1: {}
@@ -6198,10 +6209,6 @@ snapshots:
       extend-shallow: 2.0.1
       kind-of: 6.0.3
 
-  selderee@0.12.0:
-    dependencies:
-      parseley: 0.13.1
-
   semver@5.7.2: {}
 
   semver@7.8.0: {}
diff --git a/src/components/ArticleHeader.astro b/src/components/ArticleHeader.astro
index 85f387e823..e5e7740821 100644
--- a/src/components/ArticleHeader.astro
+++ b/src/components/ArticleHeader.astro
@@ -12,8 +12,11 @@ type Props = {
   lang: string;
   subtitle?: string | null;
   title: string;
+  /** Passed to `data-pagefind-weight`. Omitted leaves Pagefind's own heading
+   *  weighting alone. */
+  searchWeight?: number;
 };
-const { lang, subtitle, title } = Astro.props satisfies Props;
+const { lang, subtitle, title, searchWeight } = Astro.props satisfies Props;
 
 // Language
 const _ = Lang(lang);
@@ -22,7 +25,7 @@ const _ = Lang(lang);
 stats.stop();
 ---
 
-<header class="header">
+<header class="header" data-pagefind-weight={searchWeight}>
   <h1 class="header__title">{title}</h1>
   {subtitle && <p class="header__subtitle">{subtitle}</p>}
 </header>
diff --git a/src/components/DocsSearch.astro b/src/components/DocsSearch.astro
index 4957e1b73c..6c5162e9df 100644
--- a/src/components/DocsSearch.astro
+++ b/src/components/DocsSearch.astro
@@ -44,7 +44,7 @@ if (facets.length === 0) {
   throw new Error('DocsSearch needs at least one facet for its tab strip');
 }
 
-const indexUrl = `${SITE.subfolder}/search.json`;
+const indexUrl = `${SITE.subfolder}/pagefind/`;
 const listboxId = `${name}-search-listbox`;
 ---
 
@@ -128,6 +128,17 @@ const listboxId = `${name}-search-listbox`;
       </p>
     </div>
 
+    <!-- Outside the body, which is hidden until there is a query: a live region
+         that has just entered the accessibility tree does not reliably announce
+         the first thing written to it. -->
+    <p
+      class="docs-search__announce"
+      role="status"
+      aria-live="polite"
+      data-docs-search-announce
+    >
+    </p>
+
     <!-- Astro scopes a component's styles to the markup it can see at build
          time, so a row assembled from `createElement` would come out unstyled.
          Cloning this template carries the scope with it. -->
@@ -145,6 +156,20 @@ const listboxId = `${name}-search-listbox`;
       </li>
     </template>
 
+    {
+      /* A heading inside the result above that matched on its own. Its own
+         `role="option"`, because it links somewhere different: the reader can
+         arrow onto it and land on that section. */
+    }
+    <template data-docs-search-section>
+      <li role="presentation">
+        <a class="docs-search__section" role="option" aria-selected="false">
+          <span class="docs-search__section-mark" aria-hidden="true"></span>
+          <span class="docs-search__section-title"></span>
+        </a>
+      </li>
+    </template>
+
     <div class="docs-search__footer">
       <span class="docs-search__hint">
         <span class="docs-search__hint-icon docs-search__hint-icon--navigate"
@@ -436,6 +461,36 @@ const listboxId = `${name}-search-listbox`;
     visibility: visible;
   }
 
+  .docs-search__section {
+    display: flex;
+    gap: var(--space4);
+    align-items: baseline;
+    /* Lines up with the parent row's title, past its icon. */
+    padding-block: var(--space2);
+    padding-inline: calc(var(--space12) + 1.5rem) var(--space12);
+    color: var(--colorTextSecondary);
+    font: var(--textBodyRegularMedium);
+    text-decoration: none;
+  }
+
+  .docs-search__section[data-active] {
+    background: var(--colorNavBackgroundActive);
+  }
+
+  .docs-search__section-mark {
+    flex: none;
+    width: 0.75rem;
+    height: 0.75rem;
+    background-color: var(--colorIconTertiary);
+    mask: var(--arrowNested) center / contain no-repeat;
+  }
+
+  .docs-search__section-title {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
   .docs-search__empty {
     margin: 0;
     padding: var(--space12);
@@ -443,6 +498,18 @@ const listboxId = `${name}-search-listbox`;
     font: var(--textBodyRegularMedium);
   }
 
+  /* Visually hidden by clipping. `hidden` and `display: none` would take it out
+     of the accessibility tree and silence it. */
+  .docs-search__announce {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
   .docs-search__footer {
     flex-shrink: 0;
     display: flex;
diff --git a/src/components/Image.astro b/src/components/Image.astro
index 82cc6224a2..7db8036de1 100644
--- a/src/components/Image.astro
+++ b/src/components/Image.astro
@@ -9,6 +9,11 @@ const { src, alt, caption } = Astro.props satisfies Props;
 ---
 
 <figure class="image" data-image>
-  <img src={src} alt={alt} class="image__img" />
+  <img
+    src={src}
+    alt={alt}
+    class="image__img"
+    data-pagefind-index-attrs={alt ? 'alt' : undefined}
+  />
   {caption && <figcaption class="image__caption">{caption}</figcaption>}
 </figure>
diff --git a/src/integrations/pagefind-index.ts b/src/integrations/pagefind-index.ts
new file mode 100644
index 0000000000..0cfa405055
--- /dev/null
+++ b/src/integrations/pagefind-index.ts
@@ -0,0 +1,99 @@
+// Builds the Pagefind index from the HTML the site just emitted. What gets
+// indexed is decided by the `data-pagefind-*` attributes in `Default.astro`.
+//
+// The index has to land inside `dist/docs/`, because `prune-dist.ts` deletes
+// every top-level entry outside its allowlist, and this has to be registered
+// before `pruneDist()` — hooks run in the order they are listed.
+
+import type { AstroIntegration } from 'astro';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+// Statically, because `astro:build:done` fires after Vite's module runner has
+// closed and a dynamic import from inside the hook cannot be resolved.
+import { createIndex, close } from 'pagefind';
+
+// Roughly the number of pages that pass the search predicate. Well under it means
+// the body scoping has broken, which is otherwise a silent failure: search still
+// works, it is just full of the wrong pages.
+const EXPECTED_PAGES = 1000;
+
+export default function pagefindIndex(): AstroIntegration {
+  return {
+    name: 'pagefind-index',
+    hooks: {
+      'astro:build:done': async ({ dir, logger }) => {
+        const distDir = fileURLToPath(dir);
+
+        const { index, errors } = await createIndex({
+          keepIndexUrl: false,
+          // Pagefind strips punctuation from both the index and the query, which
+          // left `<head>` matching nothing at all. Keeping these characters
+          // indexes both forms — `head` *and* `<head>` — so ordinary searches are
+          // unaffected and a reader pasting real syntax gets the page about it.
+          //
+          // Each character earns its place: `.` for dotted variable and
+          // executable names, `#{}` for substitution syntax, `<>` for tags, `+`
+          // for C++, and `$_` for shell variables.
+          includeCharacters: '.#{}<>+$_',
+        });
+
+        if (!index) {
+          logger.error(`could not start Pagefind: ${errors.join(', ')}`);
+          return;
+        }
+
+        // `dist/docs` rather than `dist`: the client sets a `basePath` of
+        // `/docs/` which Pagefind prepends at query time, so indexing from `dist`
+        // would put the prefix on twice.
+        const added = await index.addDirectory({
+          path: path.join(distDir, 'docs'),
+          glob: '**/*.html',
+        });
+
+        if (added.errors.length > 0) {
+          logger.error(added.errors.join(', '));
+        }
+
+        const written = await index.writeFiles({
+          outputPath: path.join(distDir, 'docs', 'pagefind'),
+        });
+
+        if (written.errors.length > 0) {
+          logger.error(written.errors.join(', '));
+        }
+
+        await close();
+
+        // `page_count` is files scanned, not files indexed — it counts the
+        // redirect stubs that `data-pagefind-body` then drops. One fragment is
+        // written per indexed page, so that is the number worth checking.
+        //
+        // No fragment directory at all is the worst version of the failure the
+        // warning below exists to report, so it must not throw ahead of it.
+        const fragments = path.join(distDir, 'docs', 'pagefind', 'fragment');
+        const indexed = fs.existsSync(fragments)
+          ? (await fs.promises.readdir(fragments)).length
+          : 0;
+
+        logger.info(
+          `indexed ${indexed} of ${added.page_count} pages into docs/pagefind`
+        );
+
+        // Nothing indexed at all means every query returns nothing. That must
+        // not ship behind a green build.
+        if (indexed === 0) {
+          throw new Error(
+            'Pagefind indexed no pages — check data-pagefind-body is still on the article in Default.astro'
+          );
+        }
+
+        if (indexed < EXPECTED_PAGES) {
+          logger.warn(
+            `only ${indexed} pages were indexed, expected at least ${EXPECTED_PAGES} — check data-pagefind-body is still on the article`
+          );
+        }
+      },
+    },
+  };
+}
diff --git a/src/layouts/Default.astro b/src/layouts/Default.astro
index a4e7ec2bdc..37cdd3a26e 100644
--- a/src/layouts/Default.astro
+++ b/src/layouts/Default.astro
@@ -59,6 +59,59 @@ const showSearch = !isSearchPage;
 
 // The footer prints this; JSON-LD carries it as dateModified.
 const lastUpdated = frontmatter.modDate ?? frontmatter.pubDate ?? null;
+
+// Search indexing. Redirect stubs never reach this layout at all, so only the
+// frontmatter opt-outs have to be checked here. Deliberately looser than
+// `PostFiltering.isListable`, which also hides a future `pubDate`: a page that
+// is built and served is a page worth finding.
+const indexable =
+  frontmatter.navSearch !== false &&
+  frontmatter.listable !== false &&
+  frontmatter.draft !== true;
+
+// Which tab a result lands under. Longest match first: every CLI page also sits
+// under the REST API tree. Kept in step with `classify()` in
+// `src/scripts/search-engine.ts`, which derives the same value at query time.
+const sections: [string, RegExp][] = [
+  [
+    'cli',
+    /^\/docs\/octopus-rest-api\/(cli|octopus-cli|[a-z.]+-command-line)(\/|$)/,
+  ],
+  ['api', /^\/docs\/octopus-rest-api(\/|$)/],
+  ['integrations', /^\/docs\/api-and-integration(\/|$)/],
+];
+const section =
+  sections.find(([, prefix]) => prefix.test(Astro.url.pathname))?.[0] ?? 'docs';
+
+// Boosts a section landing page's own name. Pagefind weights an h1 at 7 on a
+// quadratic scale, so 10 roughly doubles the pull of a shallow page's title. The
+// reorder in `search-engine-pagefind.ts` does the real work; this assists it.
+const depth = Astro.url.pathname.split('/').filter(Boolean).length;
+const searchWeight = indexable && depth <= 3 ? 10 : undefined;
+
+// Indexed so results can be ordered by recency. Nothing in the overlay offers
+// that control yet, and adding one later would otherwise need a rebuild.
+const sortKeys =
+  indexable && lastUpdated
+    ? `date:${new Date(lastUpdated).toISOString().slice(0, 10)}`
+    : undefined;
+
+// Pagefind takes a result's title from the first heading inside the indexed body,
+// so a page whose h1 renders as an image would show its URL in the result row. A
+// real heading still wins; this is only consulted when there is none.
+const defaultMeta =
+  indexable && frontmatter.title ? `title:${frontmatter.title}` : undefined;
+
+// The trail the result row prints, taken from the path so it matches whatever
+// the page is actually filed under.
+const trail = Astro.url.pathname
+  .split('/')
+  .filter(Boolean)
+  .slice(1, -1)
+  .map((segment) =>
+    segment.replace(/-/g, ' ').replace(/^./, (c) => c.toUpperCase())
+  )
+  .join(' / ');
 ---
 
 <html
@@ -80,9 +133,26 @@ const lastUpdated = frontmatter.modDate ?? frontmatter.pubDate ?? null;
     <div class="content-group">
       <main id="site-main">
         <Breadcrumbs lang={lang} crumbs={crumbs} />
-        <article>
-          <ArticleHeader lang={lang} subtitle={subtitle} title={title} />
-          <div class="page-actions">
+        {
+          /* Scoping the index to the article keeps every sidebar link and footer
+             word out of every page's search terms. The article rather than
+             `.page-content`, so the h1 inside it is there for Pagefind to take
+             the result title from. */
+        }
+        <article
+          data-pagefind-body={indexable ? true : undefined}
+          data-pagefind-filter={indexable ? `section:${section}` : undefined}
+          data-pagefind-meta={indexable ? `trail:${trail}` : undefined}
+          data-pagefind-sort={sortKeys}
+          data-pagefind-default-meta={defaultMeta}
+        >
+          <ArticleHeader
+            lang={lang}
+            searchWeight={searchWeight}
+            subtitle={subtitle}
+            title={title}
+          />
+          <div class="page-actions" data-pagefind-ignore="all">
             <CopyAsMarkdown lang={lang} />
             <OpenInLlm lang={lang} />
             <EditOnGithub
@@ -95,7 +165,13 @@ const lastUpdated = frontmatter.modDate ?? frontmatter.pubDate ?? null;
             <slot />
             <Authors frontmatter={frontmatter} lang={lang} />
             <Taxonomy frontmatter={frontmatter} lang={lang} />
-            <MarkdownLinks lang={lang} />
+            {
+              /* `all` rather than the default `index`: a bare ignore still lets
+                 Pagefind read a title or metadata out of the block. */
+            }
+            <div data-pagefind-ignore="all">
+              <MarkdownLinks lang={lang} />
+            </div>
           </div>
         </article>
       </main>
diff --git a/src/lib/underConstruction.ts b/src/lib/underConstruction.ts
index 042bd23513..76f4d37b74 100644
--- a/src/lib/underConstruction.ts
+++ b/src/lib/underConstruction.ts
@@ -7,9 +7,10 @@
 // sitemap.xml, so neither readers nor Google arrive at it ahead of the pages
 // that explain it.
 //
-// Call sites are src/pages/docs/search.json.ts and src/pages/docs/sitemap.xml.ts.
-// Both take their page list from an `import.meta.glob` rooted at
-// src/pages/docs, so the paths they pass in look like './api/feeds.md'.
+// The call site is src/pages/docs/sitemap.xml.ts, which takes its page list from
+// an `import.meta.glob` rooted at src/pages/docs, so the paths it passes in look
+// like './api/feeds.md'. Search exclusion is no longer done here: Pagefind
+// indexes only what carries `data-pagefind-body`, and Api.astro carries none.
 
 const UNDER_CONSTRUCTION = [/^api(\/|$)/];
 
diff --git a/src/pages/components.mdx b/src/pages/components.mdx
index 8e9d24c43a..2e5384e82b 100644
--- a/src/pages/components.mdx
+++ b/src/pages/components.mdx
@@ -357,8 +357,8 @@ needs its own.
    run against.
 
 Results come from a `SearchEngine` (`src/scripts/search-engine.ts`), which is the
-seam the index sits behind. Production uses `legacyEngine`, over the build-time
-`search.json`.
+seam the index sits behind. Production uses `pagefindEngine`, over the Pagefind
+index built from the site's own HTML at the end of the build.
 
 Focus stays in the input the whole time it is open and `aria-activedescendant`
 moves down the list, so you can keep refining a query without tabbing out of the
diff --git a/src/pages/docs/search.json.ts b/src/pages/docs/search.json.ts
deleted file mode 100644
index 6ef6c53a15..0000000000
--- a/src/pages/docs/search.json.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-/** @format */
-
-// warning: This file is overwritten by Astro Accelerator
-
-import { accelerator } from '@lib/accelerator';
-import { PostFiltering } from 'astro-accelerator-utils';
-import type { MarkdownInstance } from 'astro';
-import { SITE } from '@config';
-import { convert } from 'html-to-text';
-import keywordExtractor from 'keyword-extractor';
-import { isUnderConstruction } from '@lib/underConstruction';
-
-const getData = async () => {
-  //@ts-ignore
-  const allPages = import.meta.glob(['./**/*.md', './**/*.mdx']);
-  const items = [];
-
-  for (const path in allPages) {
-    // Temporary - see src/lib/underConstruction.ts.
-    if (isUnderConstruction(path)) {
-      continue;
-    }
-
-    const page = (await allPages[path]()) as MarkdownInstance<
-      Record<string, any>
-    >;
-
-    if (!PostFiltering.showInSearch(page)) {
-      continue;
-    }
-
-    let url = page.url ?? '';
-
-    if (page.frontmatter.paged) {
-      url += '/1/';
-    }
-
-    const headings = await page.getHeadings();
-    const title = await accelerator.markdown.getTextFrom(
-      page.frontmatter?.title
-    );
-    const content = page.compiledContent ? await page.compiledContent() : '';
-    let counted: { word: string; count: number }[] = [];
-
-    if (content) {
-      const options = {
-        wordwrap: false,
-        selectors: [
-          { selector: 'a', options: { ignoreHref: true } },
-          { selector: 'img', format: 'skip' },
-          { selector: 'h1', options: { uppercase: false } },
-        ],
-      };
-      const text = convert(content, options);
-
-      const words = keywordExtractor.extract(text, {
-        language: 'english',
-        return_changed_case: true,
-        remove_duplicates: true,
-      });
-
-      counted = words
-        .map((w) => {
-          return {
-            word: w,
-            count: words.filter((wd) => wd === w).length,
-          };
-        })
-        .filter((e) => e.word.replace(/[^a-z]+/g, '').length > 1);
-    }
-
-    items.push({
-      title: title,
-      headings: headings.map((h) => {
-        return { text: h.text, slug: h.slug };
-      }),
-      description: page.frontmatter.description ?? '',
-      keywords: counted.map((c) => c.word).join(' '),
-      tags: page.frontmatter.tags ?? [],
-      url: SITE.url + accelerator.urlFormatter.formatAddress(url),
-      date: page.frontmatter.pubDate ?? '',
-    });
-  }
-
-  return new Response(JSON.stringify(items), {
-    status: 200,
-    headers: {
-      'Content-Type': 'application/json',
-    },
-  });
-};
-
-export const GET = getData;
diff --git a/src/plugins/pagefind-image-attrs.js b/src/plugins/pagefind-image-attrs.js
new file mode 100644
index 0000000000..f185c6b9fe
--- /dev/null
+++ b/src/plugins/pagefind-image-attrs.js
@@ -0,0 +1,29 @@
+import { defineHastPlugin } from 'satteri';
+
+// Makes image alt text searchable. Pagefind indexes text nodes, so the words in
+// an `alt` attribute are invisible to it without `data-pagefind-index-attrs`,
+// which applies only to the element carrying it — there is no inheritance, so it
+// has to land on every `<img>`.
+//
+// Covers markdown image syntax and `:img{}` directives. A raw `<img>` written
+// straight into a page is passed through as HTML and never becomes a hast
+// element, which is why `Image.astro` carries the attribute itself.
+
+export default defineHastPlugin({
+  name: 'pagefind-image-attrs',
+  element: {
+    filter: ['img'],
+    visit(node, ctx) {
+      const { alt, title } = node.properties ?? {};
+
+      // A decorative image carries `alt=""`, a deliberate signal that it has
+      // nothing to say.
+      const wanted = [alt ? 'alt' : null, title ? 'title' : null].filter(
+        Boolean
+      );
+      if (wanted.length === 0) return;
+
+      ctx.setProperty(node, 'data-pagefind-index-attrs', wanted.join(','));
+    },
+  },
+});
diff --git a/src/scripts/docs-search.ts b/src/scripts/docs-search.ts
index ef88eb5758..dd46cee0ec 100644
--- a/src/scripts/docs-search.ts
+++ b/src/scripts/docs-search.ts
@@ -13,10 +13,20 @@ import {
   fixtureEngine,
   type SearchEngine,
   type SearchResult,
+  type SearchSubResult,
 } from './search-engine';
-import { legacyEngine } from './search-engine-legacy';
+import { pagefindEngine } from './search-engine-pagefind';
 
 const DEBOUNCE_MS = 150;
+
+// Below this, typing is not yet a query.
+//
+// A single character matches an enormous share of the index, and Pagefind
+// fetches every chunk a query touches: one character costs 975ms, two 837ms,
+// three 342ms, and under 200ms beyond that. Two rather than three deliberately —
+// `s3`, `ui` and `ad` are real searches, and returning nothing for them was worse
+// than the wait.
+const MIN_QUERY_LENGTH = 2;
 const SITE_SEARCH = 'site';
 
 function setup(dialog: HTMLDialogElement) {
@@ -30,18 +40,34 @@ function setup(dialog: HTMLDialogElement) {
   const list = dialog.querySelector<HTMLElement>('[data-docs-search-results]');
   const empty = dialog.querySelector<HTMLElement>('[data-docs-search-empty]');
   const echo = dialog.querySelector<HTMLElement>('[data-docs-search-echo]');
+  const announce = dialog.querySelector<HTMLElement>(
+    '[data-docs-search-announce]'
+  );
   const template = dialog.querySelector<HTMLTemplateElement>(
     '[data-docs-search-row]'
   );
+  const sectionTemplate = dialog.querySelector<HTMLTemplateElement>(
+    '[data-docs-search-section]'
+  );
 
   // A partially rendered overlay is a bug elsewhere; wiring half of it up would
   // only turn that into a confusing runtime failure.
-  if (!input || !tabs || !body || !list || !empty || !echo || !template) return;
+  if (
+    !input ||
+    !tabs ||
+    !body ||
+    !list ||
+    !empty ||
+    !echo ||
+    !announce ||
+    !template
+  )
+    return;
 
   const demo = dialog.dataset.demoResults;
   const engine: SearchEngine = demo
     ? fixtureEngine(JSON.parse(demo))
-    : legacyEngine(dialog.dataset.indexUrl ?? '/docs/search.json');
+    : pagefindEngine(dialog.dataset.indexUrl ?? '/docs/pagefind/');
 
   let facet = 'all';
   let active = -1;
@@ -99,8 +125,46 @@ function setup(dialog: HTMLDialogElement) {
     return item;
   }
 
+  function drawSection(
+    template: HTMLTemplateElement,
+    section: SearchSubResult,
+    at: number
+  ) {
+    const item = template.content.cloneNode(true) as DocumentFragment;
+
+    const row = item.querySelector<HTMLAnchorElement>('.docs-search__section')!;
+    row.id = `${name}-search-option-${at}`;
+    row.href = section.url;
+    item.querySelector('.docs-search__section-title')!.textContent =
+      section.title;
+
+    return item;
+  }
+
+  /**
+   * Rows for the whole response, pages and their matched sections interleaved.
+   * The running index is what keeps `aria-activedescendant` working: every option
+   * needs a unique id, and a page's sections are numbered between it and the next
+   * page.
+   */
+  function drawAll(results: SearchResult[]) {
+    const nodes: DocumentFragment[] = [];
+    let at = 0;
+
+    for (const result of results) {
+      nodes.push(drawRow(result, at++));
+      if (!sectionTemplate) continue;
+      for (const section of result.sections ?? []) {
+        nodes.push(drawSection(sectionTemplate, section, at++));
+      }
+    }
+
+    return nodes;
+  }
+
   function render(response: Awaited<ReturnType<SearchEngine['search']>>) {
-    list!.replaceChildren(...response.results.map(drawRow));
+    const rows = drawAll(response.results);
+    list!.replaceChildren(...rows);
 
     for (const tab of facetTabs()) {
       const key = tab.dataset.facet!;
@@ -111,7 +175,10 @@ function setup(dialog: HTMLDialogElement) {
       tab.querySelector('.docs-search__count')!.textContent = `(${count})`;
     }
 
-    const hasQuery = input!.value.trim().length > 0;
+    // Long enough to have been searched, rather than merely non-empty. A single
+    // character never ran, so the panel should look like it is waiting rather
+    // than reporting nothing found.
+    const hasQuery = input!.value.trim().length >= MIN_QUERY_LENGTH;
     const hasResults = response.results.length > 0;
 
     tabs!.hidden = !hasQuery;
@@ -120,6 +187,20 @@ function setup(dialog: HTMLDialogElement) {
     echo!.textContent = input!.value.trim();
     input!.setAttribute('aria-expanded', String(hasQuery && hasResults));
 
+    // The combobox roles say a listbox exists and which row is active; nothing
+    // says what came back. Pages are counted the way the tab strip counts them,
+    // and the matched sections are named separately, because each is another
+    // option to arrow onto without being another result.
+    const term = input!.value.trim();
+    const pages = response.results.length;
+    const sections = rows.length - pages;
+    announce!.textContent = !hasQuery
+      ? ''
+      : pages === 0
+        ? `No results for ${term}`
+        : `${pages} ${pages === 1 ? 'result' : 'results'} for ${term}` +
+          (sections > 0 ? `, with ${sections} matching sections` : '');
+
     setActive(0);
   }
 
@@ -133,6 +214,13 @@ function setup(dialog: HTMLDialogElement) {
   }
 
   async function run() {
+    // Also guarded here, not only in `schedule`: a shared `?q=` link opens
+    // straight into a search without going through the debounce.
+    if (input!.value.trim().length < MIN_QUERY_LENGTH) {
+      render({ results: [], counts: {} });
+      return;
+    }
+
     const mine = ++generation;
     let response = await engine.search(input!.value, facet);
     if (mine !== generation) return;
@@ -150,6 +238,15 @@ function setup(dialog: HTMLDialogElement) {
 
   function schedule() {
     window.clearTimeout(debounce);
+
+    // Too short to search: close the panel back down rather than leaving the
+    // previous query's results under a field that no longer says that.
+    if (input!.value.trim().length < MIN_QUERY_LENGTH) {
+      generation += 1;
+      render({ results: [], counts: {} });
+      return;
+    }
+
     debounce = window.setTimeout(run, DEBOUNCE_MS);
   }
 
@@ -212,7 +309,15 @@ function setup(dialog: HTMLDialogElement) {
 
   // --- Inside the dialog ---------------------------------------------------
 
-  input.addEventListener('input', schedule);
+  input.addEventListener('input', () => {
+    // Ahead of the debounce, so the chunks this query needs are already on their
+    // way by the time the search runs. Guarded the same way `schedule` is: the
+    // fetch is most of what `MIN_QUERY_LENGTH` exists to avoid.
+    if (input!.value.trim().length >= MIN_QUERY_LENGTH) {
+      engine.preload?.(input!.value);
+    }
+    schedule();
+  });
 
   dialog.addEventListener('keydown', (event) => {
     // Up and Down only. Home and End belong to the query, which is what an
@@ -316,7 +421,9 @@ function setup(dialog: HTMLDialogElement) {
   if (name !== SITE_SEARCH) return;
 
   // Cmd+K on Apple platforms, Ctrl+K everywhere else.
-  const navigator = (window.navigator as Navigator & { userAgentData?: { platform: string } });
+  const navigator = window.navigator as Navigator & {
+    userAgentData?: { platform: string };
+  };
   const isApple = navigator.userAgentData
     ? navigator.userAgentData.platform === 'macOS'
     : (navigator.platform || navigator.userAgent).includes('Mac');
@@ -328,6 +435,10 @@ function setup(dialog: HTMLDialogElement) {
     open();
   });
 
+  // Engines that are cheap to start say so; the rest wait for the overlay. See
+  // `eager` on `SearchEngine` for why this is not the same answer for both.
+  if (engine.eager) engine.warm?.();
+
   // A shared `?q=` link opens straight into results.
   const q = new URLSearchParams(window.location.search).get('q');
   if (q) open(q);
diff --git a/src/scripts/modules/stemmer.js b/src/scripts/modules/stemmer.js
deleted file mode 100644
index 778ebcc9c0..0000000000
--- a/src/scripts/modules/stemmer.js
+++ /dev/null
@@ -1,197 +0,0 @@
-/**
- * Removes "morphological and inflexional endings" from words
- * See: http://www.tartarus.org/~martin/PorterStemmer
- */
-export const stemmer = (function () {
-  const step2list = {
-    ational: 'ate',
-    tional: 'tion',
-    enci: 'ence',
-    anci: 'ance',
-    izer: 'ize',
-    bli: 'ble',
-    alli: 'al',
-    entli: 'ent',
-    eli: 'e',
-    ousli: 'ous',
-    ization: 'ize',
-    ation: 'ate',
-    ator: 'ate',
-    alism: 'al',
-    iveness: 'ive',
-    fulness: 'ful',
-    ousness: 'ous',
-    aliti: 'al',
-    iviti: 'ive',
-    biliti: 'ble',
-    logi: 'log',
-  };
-
-  const step3list = {
-    icate: 'ic',
-    ative: '',
-    alize: 'al',
-    iciti: 'ic',
-    ical: 'ic',
-    ful: '',
-    ness: '',
-  };
-
-  const c = '[^aeiou]', // consonant
-    v = '[aeiouy]', // vowel
-    C = c + '[^aeiouy]*', // consonant sequence
-    V = v + '[aeiou]*', // vowel sequence
-    mgr0 = '^(' + C + ')?' + V + C, // [C]VC... is m>0
-    meq1 = '^(' + C + ')?' + V + C + '(' + V + ')?$', // [C]VC[V] is m=1
-    mgr1 = '^(' + C + ')?' + V + C + V + C, // [C]VCVC... is m>1
-    s_v = '^(' + C + ')?' + v; // vowel in stem
-
-  /**
-   * @param {string} w
-   * @returns {string}
-   */
-  return function (w) {
-    var stem,
-      suffix,
-      firstch,
-      re,
-      re2,
-      re3,
-      re4,
-      origword = w;
-
-    if (w.length < 3) {
-      return w;
-    }
-
-    firstch = w.substring(0, 1);
-
-    if (firstch == 'y') {
-      w = firstch.toUpperCase() + w.substring(1, w.length);
-    }
-
-    // Step 1a
-    re = /^(.+?)(ss|i)es$/;
-    re2 = /^(.+?)([^s])s$/;
-
-    if (re.test(w)) {
-      w = w.replace(re, '$1$2');
-    } else if (re2.test(w)) {
-      w = w.replace(re2, '$1$2');
-    }
-
-    // Step 1b
-    re = /^(.+?)eed$/;
-    re2 = /^(.+?)(ed|ing)$/;
-    if (re.test(w)) {
-      var fp = re.exec(w);
-      re = new RegExp(mgr0);
-      if (re.test(fp[1])) {
-        re = /.$/;
-        w = w.replace(re, '');
-      }
-    } else if (re2.test(w)) {
-      var fp = re2.exec(w);
-      stem = fp[1];
-      re2 = new RegExp(s_v);
-      if (re2.test(stem)) {
-        w = stem;
-        re2 = /(at|bl|iz)$/;
-        re3 = new RegExp('([^aeiouylsz])\\1$');
-        re4 = new RegExp('^' + C + v + '[^aeiouwxy]$');
-        if (re2.test(w)) {
-          w = w + 'e';
-        } else if (re3.test(w)) {
-          re = /.$/;
-          w = w.replace(re, '');
-        } else if (re4.test(w)) {
-          w = w + 'e';
-        }
-      }
-    }
-
-    // Step 1c
-    re = /^(.+?)y$/;
-    if (re.test(w)) {
-      var fp = re.exec(w);
-      stem = fp[1];
-      re = new RegExp(s_v);
-      if (re.test(stem)) {
-        w = stem + 'i';
-      }
-    }
-
-    // Step 2
-    re =
-      /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
-    if (re.test(w)) {
-      var fp = re.exec(w);
-      stem = fp[1];
-      suffix = fp[2];
-      re = new RegExp(mgr0);
-      if (re.test(stem)) {
-        w = stem + step2list[suffix];
-      }
-    }
-
-    // Step 3
-    re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
-    if (re.test(w)) {
-      var fp = re.exec(w);
-      stem = fp[1];
-      suffix = fp[2];
-      re = new RegExp(mgr0);
-      if (re.test(stem)) {
-        w = stem + step3list[suffix];
-      }
-    }
-
-    // Step 4
-    re =
-      /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
-    re2 = /^(.+?)(s|t)(ion)$/;
-    if (re.test(w)) {
-      var fp = re.exec(w);
-      stem = fp[1];
-      re = new RegExp(mgr1);
-      if (re.test(stem)) {
-        w = stem;
-      }
-    } else if (re2.test(w)) {
-      var fp = re2.exec(w);
-      stem = fp[1] + fp[2];
-      re2 = new RegExp(mgr1);
-      if (re2.test(stem)) {
-        w = stem;
-      }
-    }
-
-    // Step 5
-    re = /^(.+?)e$/;
-    if (re.test(w)) {
-      var fp = re.exec(w);
-      stem = fp[1];
-      re = new RegExp(mgr1);
-      re2 = new RegExp(meq1);
-      re3 = new RegExp('^' + C + v + '[^aeiouwxy]$');
-      if (re.test(stem) || (re2.test(stem) && !re3.test(stem))) {
-        w = stem;
-      }
-    }
-
-    re = /ll$/;
-    re2 = new RegExp(mgr1);
-    if (re.test(w) && re2.test(w)) {
-      re = /.$/;
-      w = w.replace(re, '');
-    }
-
-    // and turn initial Y back to y
-
-    if (firstch == 'y') {
-      w = firstch.toLowerCase() + w.substr(1);
-    }
-
-    return w;
-  };
-})();
diff --git a/src/scripts/modules/string.js b/src/scripts/modules/string.js
deleted file mode 100644
index dea7142565..0000000000
--- a/src/scripts/modules/string.js
+++ /dev/null
@@ -1,83 +0,0 @@
-// @ts-check
-
-/**
- * Looks for a search within a string
- *
- * @param {string} string
- * @param {string} search
- * @returns
- */
-function contains(string, search) {
-  return string.indexOf(search) > -1;
-}
-
-/**
- * Looks for a search within a string
- *
- * @param {string} string
- * @param {string} search
- * @returns
- */
-function containsWord(string, search) {
-  return string.split(' ').indexOf(search) > -1;
-}
-
-/**
- *
- * @param {string} string
- * @param {string[]} terms
- * @returns
- */
-function highlight(string, terms) {
-  terms.forEach((term) => {
-    const regEx = new RegExp(term, 'ig');
-    const matches = string.match(regEx);
-    if (matches) {
-      string = string.replace(regEx, `<mark>${matches[0]}</mark>`);
-    }
-  });
-  return string;
-}
-
-/**
- * Simplifies a string to plain lower case, removing diacritic characters and hyphens
- * This means a search for "co-op" will be found in "COOP" and "Café" will be found in "cafe"
- * @param {string} string
- * @returns {string}
- */
-function sanitise(string) {
-  // @ts-ignore
-  if (String.prototype.normalize) {
-    // Reduces diacritic characters to plain characters
-    string
-      .trim()
-      .normalize('NFD')
-      .replace(/\./g, ' ')
-      .replace(/[\u0300-\u036f]/g, '')
-      .toLowerCase()
-      .replace(/-/g, '');
-  }
-
-  // Some browsers can't normalise strings
-  return string.trim().toLowerCase().replace(/-/g, '');
-}
-
-/**
- * Sets a minimum length for a search
- * @param {string} string
- * @returns
- */
-function isLongEnough(string) {
-  return string.length > 1;
-}
-
-/**
- *
- * @param {string} string
- * @returns {string[]}
- */
-function explode(string) {
-  return string.split(' ').filter(isLongEnough).map(sanitise);
-}
-
-export { contains, containsWord, sanitise, explode, highlight };
diff --git a/src/scripts/search-engine-legacy.ts b/src/scripts/search-engine-legacy.ts
deleted file mode 100644
index 398c758757..0000000000
--- a/src/scripts/search-engine-legacy.ts
+++ /dev/null
@@ -1,265 +0,0 @@
-// The current search, behind the `SearchEngine` seam: one build-time JSON of
-// titles, headings, descriptions, tags and an extracted keyword bag, scored in
-// the browser. The scoring is carried over unchanged from the results list this
-// replaces, so the overlay returns exactly what the old dropdown returned.
-//
-// Body text is not in the index, which is the ceiling on how good this can be
-// and the reason the Pagefind and Orama spikes exist.
-
-import { contains, explode, highlight, sanitise } from './modules/string.js';
-import { stemmer } from './modules/stemmer.js';
-import {
-  breadcrumbFrom,
-  classify,
-  countByFacet,
-  type SearchEngine,
-  type SearchResult,
-} from './search-engine';
-
-type Heading = { text: string; slug: string; safeText: string };
-
-type Entry = {
-  title: string;
-  safeTitle: string;
-  description: string;
-  keywords: string;
-  tags: string[];
-  headings: Heading[];
-  url: string;
-  depth: number;
-};
-
-type Scored = Entry & {
-  score: number;
-  foundWords: number;
-  foundTerms: string[];
-};
-
-// Phrase and per-term weights, verbatim from the list this replaces.
-const SCORING = {
-  depth: 5,
-  phraseTitle: 60,
-  phraseHeading: 20,
-  phraseDescription: 20,
-  termTitle: 40,
-  termHeading: 15,
-  termDescription: 15,
-  termTags: 15,
-  termKeywords: 15,
-};
-
-const WORD_SCORES = {
-  titleExact: 20,
-  titleContains: 15,
-  headingContains: 10,
-  contentContains: 1,
-};
-
-const RESULT_LIMIT = 30;
-
-async function getSynonyms(): Promise<Record<string, string>> {
-  try {
-    return (await import('./synonyms.js')).synonyms;
-  } catch {
-    return {};
-  }
-}
-
-/** Terms reach `highlight()` as a regular expression, so a query like `c++`
- *  would throw before anything was drawn. */
-function escapeForRegExp(term: string) {
-  return term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/** The excerpt is set as HTML so the `<mark>` around each hit survives. Escaping
- *  first means those marks are the only tags that can ever reach the DOM. */
-function escapeHtml(text: string) {
-  return text
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
-}
-
-async function expand(query: string) {
-  const synonyms = await getSynonyms();
-  const terms: string[] = [];
-
-  for (const term of explode(query)) {
-    const synonym = synonyms[term];
-    // An empty synonym is a stop word: drop the term rather than expanding it.
-    if (synonym === '') continue;
-    terms.push(term);
-    if (synonym) terms.push(...synonym.split(' '));
-  }
-
-  const stemmed = terms
-    .map((term) => stemmer(term))
-    .filter((stem) => !terms.includes(stem));
-
-  return { terms, allTerms: [...terms, ...stemmed] };
-}
-
-function score(entry: Entry, query: string, allTerms: string[]): Scored {
-  const scored: Scored = { ...entry, score: 0, foundWords: 0, foundTerms: [] };
-
-  // Phrase matches: the whole query, found intact
-  if (scored.safeTitle === query) scored.foundWords += WORD_SCORES.titleExact;
-
-  if (contains(scored.safeTitle, query)) {
-    scored.score += SCORING.phraseTitle;
-    scored.foundWords += WORD_SCORES.titleContains;
-  }
-
-  for (const heading of scored.headings) {
-    if (contains(heading.safeText, query)) {
-      scored.score += SCORING.phraseHeading;
-      scored.foundWords += WORD_SCORES.headingContains;
-    }
-  }
-
-  if (contains(scored.description, query)) {
-    scored.score += SCORING.phraseDescription;
-    scored.foundWords += WORD_SCORES.contentContains;
-  }
-
-  // Term matches: each word of the query, found anywhere
-  for (const term of allTerms) {
-    let found = false;
-
-    if (contains(scored.safeTitle, term)) {
-      scored.score += SCORING.termTitle;
-      scored.foundWords += WORD_SCORES.headingContains / 2;
-      found = true;
-    }
-
-    for (const heading of scored.headings) {
-      if (contains(heading.safeText, term)) {
-        scored.score += SCORING.termHeading;
-        found = true;
-      }
-    }
-
-    if (contains(scored.description, term)) {
-      scored.score += SCORING.termDescription;
-      found = true;
-    }
-
-    for (const tag of scored.tags) {
-      if (contains(tag, term)) {
-        scored.score += SCORING.termTags;
-        found = true;
-      }
-    }
-
-    if (contains(scored.keywords, term)) {
-      scored.score += SCORING.termKeywords;
-      found = true;
-    }
-
-    if (found) {
-      scored.foundWords++;
-      if (!scored.foundTerms.includes(term)) scored.foundTerms.push(term);
-    }
-  }
-
-  // Shallow pages win ties: /docs/features over /docs/features/a/b
-  if (scored.score > 0) {
-    if (scored.depth < 5) {
-      scored.score += SCORING.depth;
-      scored.foundWords++;
-    }
-    if (scored.depth < 4) {
-      scored.score += SCORING.depth;
-      scored.foundWords++;
-    }
-  }
-
-  return scored;
-}
-
-function byRelevance(a: Scored, b: Scored) {
-  if (b.foundTerms.length !== a.foundTerms.length) {
-    return b.foundTerms.length - a.foundTerms.length;
-  }
-  if (b.foundWords !== a.foundWords) return b.foundWords - a.foundWords;
-  return b.score - a.score;
-}
-
-export function legacyEngine(indexUrl: string): SearchEngine {
-  // One fetch, on the first search rather than on page load, shared by every
-  // search after it. The old list fetched 1.86MB the moment the script ran.
-  let loading: Promise<Entry[]> | null = null;
-
-  function load() {
-    loading ??= fetch(indexUrl)
-      .then((response) => response.json())
-      .then((data: Record<string, any>[]) =>
-        data.map((item) => ({
-          title: item.title,
-          safeTitle: sanitise(item.title),
-          description: item.description ?? '',
-          keywords: item.keywords ?? '',
-          tags: (item.tags ?? []).map((tag: string) => sanitise(tag)),
-          headings: (item.headings ?? []).map((heading: Heading) => ({
-            ...heading,
-            safeText: sanitise(heading.text),
-          })),
-          url: item.url,
-          depth: item.url.match(/\//g)?.length ?? 0,
-        }))
-      )
-      .catch(() => {
-        // A failed load must not poison every later search.
-        loading = null;
-        return [] as Entry[];
-      });
-
-    return loading;
-  }
-
-  return {
-    warm: load,
-
-    async search(rawQuery, facet) {
-      // Chained words are joined, so `System.Text` searches as `systemtext`.
-      const query = sanitise(rawQuery.replace(/\./g, ' '));
-      if (!query) return { results: [], counts: countByFacet([]) };
-
-      const [haystack, { terms, allTerms }] = await Promise.all([
-        load(),
-        expand(query),
-      ]);
-
-      const highlightTerms = terms.map(escapeForRegExp);
-
-      const matched = haystack
-        .map((entry) => score(entry, query, allTerms))
-        .filter((entry) => entry.score > 0)
-        .sort(byRelevance)
-        .slice(0, RESULT_LIMIT)
-        .map((entry): SearchResult => {
-          // The index stores absolute production URLs, and every entry in it is
-          // a page of this site. Keeping only the path is what makes a result
-          // stay on whatever host is serving it — an ephemeral environment or
-          // localhost would otherwise send you to production.
-          const path = new URL(entry.url, window.location.origin).pathname;
-
-          return {
-            url: path,
-            title: entry.title,
-            excerpt: highlight(escapeHtml(entry.description), highlightTerms),
-            breadcrumb: breadcrumbFrom(path),
-            ...classify(path),
-          };
-        });
-
-      return {
-        counts: countByFacet(matched),
-        results:
-          facet && facet !== 'all'
-            ? matched.filter((result) => result.facet === facet)
-            : matched,
-      };
-    },
-  };
-}
diff --git a/src/scripts/search-engine-pagefind.ts b/src/scripts/search-engine-pagefind.ts
new file mode 100644
index 0000000000..5f60cf9fe5
--- /dev/null
+++ b/src/scripts/search-engine-pagefind.ts
@@ -0,0 +1,284 @@
+// Pagefind behind the `SearchEngine` seam.
+//
+// Two calls per search: `search()` returns lightweight stubs, then each result's
+// `data()` fetches its own fragment. Only the rows being rendered are fetched.
+
+import {
+  breadcrumbFrom,
+  classify,
+  type SearchEngine,
+  type SearchResult,
+} from './search-engine';
+
+const RESULT_LIMIT = 30;
+
+type PagefindSubResult = {
+  title: string;
+  /** Carries the heading's `#anchor` when the match is below the page title. */
+  url: string;
+  excerpt: string;
+};
+
+type PagefindFragment = {
+  url: string;
+  meta?: Record<string, string>;
+  excerpt: string;
+  sub_results?: PagefindSubResult[];
+};
+
+type PagefindResultStub = {
+  /** Pagefind's own relevance score, before any reordering here. */
+  score: number;
+  data(): Promise<PagefindFragment>;
+};
+
+type PagefindApi = {
+  options(config: Record<string, unknown>): Promise<void>;
+  filters(): Promise<Record<string, Record<string, number>>>;
+  preload(
+    query: string,
+    options?: { filters?: Record<string, string[]> }
+  ): void;
+  search(
+    query: string,
+    options?: { filters?: Record<string, string[]> }
+  ): Promise<{
+    results: PagefindResultStub[];
+    totalFilters: Record<string, Record<string, number>>;
+    unfilteredResultCount: number;
+  }>;
+};
+
+// Below this score, the best match is not a match. Pagefind ranks whatever
+// shares a few letters with the query and returns it as confidently as a real
+// hit, so a keyboard mash comes back with three security articles.
+//
+// Calibrated against the site's search log: the weakest genuine query, `cli`,
+// scores 9.5 and a keyboard mash 6.0. Eight suppressed 17 of the 33 terms with
+// no right answer and cost none of the 57 that had one. Applied to the top
+// result only, because the question is whether the query has an answer at all.
+//
+// Recalibrating: `options()` merges rather than replaces, so a run that did not
+// start from a clean page comes back with every score depressed.
+const MINIMUM_SCORE = 8;
+
+// Sections are their own rows, so they compete with pages for the reader's first
+// screenful. Three headings per page across thirty results made two thirds of
+// the list headings.
+/** Headings shown under one page. */
+const SECTION_LIMIT = 2;
+/** How many of the leading pages get headings at all. */
+const ROWS_WITH_SECTIONS = 3;
+
+/**
+ * The headings inside a result that matched on their own. Pagefind also returns a
+ * sub-result for the page itself, whose URL carries no anchor; that is the row's
+ * own link, so anchorless sub-results are dropped.
+ */
+function sectionsOf(fragment: PagefindFragment) {
+  return (fragment.sub_results ?? [])
+    .filter((sub) => sub.url.includes('#'))
+    .slice(0, SECTION_LIMIT)
+    .map((sub) => {
+      const { pathname, hash } = new URL(sub.url, window.location.origin);
+      // Path and anchor, no origin, so the row links the way a page row does.
+      // The anchor is the whole point of a section row.
+      return { title: sub.title, url: pathname + hash };
+    });
+}
+
+/** Lowercased, punctuation collapsed, so `Config as Code` matches `config as code`. */
+function comparable(text: string) {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9 ]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function segments(path: string) {
+  return path.split('/').filter(Boolean);
+}
+
+/**
+ * Reorders results so a section's own page beats the pages inside it. BM25 has
+ * no notion of a site's shape, so a bare section name otherwise ranks the pages
+ * inside the section above the section itself.
+ *
+ * A page the query *names* — by title or by the last segment of its URL — wins
+ * outright; the rest are ordered by score discounted per path segment.
+ * `data-pagefind-weight` alone measured as a no-op, so the attribute is no
+ * substitute for this.
+ *
+ * Reaches only the results already fetched, so a landing page ranked below
+ * `RESULT_LIMIT` on raw score cannot be rescued here.
+ */
+function byNameThenDepth<
+  T extends { score: number; url: string; title: string },
+>(hits: T[], term: string): T[] {
+  const wanted = comparable(term);
+  const DEPTH_PENALTY = 0.12;
+
+  const names = (hit: T) => {
+    const slug = segments(hit.url).pop() ?? '';
+    return comparable(hit.title) === wanted ||
+      comparable(slug.replace(/-/g, ' ')) === wanted
+      ? 1
+      : 0;
+  };
+
+  return hits
+    .map((hit) => ({
+      hit,
+      names: names(hit),
+      adjusted: hit.score / (1 + DEPTH_PENALTY * segments(hit.url).length),
+    }))
+    .sort((a, b) => b.names - a.names || b.adjusted - a.adjusted)
+    .map((entry) => entry.hit);
+}
+
+export function pagefindEngine(bundlePath: string): SearchEngine {
+  let loading: Promise<PagefindApi | null> | null = null;
+
+  function load() {
+    loading ??= import(/* @vite-ignore */ `${bundlePath}pagefind.js`)
+      .then(async (api: PagefindApi) => {
+        // Pagefind resolves its chunk URLs against this and prepends it to every
+        // result URL, so it has to match the prefix the index was built against.
+        await api.options({
+          basePath: bundlePath,
+          // The default is 30 words, which overruns the single line the result
+          // row gives it. Sized to the row instead.
+          excerptLength: 20,
+          ranking: {
+            // `trail` is the breadcrumb, derived from the URL, so every page
+            // under /docs/projects/ carries "Projects" and would otherwise match
+            // a search for it as well as the Projects page does. Demoting it is
+            // worth seven points of Success@5.
+            metaWeights: { title: 8, trail: 0.5 },
+          },
+        });
+        // The filter index is a separate chunk, and a search returns empty filter
+        // counts until it has been pulled down.
+        await api.filters();
+        return api;
+      })
+      .catch((error) => {
+        // A failed load must not poison every later search.
+        loading = null;
+        console.error('[docs-search] could not load the Pagefind index', error);
+        return null;
+      });
+
+    return loading;
+  }
+
+  return {
+    // 118KB of runtime and WASM up front; the per-query chunks stay on demand.
+    eager: true,
+    warm: load,
+
+    preload(query) {
+      const term = query.trim();
+      if (!term) return;
+      void load().then((api) => api?.preload(term));
+    },
+
+    async search(rawQuery, facet) {
+      const query = rawQuery.trim();
+      const empty = { results: [], counts: { all: 0 } };
+      if (!query) return empty;
+
+      const api = await load();
+      if (!api) return empty;
+
+      try {
+        const filters =
+          facet && facet !== 'all' ? { section: [facet] } : undefined;
+
+        // Two searches while a tab is selected: the filtered one supplies the
+        // rows, the unfiltered one says whether the query has any answer at all.
+        // Together, because a second await here would sit in front of every
+        // fragment fetch below it.
+        const [response, wholeCorpus] = await Promise.all([
+          api.search(query, { filters }),
+          filters ? api.search(query) : null,
+        ]);
+        const unfiltered = wholeCorpus ?? response;
+
+        // Counts come from the whole match set rather than the filtered one, so
+        // the strip keeps showing what the other tabs hold while one is selected.
+        const counts: Record<string, number> = {
+          all: response.unfilteredResultCount,
+          ...(response.totalFilters?.section ?? {}),
+        };
+
+        // Two questions, and the floor answers both. Nothing in the corpus is a
+        // real answer, so offer nothing and advertise nothing.
+        if ((unfiltered.results[0]?.score ?? 0) < MINIMUM_SCORE) return empty;
+
+        // The corpus answers it and this tab does not. Filtering only removes
+        // documents, so the survivors here can be accidents scoring far below
+        // anything the reader asked for. Keep the counts, so the strip still
+        // shows which tab holds the answer.
+        if ((response.results[0]?.score ?? 0) < MINIMUM_SCORE) {
+          return { results: [], counts };
+        }
+
+        const stubs = response.results.slice(0, RESULT_LIMIT);
+        const settled = await Promise.allSettled(
+          stubs.map((stub) => stub.data())
+        );
+
+        // A fragment that fails takes its own row out, not the whole result set.
+        // The score lives on the stub and the URL on the fragment, so the reorder
+        // needs the pair kept together.
+        const scored = settled.flatMap((outcome, at) => {
+          if (outcome.status === 'rejected') {
+            console.error(
+              '[docs-search] dropped a result whose fragment failed',
+              outcome.reason
+            );
+            return [];
+          }
+
+          const fragment = outcome.value;
+          const { pathname } = new URL(fragment.url, window.location.origin);
+          return [
+            {
+              fragment,
+              score: stubs[at].score,
+              url: pathname,
+              title: fragment.meta?.title ?? pathname,
+            },
+          ];
+        });
+
+        const results = byNameThenDepth(scored, query).map(
+          (hit, rank): SearchResult => ({
+            url: hit.url,
+            title: hit.title,
+            // Already carries <mark> around the hits, and Pagefind escapes the
+            // surrounding text itself.
+            excerpt: hit.fragment.excerpt,
+            breadcrumb: hit.fragment.meta?.trail
+              ? hit.fragment.meta.trail.split(' / ')
+              : breadcrumbFrom(hit.url),
+            sections:
+              rank < ROWS_WITH_SECTIONS
+                ? sectionsOf(hit.fragment)
+                : undefined,
+            ...classify(hit.url),
+          })
+        );
+
+        return { results, counts };
+      } catch (error) {
+        // The search itself failed, rather than one row of it. Rejecting would
+        // leave the previous query's rows under the new text.
+        console.error('[docs-search] search failed', error);
+        return empty;
+      }
+    },
+  };
+}
diff --git a/src/scripts/search-engine.ts b/src/scripts/search-engine.ts
index c8d1800b2b..47f5433b77 100644
--- a/src/scripts/search-engine.ts
+++ b/src/scripts/search-engine.ts
@@ -2,6 +2,14 @@
 // only ever talks to a `SearchEngine`, so swapping the index out is a matter of
 // supplying a different implementation.
 
+/** A heading inside a result that matched in its own right. */
+export type SearchSubResult = {
+  /** The heading text. */
+  title: string;
+  /** The page URL with the heading's `#anchor`, so the reader lands on it. */
+  url: string;
+};
+
 export type SearchResult = {
   url: string;
   title: string;
@@ -10,6 +18,12 @@ export type SearchResult = {
   breadcrumb: string[];
   kind: 'page' | 'command';
   facet: string;
+  /**
+   * Headings within the page that matched, deepest-matching first. Only an
+   * engine that indexes per-heading can fill this, so an empty array means the
+   * engine has nothing to say, never that the page has no headings.
+   */
+  sections?: SearchSubResult[];
 };
 
 export type SearchResponse = {
@@ -22,6 +36,17 @@ export type SearchEngine = {
   search(query: string, facet?: string): Promise<SearchResponse>;
   /** Optional: start loading the index before the first query needs it. */
   warm?(): void;
+  /**
+   * Whether `warm()` is cheap enough to run on page load rather than when the
+   * overlay opens. An engine that parses its whole index up front pays on every
+   * navigation, for every visitor including the majority who never search.
+   */
+  eager?: boolean;
+  /**
+   * Optional: fetch what this query will need without running it. Called while
+   * the reader is still typing, ahead of the debounced search.
+   */
+  preload?(query: string): void;
 };
 
 export type Facet = { key: string; label: string };
diff --git a/src/scripts/synonyms.js b/src/scripts/synonyms.js
deleted file mode 100644
index 489fc14133..0000000000
--- a/src/scripts/synonyms.js
+++ /dev/null
@@ -1,17 +0,0 @@
-const synonyms = {
-  // Keep me alphabetical
-  licence: 'license',
-  logs: 'log',
-  regex: 'regular expression',
-  // Join words
-  a: '',
-  and: '',
-  for: '',
-  if: '',
-  the: '',
-  to: '',
-  via: '',
-  with: '',
-};
-
-export { synonyms };
diff --git a/tests/api-page.spec.ts b/tests/api-page.spec.ts
index acfc11d5f6..9953fb89ee 100644
--- a/tests/api-page.spec.ts
+++ b/tests/api-page.spec.ts
@@ -60,14 +60,32 @@ test.describe('api page chrome', () => {
   });
 
   test('the section is kept out of the search index and the sitemap', async ({
+    page,
     request,
   }) => {
     // Temporary, alongside src/lib/underConstruction.ts - delete with it when
     // the API reference goes live.
-    const index = await (await request.get('/docs/search.json')).json();
-    expect(index.filter((entry) => entry.url.includes('/docs/api/'))).toEqual(
-      []
+    //
+    // Asked through the overlay rather than of an index file, because the index
+    // is now a directory of compressed chunks. What has to hold: a reader
+    // searching a word the API reference is full of must not be sent into it.
+    await page.goto('/docs/');
+    await page
+      .locator('input[data-docs-search-trigger]:visible')
+      .first()
+      .click();
+    await page.locator('[data-docs-search-input]').fill('accounts');
+
+    // The href assertion below passes on an empty list, so the visibility check
+    // is what makes this test mean anything. `accounts` names pages in the API
+    // reference *and* pages outside it, which is what keeps the list non-empty.
+    const results = page.locator('[data-docs-search-results] [role="option"]');
+    await expect(results.first()).toBeVisible({ timeout: 30_000 });
+
+    const hrefs = await results.evaluateAll((rows) =>
+      rows.map((row) => row.getAttribute('href') ?? '')
     );
+    expect(hrefs.filter((href) => href.includes('/docs/api/'))).toEqual([]);
 
     const sitemap = await (await request.get('/docs/sitemap.xml')).text();
     expect(sitemap).not.toContain('/docs/api/');