@@ -12,6 +12,9 @@ name: Sync Algolia crawler config
 #   - Variable ALGOLIA_CRAWLER_ID
 #   - Secret   ALGOLIA_CRAWLER_USER_ID
 #   - Secret   ALGOLIA_CRAWLER_API_KEY
+#   - Secret   ALGOLIA_ADMIN_API_KEY  (optional — needed to push
+#              initialIndexSettings to existing indices, since the crawler
+#              only applies them on index creation)
 
 on:
   push:
@@ -42,6 +45,7 @@ jobs:
           ALGOLIA_CRAWLER_ID: ${{ vars.ALGOLIA_CRAWLER_ID }}
           ALGOLIA_CRAWLER_USER_ID: ${{ secrets.ALGOLIA_CRAWLER_USER_ID }}
           ALGOLIA_CRAWLER_API_KEY: ${{ secrets.ALGOLIA_CRAWLER_API_KEY }}
+          ALGOLIA_ADMIN_API_KEY: ${{ secrets.ALGOLIA_ADMIN_API_KEY }}
           # On push, skip the reindex here — algolia-reindex.yml fires after the
           # Vercel production deploy so pages are live before the crawl starts.
           # On workflow_dispatch there is no pending deploy, so reindex immediately.
 
@@ -50,6 +50,20 @@ dashboard and in CI secrets. The workflows need:
 | `ALGOLIA_CRAWLER_ID` | Variable | Crawler dashboard URL |
 | `ALGOLIA_CRAWLER_USER_ID` | Secret | Crawler → API credentials |
 | `ALGOLIA_CRAWLER_API_KEY` | Secret | Crawler → API credentials |
+| `ALGOLIA_ADMIN_API_KEY` | Secret | Algolia dashboard → API Keys → Admin API Key |
+
+### Why `ALGOLIA_ADMIN_API_KEY` is needed
+
+The crawler's `initialIndexSettings` block is only applied when the crawler
+*creates* an index. Once the production index exists, later edits to that
+block (for example, tuning `removeWordsIfNoResults` to relax matching for
+long agent-style queries) never reach the live index through the crawler
+API alone, and the no-result rate stays elevated for those queries.
+
+`scripts/sync-crawler-config.ts` therefore also pushes `initialIndexSettings`
+to each live index via the Search API's `PUT /1/indexes/{name}/settings`
+using this key. Without the key the config still syncs and a reindex still
+runs, but the index-settings step is skipped with a warning.
 
 The public search credentials used by the frontend widget
 (`app/_components/algolia-search.tsx`) are separate `NEXT_PUBLIC_ALGOLIA_*`
 
@@ -63,6 +63,10 @@ export const crawlerConfig = {
       },
     },
   ],
+  // The crawler applies `initialIndexSettings` only when it *creates* an
+  // index, so edits below never reach an existing production index by
+  // themselves. `scripts/sync-crawler-config.ts` also pushes these via the
+  // Search API when ALGOLIA_ADMIN_API_KEY is set; see algolia/README.md.
   initialIndexSettings: {
     docs_arcade_dev_bjb8pbsq9t_docsearch: {
       distinct: true,
 
@@ -12,10 +12,20 @@
  * here (the config file doesn't store it either). Updating config doesn't crawl
  * on its own, so we POST /reindex afterwards to apply the new config.
  *
+ * `initialIndexSettings` in the crawler config only applies when the crawler
+ * *creates* the index — it is not re-applied to an existing index on subsequent
+ * crawls. To keep the live production index in sync with the versioned settings,
+ * we also push them via the Search API's PUT /1/indexes/{name}/settings when
+ * ALGOLIA_ADMIN_API_KEY is available. Without that key, we skip with a warning
+ * and the crawler config still updates normally.
+ *
  * Requires these env vars (provided as CI secrets/variables):
  *   ALGOLIA_CRAWLER_ID
  *   ALGOLIA_CRAWLER_USER_ID
  *   ALGOLIA_CRAWLER_API_KEY
+ *
+ * Optional:
+ *   ALGOLIA_ADMIN_API_KEY  (needed to apply index settings to existing indices)
  */
 
 import { Buffer } from "node:buffer";
@@ -24,6 +34,7 @@ import { crawlerConfig } from "../algolia/crawler-config.js";
 const CRAWLER_ID = process.env.ALGOLIA_CRAWLER_ID;
 const USER_ID = process.env.ALGOLIA_CRAWLER_USER_ID;
 const API_KEY = process.env.ALGOLIA_CRAWLER_API_KEY;
+const ADMIN_API_KEY = process.env.ALGOLIA_ADMIN_API_KEY;
 
 if (!(CRAWLER_ID && USER_ID && API_KEY)) {
   console.error(
@@ -64,6 +75,42 @@ if (!configResponse.ok) {
 }
 console.log("Crawler config updated.");
 
+// Push initialIndexSettings to each live index via the Search API. The crawler
+// only applies these when the index is first created, so a settings change
+// (e.g. removeWordsIfNoResults) never reaches an existing production index
+// otherwise, and no-result rates stay high for compound agent queries.
+if (ADMIN_API_KEY) {
+  const settingsByIndex = crawlerConfig.initialIndexSettings ?? {};
+  for (const [indexName, settings] of Object.entries(settingsByIndex)) {
+    const response = await fetch(
+      `https://${crawlerConfig.appId}-dsn.algolia.net/1/indexes/${encodeURIComponent(indexName)}/settings`,
+      {
+        method: "PUT",
+        headers: {
+          "X-Algolia-Application-Id": crawlerConfig.appId,
+          "X-Algolia-API-Key": ADMIN_API_KEY,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(settings),
+      }
+    );
+    if (!response.ok) {
+      console.error(
+        `Index settings update failed for ${indexName} (${response.status}): ${await response.text()}`
+      );
+      process.exit(1);
+    }
+    console.log(`Index settings pushed to ${indexName}.`);
+  }
+} else {
+  console.warn(
+    "ALGOLIA_ADMIN_API_KEY not set — skipping Search API settings push. " +
+      "The crawler's initialIndexSettings only apply on index creation, so " +
+      "changes to those fields will not reach the existing production index " +
+      "until this key is provided. See algolia/README.md."
+  );
+}
+
 if (process.env.SKIP_REINDEX === "true") {
   console.log("Skipping reindex — will be triggered after deployment.");
   process.exit(0);