From b3166d794e758c074d706fcab5864a9f4e7e2c2c Mon Sep 17 00:00:00 2001
From: Ogulcan Celik <ogulcancelik@gmail.com>
Date: Tue, 18 Aug 2026 00:31:15 +0300
Subject: fix(docs): link agents to config reference data

---
 website/scripts/prepare-docs.mjs | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

(limited to 'website/scripts/prepare-docs.mjs')

diff --git a/website/scripts/prepare-docs.mjs b/website/scripts/prepare-docs.mjs
index 55a463bb..14d62abc 100644
--- a/website/scripts/prepare-docs.mjs
+++ b/website/scripts/prepare-docs.mjs
@@ -261,24 +261,30 @@ async function writeAgentDocsIndex({
   if (configDataPath === repositoryPath) {
     throw new Error(`cannot derive config reference path from ${repositoryPath}`);
   }
+  const configDataUrl = `${rawRoot}/${configDataPath}`;
 
   const lines = [
     `# ${heading}`,
     '',
     `> ${summary}`,
     '',
-    'Open only the pages relevant to the current task. Links return raw MDX from the exact documented source revision. For another topic, return to this index instead of following `/docs/` links inside a page, which serve human-facing HTML.',
+    'Open only the pages relevant to the current task. Links return raw source files from the exact documented revision. For another topic, return to this index instead of following `/docs/` links inside a page, which serve human-facing HTML.',
     '',
     '## Documentation',
     '',
-    ...pages.map(
-      ({ title, description, path }) =>
-        `- [${title}](${rawBase}/${path})${description ? `: ${description}` : ''}`,
-    ),
+    ...pages.map(({ title, description, path }) => {
+      const url = /^config-reference\.mdx?$/.test(path) ? configDataUrl : `${rawBase}/${path}`;
+      return `- [${title}](${url})${description ? `: ${description}` : ''}`;
+    }),
+    '',
+    '## Using the config reference',
     '',
-    '## Generated reference data',
+    'The Config reference link above is a large structured JSON file. When command tools are available, fetch and filter it by exact key instead of loading the whole file:',
     '',
-    `- [Config reference data](${rawRoot}/${configDataPath}): every canonical config.toml key, type, default, and description`,
+    '```sh',
+    `curl -fsSL '${configDataUrl}' | jq --arg key 'ui.sidebar_width' \\`,
+    "  '.sections[].keys[] | select(.key == $key)'",
+    '```',
     '',
     ...extraSections,
     '',
-- 
cgit v1.2.3