fix(docs): link agents to config reference data

2 files changed, 35 insertions, 14 deletions

diff --git a/website/scripts/check-built-docs.mjs b/website/scripts/check-built-docs.mjs
index 5bda738e..f6a2f199 100644
--- a/website/scripts/check-built-docs.mjs
+++ b/website/scripts/check-built-docs.mjs
@@ -82,23 +82,35 @@ if (!currentDocs?.tag || !currentDocs.source) {
 }
 const stableRawRoot = `https://raw.githubusercontent.com/herdrdev/herdr/${currentDocs.tag}`;
 const stableRawBase = `${stableRawRoot}/${currentDocs.source}`;
-const previewRawBase = `https://raw.githubusercontent.com/herdrdev/herdr/${versions.preview.commit}/docs/next/website/src/content/docs`;
+const stableConfigReferenceUrl = `${stableRawRoot}/${currentDocs.source.replace(/\/content\/docs$/, '/data/config-reference.json')}`;
+const previewRawRoot = `https://raw.githubusercontent.com/herdrdev/herdr/${versions.preview.commit}`;
+const previewRawBase = `${previewRawRoot}/docs/next/website/src/content/docs`;
+const previewConfigReferenceUrl = `${previewRawRoot}/docs/next/website/src/data/config-reference.json`;
 assertIncludes(llmsIndex, `Current stable release: ${versions.current}.`);
 assertIncludes(llmsIndex, `${stableRawBase}/quick-start.mdx`);
-assertIncludes(
-  llmsIndex,
-  `${stableRawRoot}/${currentDocs.source.replace(/\/content\/docs$/, '/data/config-reference.json')}`,
-);
+assertIncludes(llmsIndex, `- [Config reference](${stableConfigReferenceUrl})`);
+assertIncludes(llmsIndex, '## Using the config reference');
+assertIncludes(llmsIndex, "jq --arg key 'ui.sidebar_width'");
+if (llmsIndex.includes(`${stableRawBase}/config-reference.mdx`)) {
+  throw new Error('llms.txt must link to config reference data instead of the unrendered MDX component');
+}
 assertIncludes(llmsIndex, 'https://herdr.dev/llms-small.txt');
 assertIncludes(llmsIndex, 'https://herdr.dev/llms-full.txt');
 assertIncludes(llmsIndex, 'https://herdr.dev/agent-guide.md');
 assertIncludes(llmsIndex, 'https://herdr.dev/llms-preview.txt');
 assertIncludes(llmsPreview, `Active preview build: ${versions.preview.build_id}`);
 assertIncludes(llmsPreview, `${previewRawBase}/quick-start.mdx`);
+assertIncludes(llmsPreview, `- [Config reference](${previewConfigReferenceUrl})`);
+if (llmsPreview.includes(`${previewRawBase}/config-reference.mdx`)) {
+  throw new Error('llms-preview.txt must link to config reference data instead of the unrendered MDX component');
+}
 assertIncludes(llmsPreview, 'https://herdr.dev/llms.txt');
 const stablePageLinks = llmsIndex
   .split('\n')
-  .filter((line) => line.includes(`](${stableRawBase}/`));
+  .filter(
+    (line) =>
+      line.includes(`](${stableRawBase}/`) || line.includes(`](${stableConfigReferenceUrl})`),
+  );
 if (stablePageLinks.length !== versions.scopes.stable.locales.root.length) {
   throw new Error(
     `llms.txt lists ${stablePageLinks.length} stable pages, expected ${versions.scopes.stable.locales.root.length}`,
@@ -106,7 +118,10 @@ if (stablePageLinks.length !== versions.scopes.stable.locales.root.length) {
 }
 const previewPageLinks = llmsPreview
   .split('\n')
-  .filter((line) => line.includes(`](${previewRawBase}/`));
+  .filter(
+    (line) =>
+      line.includes(`](${previewRawBase}/`) || line.includes(`](${previewConfigReferenceUrl})`),
+  );
 if (previewPageLinks.length !== versions.scopes.preview.locales.root.length) {
   throw new Error(
     `llms-preview.txt lists ${previewPageLinks.length} preview pages, expected ${versions.scopes.preview.locales.root.length}`,
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,
     '',