From 4598e8783bc6edab999f5bbd3c170e7202ba3329 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Tue, 4 Nov 2025 11:02:49 +0000
Subject: [PATCH 01/43] Add new docContet.js util

---
 .../AiToolbar/actions/actionRegistry.js       | 22 +++---
 .../AiToolbar/actions/copyMarkdown.js         | 71 ++++++------------
 .../AiToolbar/config/aiToolsConfig.js         | 38 ++++++++--
 .../components/AiToolbar/utils/docContext.js  | 75 +++++++++++++++++++
 4 files changed, 141 insertions(+), 65 deletions(-)
 create mode 100644 docusaurus/src/components/AiToolbar/utils/docContext.js

diff --git a/docusaurus/src/components/AiToolbar/actions/actionRegistry.js b/docusaurus/src/components/AiToolbar/actions/actionRegistry.js
index 49a327e25e..e5a962e219 100644
--- a/docusaurus/src/components/AiToolbar/actions/actionRegistry.js
+++ b/docusaurus/src/components/AiToolbar/actions/actionRegistry.js
@@ -1,26 +1,28 @@
 import { copyMarkdownAction } from './copyMarkdown';
 import { navigateAction } from './navigate';
+import { openLLMAction } from './openLLM';
 
 // Central registry of all available actions
 export const actionHandlers = {
   'copy-markdown': copyMarkdownAction,
-  'navigate': navigateAction,
+  navigate: navigateAction,
+  'open-llm': openLLMAction,
 };
 
 // Main function to execute an action
 export const executeAction = async (actionConfig, additionalContext = {}) => {
   const handler = actionHandlers[actionConfig.actionType];
-  
+
   if (!handler) {
     console.warn(`Unknown action type: ${actionConfig.actionType}`);
     return;
   }
-  
+
   const context = {
     ...actionConfig, // url, etc.
     ...additionalContext, // docId, docPath, updateActionState, closeDropdown, etc.
   };
-  
+
   try {
     await handler(context);
   } catch (error) {
@@ -38,28 +40,28 @@ export const getActionDisplay = (actionId, currentState = 'idle') => {
             icon: 'circle-notch',
             iconClasses: 'ph-bold spinning',
             label: 'Copying...',
-            className: 'ai-toolbar-button--loading'
+            className: 'ai-toolbar-button--loading',
           };
         case 'success':
           return {
             icon: 'check-circle',
             iconClasses: 'ph-fill',
             label: 'Copied!',
-            className: 'ai-toolbar-button--success'
+            className: 'ai-toolbar-button--success',
           };
         case 'error':
           return {
             icon: 'warning-circle',
             iconClasses: 'ph-fill',
             label: 'Copy failed',
-            className: 'ai-toolbar-button--error'
+            className: 'ai-toolbar-button--error',
           };
         default: // 'idle'
           return {
             icon: 'copy',
             iconClasses: 'ph-bold',
             label: 'Copy Markdown',
-            className: 'ai-toolbar-button--idle'
+            className: 'ai-toolbar-button--idle',
           };
       }
     default:
@@ -68,7 +70,7 @@ export const getActionDisplay = (actionId, currentState = 'idle') => {
         icon: 'question',
         iconClasses: 'ph-bold',
         label: 'Unknown',
-        className: 'ai-toolbar-button--idle'
+        className: 'ai-toolbar-button--idle',
       };
   }
-};
\ No newline at end of file
+};
diff --git a/docusaurus/src/components/AiToolbar/actions/copyMarkdown.js b/docusaurus/src/components/AiToolbar/actions/copyMarkdown.js
index f3580738d7..037a224b08 100644
--- a/docusaurus/src/components/AiToolbar/actions/copyMarkdown.js
+++ b/docusaurus/src/components/AiToolbar/actions/copyMarkdown.js
@@ -1,62 +1,39 @@
+import { resolveDocContext, getRawMarkdownUrl } from '../utils/docContext';
+
 export const copyMarkdownAction = async (context) => {
   const { docId, docPath, updateActionState } = context;
-  
+
   try {
-    updateActionState('copy-markdown', 'loading');
-    
-    // Helper functions to get current document info from URL (reused from CopyMarkdownButton)
-    const getCurrentDocId = () => {
-      if (typeof window === 'undefined') return null;
-      const path = window.location.pathname;
-      // Remove leading/trailing slashes and split
-      const segments = path.replace(/^\/|\/$/g, '').split('/');
-      // For paths like /cms/api/rest or /cloud/getting-started/intro
-      if (segments.length >= 2) {
-        return segments.join('/');
-      }
-      return null;
-    };
-
-    const getCurrentDocPath = () => {
-      if (typeof window === 'undefined') return null;
-      const path = window.location.pathname;
-      // Convert URL path to docs file path
-      const cleanPath = path.replace(/^\/|\/$/g, '');
-      return cleanPath ? `docs/${cleanPath}.md` : null;
-    };
-
-    // Use props or try to get from current URL
-    const currentDocId = docId || getCurrentDocId();
-    const currentDocPath = docPath || getCurrentDocPath();
-    
-    if (!currentDocId && !currentDocPath) {
+    if (updateActionState) {
+      updateActionState('copy-markdown', 'loading');
+    }
+
+    const { docId: resolvedDocId, docPath: resolvedDocPath } = resolveDocContext(docId, docPath);
+    const markdownUrl = getRawMarkdownUrl({ docId: resolvedDocId, docPath: resolvedDocPath });
+
+    if (!markdownUrl) {
       throw new Error('Unable to determine document path');
     }
 
-    // Build the raw markdown URL from GitHub
-    const baseUrl = 'https://raw.githubusercontent.com/strapi/documentation/main/docusaurus';
-    const markdownUrl = currentDocPath 
-      ? `${baseUrl}/${currentDocPath}` 
-      : `${baseUrl}/docs/${currentDocId}.md`;
-    
-    // Fetch the raw markdown content
     const response = await fetch(markdownUrl);
-    
+
     if (!response.ok) {
       throw new Error(`Failed to fetch markdown: ${response.status}`);
     }
-    
+
     const markdownContent = await response.text();
-    
-    // Copy to clipboard
     await navigator.clipboard.writeText(markdownContent);
-    
-    updateActionState('copy-markdown', 'success');
-    setTimeout(() => updateActionState('copy-markdown', 'idle'), 3000);
-    
+
+    if (updateActionState) {
+      updateActionState('copy-markdown', 'success');
+      setTimeout(() => updateActionState('copy-markdown', 'idle'), 3000);
+    }
   } catch (error) {
     console.error('Error copying markdown:', error);
-    updateActionState('copy-markdown', 'error');
-    setTimeout(() => updateActionState('copy-markdown', 'idle'), 3000);
+
+    if (updateActionState) {
+      updateActionState('copy-markdown', 'error');
+      setTimeout(() => updateActionState('copy-markdown', 'idle'), 3000);
+    }
   }
-};
\ No newline at end of file
+};
diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index 0b84e435fb..9f0bbc584c 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -1,13 +1,13 @@
 export const aiToolsConfig = {
   primaryActionId: 'copy-markdown',
-  
+
   actions: [
     {
       id: 'copy-markdown',
       label: 'Copy Markdown',
       description: 'Copy the raw markdown content of this page',
       icon: 'copy',
-      actionType: 'copy-markdown'
+      actionType: 'copy-markdown',
     },
     {
       id: 'view-llms',
@@ -15,15 +15,37 @@ export const aiToolsConfig = {
       description: 'Lightweight version for AI models',
       icon: 'file-text',
       actionType: 'navigate',
-      url: '/llms.txt'
+      url: '/llms.txt',
     },
     {
       id: 'view-llms-full',
-      label: 'View LLMs-full.txt', 
+      label: 'View LLMs-full.txt',
       description: 'Complete documentation for AI models',
       icon: 'file-text',
       actionType: 'navigate',
-      url: '/llms-full.txt'
-    }
-  ]
-};
\ No newline at end of file
+      url: '/llms-full.txt',
+    },
+    {
+      id: 'open-chatgpt',
+      label: 'Open with ChatGPT',
+      description: 'Open ChatGPT with a prompt about this page',
+      icon: 'chat-circle-dots',
+      actionType: 'open-llm',
+      targetUrl: 'https://chat.openai.com/',
+      promptTemplate: 'Read from {{url}} so I can ask questions about it.',
+      promptParam: 'prompt',
+      openIn: '_blank',
+    },
+    {
+      id: 'open-claude',
+      label: 'Open with Claude',
+      description: 'Open Claude with a prompt about this page',
+      icon: 'sparkle',
+      actionType: 'open-llm',
+      targetUrl: 'https://claude.ai/new',
+      promptTemplate: 'Read from {{url}} so I can ask questions about it.',
+      promptParam: 'query',
+      openIn: '_blank',
+    },
+  ],
+};
diff --git a/docusaurus/src/components/AiToolbar/utils/docContext.js b/docusaurus/src/components/AiToolbar/utils/docContext.js
new file mode 100644
index 0000000000..fefeb6e954
--- /dev/null
+++ b/docusaurus/src/components/AiToolbar/utils/docContext.js
@@ -0,0 +1,75 @@
+const RAW_BASE_URL = 'https://raw.githubusercontent.com/strapi/documentation/main/docusaurus';
+
+const isBrowser = () => typeof window !== 'undefined';
+
+export const getCurrentDocId = () => {
+  if (!isBrowser()) return null;
+  const path = window.location.pathname;
+  const segments = path.replace(/^\/|\/$/g, '').split('/');
+  return segments.length >= 2 ? segments.join('/') : null;
+};
+
+export const getCurrentDocPath = () => {
+  if (!isBrowser()) return null;
+  const path = window.location.pathname;
+  const cleanPath = path.replace(/^\/|\/$/g, '');
+  return cleanPath ? `docs/${cleanPath}.md` : null;
+};
+
+export const getCurrentDocUrl = () => {
+  if (!isBrowser()) return null;
+  return window.location.href;
+};
+
+export const resolveDocContext = (docId, docPath) => {
+  return {
+    docId: docId || getCurrentDocId(),
+    docPath: docPath || getCurrentDocPath(),
+  };
+};
+
+export const getRawMarkdownUrl = ({ docId, docPath }) => {
+  if (docPath) {
+    return `${RAW_BASE_URL}/${docPath}`;
+  }
+  if (docId) {
+    return `${RAW_BASE_URL}/docs/${docId}.md`;
+  }
+  return null;
+};
+
+const TEMPLATE_PATTERN = /\{\{\s*(\w+)\s*\}\}/g;
+
+export const applyTemplate = (template, values) => {
+  if (typeof template !== 'string') return '';
+  return template.replace(TEMPLATE_PATTERN, (match, key) => {
+    const value = values[key];
+    return value == null ? '' : String(value);
+  });
+};
+
+export const buildPromptFromTemplate = (template, extraValues = {}) => {
+  const values = {
+    url: getCurrentDocUrl(),
+    docId: getCurrentDocId(),
+    docPath: getCurrentDocPath(),
+    ...extraValues,
+  };
+  return applyTemplate(template, values);
+};
+
+export const buildUrlWithPrompt = ({ targetUrl, prompt, promptParam = 'prompt' }) => {
+  if (!targetUrl) return null;
+  if (!promptParam || !prompt) return targetUrl;
+
+  try {
+    const url = new URL(targetUrl, isBrowser() ? window.location.origin : undefined);
+    url.searchParams.set(promptParam, prompt);
+    return url.toString();
+  } catch (error) {
+    const encodedPrompt = encodeURIComponent(prompt);
+    const encodedParam = encodeURIComponent(promptParam);
+    const separator = targetUrl.includes('?') ? '&' : '?';
+    return `${targetUrl}${separator}${encodedParam}=${encodedPrompt}`;
+  }
+};

From 6f0bde0e9e681aea2602a2541ae54a6d159a4bd3 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Tue, 4 Nov 2025 11:03:35 +0000
Subject: [PATCH 02/43] Add new openLLM action

---
 .../components/AiToolbar/actions/openLLM.js   | 31 +++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 docusaurus/src/components/AiToolbar/actions/openLLM.js

diff --git a/docusaurus/src/components/AiToolbar/actions/openLLM.js b/docusaurus/src/components/AiToolbar/actions/openLLM.js
new file mode 100644
index 0000000000..d8b6e037af
--- /dev/null
+++ b/docusaurus/src/components/AiToolbar/actions/openLLM.js
@@ -0,0 +1,31 @@
+import { buildPromptFromTemplate, buildUrlWithPrompt } from '../utils/docContext';
+
+const DEFAULT_PROMPT_TEMPLATE = 'Read from {{url}} so I can ask questions about it.';
+
+export const openLLMAction = (context) => {
+  const {
+    targetUrl,
+    promptTemplate = DEFAULT_PROMPT_TEMPLATE,
+    promptParam = 'prompt',
+    openIn = '_blank',
+    closeDropdown,
+  } = context;
+
+  if (!targetUrl) {
+    console.error('open-llm action requires a targetUrl');
+    return;
+  }
+
+  const prompt = buildPromptFromTemplate(promptTemplate);
+  const fullUrl = buildUrlWithPrompt({
+    targetUrl,
+    prompt,
+    promptParam,
+  });
+
+  window.open(fullUrl || targetUrl, openIn);
+
+  if (closeDropdown) {
+    closeDropdown();
+  }
+};

From 925e20d09387cdeea578117cf39545d0c6628559 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Tue, 4 Nov 2025 13:15:31 +0000
Subject: [PATCH 03/43] Swap generic icon for ChatGPT with the official OpenAI
 logo from PhosphorIcons library

---
 docusaurus/src/components/AiToolbar/config/aiToolsConfig.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index 9f0bbc584c..626c9316b0 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -29,7 +29,7 @@ export const aiToolsConfig = {
       id: 'open-chatgpt',
       label: 'Open with ChatGPT',
       description: 'Open ChatGPT with a prompt about this page',
-      icon: 'chat-circle-dots',
+      icon: 'open-ai-logo',
       actionType: 'open-llm',
       targetUrl: 'https://chat.openai.com/',
       promptTemplate: 'Read from {{url}} so I can ask questions about it.',

From c50254c59e325f44fa2d609bfbb86c481113185e Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Tue, 4 Nov 2025 13:46:37 +0000
Subject: [PATCH 04/43] Swap sparkle icon for Claude with a chat bubble icon,
 since sparkle is used for Kapa

---
 docusaurus/src/components/AiToolbar/config/aiToolsConfig.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index 626c9316b0..551e47769f 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -40,7 +40,7 @@ export const aiToolsConfig = {
       id: 'open-claude',
       label: 'Open with Claude',
       description: 'Open Claude with a prompt about this page',
-      icon: 'sparkle',
+      icon: 'circles-three-plus',
       actionType: 'open-llm',
       targetUrl: 'https://claude.ai/new',
       promptTemplate: 'Read from {{url}} so I can ask questions about it.',

From 04c94d798f53157adba6c44649554cd0ea04d3af Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Tue, 4 Nov 2025 14:23:08 +0000
Subject: [PATCH 05/43] Add prompt localization for the top 10 most used
 languages

---
 .../components/AiToolbar/actions/openLLM.js   | 10 +++-
 .../AiToolbar/config/aiToolsConfig.js         | 24 +++++++++
 .../components/AiToolbar/utils/docContext.js  | 49 +++++++++++++++++++
 3 files changed, 81 insertions(+), 2 deletions(-)

diff --git a/docusaurus/src/components/AiToolbar/actions/openLLM.js b/docusaurus/src/components/AiToolbar/actions/openLLM.js
index d8b6e037af..be34c7efee 100644
--- a/docusaurus/src/components/AiToolbar/actions/openLLM.js
+++ b/docusaurus/src/components/AiToolbar/actions/openLLM.js
@@ -1,4 +1,8 @@
-import { buildPromptFromTemplate, buildUrlWithPrompt } from '../utils/docContext';
+import {
+  buildPromptFromTemplate,
+  buildUrlWithPrompt,
+  selectLocalizedTemplate,
+} from '../utils/docContext';
 
 const DEFAULT_PROMPT_TEMPLATE = 'Read from {{url}} so I can ask questions about it.';
 
@@ -6,6 +10,7 @@ export const openLLMAction = (context) => {
   const {
     targetUrl,
     promptTemplate = DEFAULT_PROMPT_TEMPLATE,
+    localizedPromptTemplates = {},
     promptParam = 'prompt',
     openIn = '_blank',
     closeDropdown,
@@ -16,7 +21,8 @@ export const openLLMAction = (context) => {
     return;
   }
 
-  const prompt = buildPromptFromTemplate(promptTemplate);
+  const template = selectLocalizedTemplate(promptTemplate, localizedPromptTemplates);
+  const prompt = buildPromptFromTemplate(template);
   const fullUrl = buildUrlWithPrompt({
     targetUrl,
     prompt,
diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index 551e47769f..f9b8ff6dd5 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -33,6 +33,18 @@ export const aiToolsConfig = {
       actionType: 'open-llm',
       targetUrl: 'https://chat.openai.com/',
       promptTemplate: 'Read from {{url}} so I can ask questions about it.',
+      localizedPromptTemplates: {
+        en: 'Read from {{url}} so I can ask questions about it.',
+        zh: '請閱讀 {{url}} 的內容，以便我能就其提出問題。',
+        es: 'Lee {{url}} para que pueda hacer preguntas al respecto.',
+        hi: '{{url}} पढ़ें ताकि मैं इसके बारे में प्रश्न पूछ सकूँ।',
+        ar: 'اقرأ من {{url}} حتى أتمكن من طرح أسئلة حوله.',
+        fr: 'Lis {{url}} pour que je puisse poser des questions à son sujet.',
+        pt: 'Leia {{url}} para que eu possa fazer perguntas sobre isso.',
+        bn: '{{url}} থেকে পড়ুন যাতে আমি এর সম্পর্কে প্রশ্ন করতে পারি।',
+        ru: 'Прочитай {{url}}, чтобы я мог задавать вопросы по нему.',
+        ja: '{{url}} を読んで、質問できるようにしてください。',
+      },
       promptParam: 'prompt',
       openIn: '_blank',
     },
@@ -44,6 +56,18 @@ export const aiToolsConfig = {
       actionType: 'open-llm',
       targetUrl: 'https://claude.ai/new',
       promptTemplate: 'Read from {{url}} so I can ask questions about it.',
+      localizedPromptTemplates: {
+        en: 'Read from {{url}} so I can ask questions about it.',
+        zh: '請閱讀 {{url}} 的內容，以便我能就其提出問題。',
+        es: 'Lee {{url}} para que pueda hacer preguntas al respecto.',
+        hi: '{{url}} पढ़ें ताकि मैं इसके बारे में प्रश्न पूछ सकूँ।',
+        ar: 'اقرأ من {{url}} حتى أتمكن من طرح أسئلة حوله.',
+        fr: 'Lis {{url}} pour que je puisse poser des questions à son sujet.',
+        pt: 'Leia {{url}} para que eu possa fazer perguntas sobre isso.',
+        bn: '{{url}} থেকে পড়ুন যাতে আমি এর সম্পর্কে প্রশ্ন করতে পারি।',
+        ru: 'Прочитай {{url}}, чтобы я мог задавать вопросы по нему.',
+        ja: '{{url}} を読んで、質問できるようにしてください。',
+      },
       promptParam: 'query',
       openIn: '_blank',
     },
diff --git a/docusaurus/src/components/AiToolbar/utils/docContext.js b/docusaurus/src/components/AiToolbar/utils/docContext.js
index fefeb6e954..9dfe028c86 100644
--- a/docusaurus/src/components/AiToolbar/utils/docContext.js
+++ b/docusaurus/src/components/AiToolbar/utils/docContext.js
@@ -73,3 +73,52 @@ export const buildUrlWithPrompt = ({ targetUrl, prompt, promptParam = 'prompt' }
     return `${targetUrl}${separator}${encodedParam}=${encodedPrompt}`;
   }
 };
+
+export const getUserLanguagePreferences = () => {
+  if (!isBrowser()) {
+    return [];
+  }
+
+  const languages = Array.isArray(navigator.languages) ? navigator.languages : [];
+  const fallback = navigator.language ? [navigator.language] : [];
+  const merged = [...languages, ...fallback];
+
+  return merged
+    .map((lang) => (typeof lang === 'string' ? lang.toLowerCase() : null))
+    .filter(Boolean);
+};
+
+export const selectLocalizedTemplate = (defaultTemplate, localizedTemplates = {}) => {
+  const userLanguages = getUserLanguagePreferences();
+  const availableLanguages = Object.keys(localizedTemplates);
+
+  const tryMatch = (languageTag) => {
+    if (!languageTag) {
+      return null;
+    }
+
+    if (localizedTemplates[languageTag]) {
+      return localizedTemplates[languageTag];
+    }
+
+    const base = languageTag.split('-')[0];
+    if (localizedTemplates[base]) {
+      return localizedTemplates[base];
+    }
+
+    return null;
+  };
+
+  for (const lang of userLanguages) {
+    const match = tryMatch(lang);
+    if (match) {
+      return match;
+    }
+  }
+
+  if (localizedTemplates.en) {
+    return localizedTemplates.en;
+  }
+
+  return defaultTemplate;
+};

From 68742d8f19bec9f3095f034a431e44e04bdaacfb Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Tue, 4 Nov 2025 15:21:46 +0000
Subject: [PATCH 06/43] Fix Claude incorrectly building translated prompt

---
 .../AiToolbar/config/aiToolsConfig.js         |  8 ++---
 .../components/AiToolbar/utils/docContext.js  | 31 +++++++++++++++----
 2 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index f9b8ff6dd5..2c95be80e0 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -35,7 +35,7 @@ export const aiToolsConfig = {
       promptTemplate: 'Read from {{url}} so I can ask questions about it.',
       localizedPromptTemplates: {
         en: 'Read from {{url}} so I can ask questions about it.',
-        zh: '請閱讀 {{url}} 的內容，以便我能就其提出問題。',
+        zh: '请阅读 {{url}} 的内容，以便我能就其提出问题。',
         es: 'Lee {{url}} para que pueda hacer preguntas al respecto.',
         hi: '{{url}} पढ़ें ताकि मैं इसके बारे में प्रश्न पूछ सकूँ।',
         ar: 'اقرأ من {{url}} حتى أتمكن من طرح أسئلة حوله.',
@@ -58,17 +58,17 @@ export const aiToolsConfig = {
       promptTemplate: 'Read from {{url}} so I can ask questions about it.',
       localizedPromptTemplates: {
         en: 'Read from {{url}} so I can ask questions about it.',
-        zh: '請閱讀 {{url}} 的內容，以便我能就其提出問題。',
+        zh: '请阅读 {{url}} 的内容，以便我能就其提出问题。',
         es: 'Lee {{url}} para que pueda hacer preguntas al respecto.',
         hi: '{{url}} पढ़ें ताकि मैं इसके बारे में प्रश्न पूछ सकूँ।',
         ar: 'اقرأ من {{url}} حتى أتمكن من طرح أسئلة حوله.',
         fr: 'Lis {{url}} pour que je puisse poser des questions à son sujet.',
         pt: 'Leia {{url}} para que eu possa fazer perguntas sobre isso.',
-        bn: '{{url}} থেকে পড়ুন যাতে আমি এর সম্পর্কে প্রশ্ন করতে পারি।',
+        bn: '{{url}} থেকে পড়ুন যাতে আমি এর সম্পর্কে प्रश्न করতে পারি।',
         ru: 'Прочитай {{url}}, чтобы я мог задавать вопросы по нему.',
         ja: '{{url}} を読んで、質問できるようにしてください。',
       },
-      promptParam: 'query',
+      promptParam: ['query', 'initial_message'],
       openIn: '_blank',
     },
   ],
diff --git a/docusaurus/src/components/AiToolbar/utils/docContext.js b/docusaurus/src/components/AiToolbar/utils/docContext.js
index 9dfe028c86..9bc7744677 100644
--- a/docusaurus/src/components/AiToolbar/utils/docContext.js
+++ b/docusaurus/src/components/AiToolbar/utils/docContext.js
@@ -58,19 +58,40 @@ export const buildPromptFromTemplate = (template, extraValues = {}) => {
   return applyTemplate(template, values);
 };
 
+const normalizeParams = (promptParam) => {
+  if (!promptParam) {
+    return [];
+  }
+
+  if (Array.isArray(promptParam)) {
+    return promptParam.filter(Boolean);
+  }
+
+  return [promptParam];
+};
+
 export const buildUrlWithPrompt = ({ targetUrl, prompt, promptParam = 'prompt' }) => {
   if (!targetUrl) return null;
-  if (!promptParam || !prompt) return targetUrl;
+  const params = normalizeParams(promptParam);
+
+  if (!prompt || params.length === 0) {
+    return targetUrl;
+  }
 
   try {
     const url = new URL(targetUrl, isBrowser() ? window.location.origin : undefined);
-    url.searchParams.set(promptParam, prompt);
+    params.forEach((param) => {
+      url.searchParams.set(param, prompt);
+    });
     return url.toString();
   } catch (error) {
     const encodedPrompt = encodeURIComponent(prompt);
-    const encodedParam = encodeURIComponent(promptParam);
+    const encodedParams = params.map((param) => encodeURIComponent(param));
     const separator = targetUrl.includes('?') ? '&' : '?';
-    return `${targetUrl}${separator}${encodedParam}=${encodedPrompt}`;
+    const query = encodedParams
+      .map((param) => `${param}=${encodedPrompt}`)
+      .join('&');
+    return `${targetUrl}${separator}${query}`;
   }
 };
 
@@ -90,8 +111,6 @@ export const getUserLanguagePreferences = () => {
 
 export const selectLocalizedTemplate = (defaultTemplate, localizedTemplates = {}) => {
   const userLanguages = getUserLanguagePreferences();
-  const availableLanguages = Object.keys(localizedTemplates);
-
   const tryMatch = (languageTag) => {
     if (!languageTag) {
       return null;

From 0fc185c3904711920729f5ee5b3b2e0add059c33 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Tue, 4 Nov 2025 16:06:10 +0000
Subject: [PATCH 07/43] Better fix Claude handling of locales by adding dual
 English + localized prompt

---
 .../src/components/AiToolbar/actions/openLLM.js       | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/docusaurus/src/components/AiToolbar/actions/openLLM.js b/docusaurus/src/components/AiToolbar/actions/openLLM.js
index be34c7efee..6a1d84556f 100644
--- a/docusaurus/src/components/AiToolbar/actions/openLLM.js
+++ b/docusaurus/src/components/AiToolbar/actions/openLLM.js
@@ -6,6 +6,14 @@ import {
 
 const DEFAULT_PROMPT_TEMPLATE = 'Read from {{url}} so I can ask questions about it.';
 
+const buildLocalizedPromptTemplate = (defaultTemplate, selectedTemplate) => {
+  if (!selectedTemplate || selectedTemplate === defaultTemplate) {
+    return defaultTemplate;
+  }
+
+  return `${selectedTemplate}\n\n---\n${defaultTemplate}`;
+};
+
 export const openLLMAction = (context) => {
   const {
     targetUrl,
@@ -21,7 +29,8 @@ export const openLLMAction = (context) => {
     return;
   }
 
-  const template = selectLocalizedTemplate(promptTemplate, localizedPromptTemplates);
+  const selectedTemplate = selectLocalizedTemplate(promptTemplate, localizedPromptTemplates);
+  const template = buildLocalizedPromptTemplate(DEFAULT_PROMPT_TEMPLATE, selectedTemplate);
   const prompt = buildPromptFromTemplate(template);
   const fullUrl = buildUrlWithPrompt({
     targetUrl,

From 98c95ccfe12331560d4d04b1b3d04c16d47d929d Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Tue, 4 Nov 2025 16:34:29 +0000
Subject: [PATCH 08/43] Ensure only Claude shows dual prompts

---
 .../components/AiToolbar/actions/openLLM.js    | 18 +++++++++++++-----
 .../AiToolbar/config/aiToolsConfig.js          |  3 ++-
 2 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/docusaurus/src/components/AiToolbar/actions/openLLM.js b/docusaurus/src/components/AiToolbar/actions/openLLM.js
index 6a1d84556f..d287d51a88 100644
--- a/docusaurus/src/components/AiToolbar/actions/openLLM.js
+++ b/docusaurus/src/components/AiToolbar/actions/openLLM.js
@@ -6,12 +6,19 @@ import {
 
 const DEFAULT_PROMPT_TEMPLATE = 'Read from {{url}} so I can ask questions about it.';
 
-const buildLocalizedPromptTemplate = (defaultTemplate, selectedTemplate) => {
-  if (!selectedTemplate || selectedTemplate === defaultTemplate) {
-    return defaultTemplate;
+const resolveTemplate = (defaultTemplate, selectedTemplate, includeDefaultPrompt) => {
+  const safeDefault = defaultTemplate || DEFAULT_PROMPT_TEMPLATE;
+  const safeSelected = selectedTemplate || safeDefault;
+
+  if (!includeDefaultPrompt) {
+    return safeSelected;
+  }
+
+  if (safeSelected === safeDefault) {
+    return safeDefault;
   }
 
-  return `${selectedTemplate}\n\n---\n${defaultTemplate}`;
+  return `${safeSelected}\n\n---\n${safeDefault}`;
 };
 
 export const openLLMAction = (context) => {
@@ -19,6 +26,7 @@ export const openLLMAction = (context) => {
     targetUrl,
     promptTemplate = DEFAULT_PROMPT_TEMPLATE,
     localizedPromptTemplates = {},
+    includeDefaultPrompt = false,
     promptParam = 'prompt',
     openIn = '_blank',
     closeDropdown,
@@ -30,7 +38,7 @@ export const openLLMAction = (context) => {
   }
 
   const selectedTemplate = selectLocalizedTemplate(promptTemplate, localizedPromptTemplates);
-  const template = buildLocalizedPromptTemplate(DEFAULT_PROMPT_TEMPLATE, selectedTemplate);
+  const template = resolveTemplate(promptTemplate, selectedTemplate, includeDefaultPrompt);
   const prompt = buildPromptFromTemplate(template);
   const fullUrl = buildUrlWithPrompt({
     targetUrl,
diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index 2c95be80e0..0a4c91ce79 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -64,10 +64,11 @@ export const aiToolsConfig = {
         ar: 'اقرأ من {{url}} حتى أتمكن من طرح أسئلة حوله.',
         fr: 'Lis {{url}} pour que je puisse poser des questions à son sujet.',
         pt: 'Leia {{url}} para que eu possa fazer perguntas sobre isso.',
-        bn: '{{url}} থেকে পড়ুন যাতে আমি এর সম্পর্কে प्रश्न করতে পারি।',
+        bn: '{{url}} থেকে পড়ুন যাতে నేను এর সম্পর্কে প্রশ্ন করতে পারি।',
         ru: 'Прочитай {{url}}, чтобы я мог задавать вопросы по нему.',
         ja: '{{url}} を読んで、質問できるようにしてください。',
       },
+      includeDefaultPrompt: true,
       promptParam: ['query', 'initial_message'],
       openIn: '_blank',
     },

From a68f7b08c9c8e85d39f84ed8529df51e64437f60 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <4233866+pwizla@users.noreply.github.com>
Date: Tue, 4 Nov 2025 18:03:15 +0100
Subject: [PATCH 09/43] =?UTF-8?q?Hide=20descriptions=20for=20Open=20with?=
 =?UTF-8?q?=E2=80=A6=20buttons?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docusaurus/src/components/AiToolbar/config/aiToolsConfig.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index 0a4c91ce79..c3f220097f 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -28,7 +28,7 @@ export const aiToolsConfig = {
     {
       id: 'open-chatgpt',
       label: 'Open with ChatGPT',
-      description: 'Open ChatGPT with a prompt about this page',
+      // description: 'Open ChatGPT with a prompt about this page',
       icon: 'open-ai-logo',
       actionType: 'open-llm',
       targetUrl: 'https://chat.openai.com/',
@@ -51,7 +51,7 @@ export const aiToolsConfig = {
     {
       id: 'open-claude',
       label: 'Open with Claude',
-      description: 'Open Claude with a prompt about this page',
+      // description: 'Open Claude with a prompt about this page',
       icon: 'circles-three-plus',
       actionType: 'open-llm',
       targetUrl: 'https://claude.ai/new',

From 83d7e8ac17ff8fc5301841f9f976ecef6779b904 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <4233866+pwizla@users.noreply.github.com>
Date: Tue, 4 Nov 2025 18:03:24 +0100
Subject: [PATCH 10/43] Update icon for Claude

---
 docusaurus/src/components/AiToolbar/config/aiToolsConfig.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index c3f220097f..be605dec24 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -52,7 +52,7 @@ export const aiToolsConfig = {
       id: 'open-claude',
       label: 'Open with Claude',
       // description: 'Open Claude with a prompt about this page',
-      icon: 'circles-three-plus',
+      icon: 'chat-teardrop-text',
       actionType: 'open-llm',
       targetUrl: 'https://claude.ai/new',
       promptTemplate: 'Read from {{url}} so I can ask questions about it.',

From 6766923d481c2282918388a19c8170bb382d6b6d Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Tue, 4 Nov 2025 17:18:16 +0000
Subject: [PATCH 11/43] Fix icon position when no description provided

---
 docusaurus/src/components/AiToolbar/AiToolbar.jsx |  4 ++--
 docusaurus/src/scss/ai-toolbar.scss               | 14 +++++++++++++-
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/docusaurus/src/components/AiToolbar/AiToolbar.jsx b/docusaurus/src/components/AiToolbar/AiToolbar.jsx
index c94964d621..401e15c5cd 100644
--- a/docusaurus/src/components/AiToolbar/AiToolbar.jsx
+++ b/docusaurus/src/components/AiToolbar/AiToolbar.jsx
@@ -124,7 +124,7 @@ const AiToolbar = () => {
               <button
                 key={action.id}
                 onClick={() => handleDropdownAction(action)}
-                className="ai-toolbar__dropdown-item"
+                className={`ai-toolbar__dropdown-item ${action.description ? '' : 'ai-toolbar__dropdown-item--no-description'}`}
                 title={action.description}
               >
                 <Icon 
@@ -151,4 +151,4 @@ const AiToolbar = () => {
   );
 };
 
-export default AiToolbar;
\ No newline at end of file
+export default AiToolbar;
diff --git a/docusaurus/src/scss/ai-toolbar.scss b/docusaurus/src/scss/ai-toolbar.scss
index 2a70410ff3..c32a3e1766 100644
--- a/docusaurus/src/scss/ai-toolbar.scss
+++ b/docusaurus/src/scss/ai-toolbar.scss
@@ -136,6 +136,12 @@
       flex-shrink: 0;
       color: var(--strapi-neutral-600);
     }
+
+    &--no-description {
+      .strapi-icons {
+        top: -8px;
+      }
+    }
   }
 
   &__dropdown-item-content {
@@ -247,10 +253,16 @@
       .strapi-icons {
         color: var(--strapi-neutral-600);
       }
+
+      &--no-description {
+        .strapi-icons {
+          top: -8px;
+        }
+      }
     }
 
     &__dropdown-item-description {
       color: var(--strapi-neutral-500);
     }
   }
-}
\ No newline at end of file
+}

From cdb8d766822a0a299aca201f045b336a15c14a85 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Tue, 4 Nov 2025 17:24:38 +0000
Subject: [PATCH 12/43] Try to accomodate for both description and no
 desciption scenarii for icons placement

---
 docusaurus/src/scss/ai-toolbar.scss | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docusaurus/src/scss/ai-toolbar.scss b/docusaurus/src/scss/ai-toolbar.scss
index c32a3e1766..6d5f8e7855 100644
--- a/docusaurus/src/scss/ai-toolbar.scss
+++ b/docusaurus/src/scss/ai-toolbar.scss
@@ -110,6 +110,7 @@
   }
 
   &__dropdown-item {
+    position: relative;
     display: flex;
     align-items: center;
     gap: 0.75rem;
@@ -133,13 +134,15 @@
     }
 
     .strapi-icons {
+      position: relative;
+      top: 1px;
       flex-shrink: 0;
       color: var(--strapi-neutral-600);
     }
 
     &--no-description {
       .strapi-icons {
-        top: -8px;
+        top: -7px;
       }
     }
   }
@@ -256,7 +259,7 @@
 
       &--no-description {
         .strapi-icons {
-          top: -8px;
+          top: -7px;
         }
       }
     }

From 6691a93713d455e56d18ed9cdb53e5c194001a39 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <4233866+pwizla@users.noreply.github.com>
Date: Tue, 4 Nov 2025 21:02:20 +0100
Subject: [PATCH 13/43] Revert "Try to accomodate for both description and no
 desciption scenarii for icons placement"

This reverts commit cdb8d766822a0a299aca201f045b336a15c14a85.
---
 docusaurus/src/scss/ai-toolbar.scss | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/docusaurus/src/scss/ai-toolbar.scss b/docusaurus/src/scss/ai-toolbar.scss
index 6d5f8e7855..c32a3e1766 100644
--- a/docusaurus/src/scss/ai-toolbar.scss
+++ b/docusaurus/src/scss/ai-toolbar.scss
@@ -110,7 +110,6 @@
   }
 
   &__dropdown-item {
-    position: relative;
     display: flex;
     align-items: center;
     gap: 0.75rem;
@@ -134,15 +133,13 @@
     }
 
     .strapi-icons {
-      position: relative;
-      top: 1px;
       flex-shrink: 0;
       color: var(--strapi-neutral-600);
     }
 
     &--no-description {
       .strapi-icons {
-        top: -7px;
+        top: -8px;
       }
     }
   }
@@ -259,7 +256,7 @@
 
       &--no-description {
         .strapi-icons {
-          top: -7px;
+          top: -8px;
         }
       }
     }

From b707ce3cf3d905e9602b006e87475abe2d173cd5 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <4233866+pwizla@users.noreply.github.com>
Date: Tue, 4 Nov 2025 21:05:22 +0100
Subject: [PATCH 14/43] Simplify icons alignment fix

---
 docusaurus/src/scss/ai-toolbar.scss | 16 ++--------------
 1 file changed, 2 insertions(+), 14 deletions(-)

diff --git a/docusaurus/src/scss/ai-toolbar.scss b/docusaurus/src/scss/ai-toolbar.scss
index c32a3e1766..96ab742ec5 100644
--- a/docusaurus/src/scss/ai-toolbar.scss
+++ b/docusaurus/src/scss/ai-toolbar.scss
@@ -111,8 +111,8 @@
 
   &__dropdown-item {
     display: flex;
-    align-items: center;
-    gap: 0.75rem;
+    align-items: flex-start;
+    gap: 0.5rem;
     width: 100%;
     padding: 0.75rem 1rem;
     border: none;
@@ -136,12 +136,6 @@
       flex-shrink: 0;
       color: var(--strapi-neutral-600);
     }
-
-    &--no-description {
-      .strapi-icons {
-        top: -8px;
-      }
-    }
   }
 
   &__dropdown-item-content {
@@ -253,12 +247,6 @@
       .strapi-icons {
         color: var(--strapi-neutral-600);
       }
-
-      &--no-description {
-        .strapi-icons {
-          top: -8px;
-        }
-      }
     }
 
     &__dropdown-item-description {

From 713ce210a6a66f1958e6edc51d09c7ef8a335558 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <4233866+pwizla@users.noreply.github.com>
Date: Wed, 5 Nov 2025 14:30:45 +0100
Subject: [PATCH 15/43] Try to fix Claude's issue

---
 .../components/AiToolbar/actions/openLLM.js   | 115 ++++++++++--------
 1 file changed, 62 insertions(+), 53 deletions(-)

diff --git a/docusaurus/src/components/AiToolbar/actions/openLLM.js b/docusaurus/src/components/AiToolbar/actions/openLLM.js
index d287d51a88..91a2471054 100644
--- a/docusaurus/src/components/AiToolbar/actions/openLLM.js
+++ b/docusaurus/src/components/AiToolbar/actions/openLLM.js
@@ -1,54 +1,63 @@
 import {
-  buildPromptFromTemplate,
-  buildUrlWithPrompt,
-  selectLocalizedTemplate,
-} from '../utils/docContext';
-
-const DEFAULT_PROMPT_TEMPLATE = 'Read from {{url}} so I can ask questions about it.';
-
-const resolveTemplate = (defaultTemplate, selectedTemplate, includeDefaultPrompt) => {
-  const safeDefault = defaultTemplate || DEFAULT_PROMPT_TEMPLATE;
-  const safeSelected = selectedTemplate || safeDefault;
-
-  if (!includeDefaultPrompt) {
-    return safeSelected;
-  }
-
-  if (safeSelected === safeDefault) {
-    return safeDefault;
-  }
-
-  return `${safeSelected}\n\n---\n${safeDefault}`;
-};
-
-export const openLLMAction = (context) => {
-  const {
-    targetUrl,
-    promptTemplate = DEFAULT_PROMPT_TEMPLATE,
-    localizedPromptTemplates = {},
-    includeDefaultPrompt = false,
-    promptParam = 'prompt',
-    openIn = '_blank',
-    closeDropdown,
-  } = context;
-
-  if (!targetUrl) {
-    console.error('open-llm action requires a targetUrl');
-    return;
-  }
-
-  const selectedTemplate = selectLocalizedTemplate(promptTemplate, localizedPromptTemplates);
-  const template = resolveTemplate(promptTemplate, selectedTemplate, includeDefaultPrompt);
-  const prompt = buildPromptFromTemplate(template);
-  const fullUrl = buildUrlWithPrompt({
-    targetUrl,
-    prompt,
-    promptParam,
-  });
-
-  window.open(fullUrl || targetUrl, openIn);
-
-  if (closeDropdown) {
-    closeDropdown();
-  }
-};
+    buildPromptFromTemplate,
+    buildUrlWithPrompt,
+    selectLocalizedTemplate,
+  } from '../utils/docContext';
+
+  const DEFAULT_PROMPT_TEMPLATE = 'Read from {{url}} so I can ask questions about it.';
+
+  const resolveTemplate = (defaultTemplate, selectedTemplate, includeDefaultPrompt) => {
+    const safeDefault = defaultTemplate || DEFAULT_PROMPT_TEMPLATE;
+    const safeSelected = selectedTemplate || safeDefault;
+
+    if (!includeDefaultPrompt) {
+      return safeSelected;
+    }
+
+    if (safeSelected === safeDefault) {
+      return safeDefault;
+    }
+
+    return `${safeSelected}\n\n---\n${safeDefault}`;
+  };
+
+  export const openLLMAction = async (context) => {
+    const {
+      targetUrl,
+      promptTemplate = DEFAULT_PROMPT_TEMPLATE,
+      localizedPromptTemplates = {},
+      includeDefaultPrompt = false,
+      copyPromptToClipboard = false,
+      promptParam = 'prompt',
+      openIn = '_blank',
+      closeDropdown,
+    } = context;
+
+    if (!targetUrl) {
+      console.error('open-llm action requires a targetUrl');
+      return;
+    }
+
+    const selectedTemplate = selectLocalizedTemplate(promptTemplate, localizedPromptTemplates);
+    const template = resolveTemplate(promptTemplate, selectedTemplate, includeDefaultPrompt);
+    const prompt = buildPromptFromTemplate(template);
+    const fullUrl = buildUrlWithPrompt({
+      targetUrl,
+      prompt,
+      promptParam,
+    });
+
+    if (copyPromptToClipboard && typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+      try {
+        await navigator.clipboard.writeText(prompt);
+      } catch (error) {
+        console.warn('Unable to copy prompt to clipboard:', error);
+      }
+    }
+
+    window.open(fullUrl || targetUrl, openIn);
+
+    if (closeDropdown) {
+      closeDropdown();
+    }
+  };
\ No newline at end of file

From 08ad52069977fbc07cb2f39c102d1f9d8d58069b Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Wed, 5 Nov 2025 14:26:11 +0000
Subject: [PATCH 16/43] Fix query parameter for Claude

---
 docusaurus/src/components/AiToolbar/config/aiToolsConfig.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index be605dec24..2bcdf358fc 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -69,7 +69,7 @@ export const aiToolsConfig = {
         ja: '{{url}} を読んで、質問できるようにしてください。',
       },
       includeDefaultPrompt: true,
-      promptParam: ['query', 'initial_message'],
+      promptParam: 'q',
       openIn: '_blank',
     },
   ],

From ed2d60ed2f0a8de6ff3ff27cba9c9183fb3db2ad Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Wed, 5 Nov 2025 14:31:34 +0000
Subject: [PATCH 17/43] Remove dual prompt in Claude now that we fixed the
 query param

---
 .../components/AiToolbar/actions/openLLM.js   | 110 ++++++++----------
 .../AiToolbar/config/aiToolsConfig.js         |   1 -
 2 files changed, 51 insertions(+), 60 deletions(-)

diff --git a/docusaurus/src/components/AiToolbar/actions/openLLM.js b/docusaurus/src/components/AiToolbar/actions/openLLM.js
index 91a2471054..714fa3933c 100644
--- a/docusaurus/src/components/AiToolbar/actions/openLLM.js
+++ b/docusaurus/src/components/AiToolbar/actions/openLLM.js
@@ -1,63 +1,55 @@
 import {
-    buildPromptFromTemplate,
-    buildUrlWithPrompt,
-    selectLocalizedTemplate,
-  } from '../utils/docContext';
-
-  const DEFAULT_PROMPT_TEMPLATE = 'Read from {{url}} so I can ask questions about it.';
-
-  const resolveTemplate = (defaultTemplate, selectedTemplate, includeDefaultPrompt) => {
-    const safeDefault = defaultTemplate || DEFAULT_PROMPT_TEMPLATE;
-    const safeSelected = selectedTemplate || safeDefault;
-
-    if (!includeDefaultPrompt) {
-      return safeSelected;
-    }
-
-    if (safeSelected === safeDefault) {
-      return safeDefault;
+  buildPromptFromTemplate,
+  buildUrlWithPrompt,
+  selectLocalizedTemplate,
+} from '../utils/docContext';
+
+const DEFAULT_PROMPT_TEMPLATE = 'Read from {{url}} so I can ask questions about it.';
+
+const resolveTemplate = (defaultTemplate, selectedTemplate) => {
+  return selectedTemplate || defaultTemplate || DEFAULT_PROMPT_TEMPLATE;
+};
+
+export const openLLMAction = async (context) => {
+  const {
+    targetUrl,
+    promptTemplate = DEFAULT_PROMPT_TEMPLATE,
+    localizedPromptTemplates = {},
+    copyPromptToClipboard = false,
+    promptParam = 'prompt',
+    openIn = '_blank',
+    closeDropdown,
+  } = context;
+
+  if (!targetUrl) {
+    console.error('open-llm action requires a targetUrl');
+    return;
+  }
+
+  const selectedTemplate = selectLocalizedTemplate(promptTemplate, localizedPromptTemplates);
+  const template = resolveTemplate(promptTemplate, selectedTemplate);
+  const prompt = buildPromptFromTemplate(template);
+  const fullUrl = buildUrlWithPrompt({
+    targetUrl,
+    prompt,
+    promptParam,
+  });
+
+  if (
+    copyPromptToClipboard &&
+    typeof navigator !== 'undefined' &&
+    navigator.clipboard?.writeText
+  ) {
+    try {
+      await navigator.clipboard.writeText(prompt);
+    } catch (error) {
+      console.warn('Unable to copy prompt to clipboard:', error);
     }
+  }
 
-    return `${safeSelected}\n\n---\n${safeDefault}`;
-  };
-
-  export const openLLMAction = async (context) => {
-    const {
-      targetUrl,
-      promptTemplate = DEFAULT_PROMPT_TEMPLATE,
-      localizedPromptTemplates = {},
-      includeDefaultPrompt = false,
-      copyPromptToClipboard = false,
-      promptParam = 'prompt',
-      openIn = '_blank',
-      closeDropdown,
-    } = context;
-
-    if (!targetUrl) {
-      console.error('open-llm action requires a targetUrl');
-      return;
-    }
-
-    const selectedTemplate = selectLocalizedTemplate(promptTemplate, localizedPromptTemplates);
-    const template = resolveTemplate(promptTemplate, selectedTemplate, includeDefaultPrompt);
-    const prompt = buildPromptFromTemplate(template);
-    const fullUrl = buildUrlWithPrompt({
-      targetUrl,
-      prompt,
-      promptParam,
-    });
-
-    if (copyPromptToClipboard && typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
-      try {
-        await navigator.clipboard.writeText(prompt);
-      } catch (error) {
-        console.warn('Unable to copy prompt to clipboard:', error);
-      }
-    }
+  window.open(fullUrl || targetUrl, openIn);
 
-    window.open(fullUrl || targetUrl, openIn);
-
-    if (closeDropdown) {
-      closeDropdown();
-    }
-  };
\ No newline at end of file
+  if (closeDropdown) {
+    closeDropdown();
+  }
+};
diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index 2bcdf358fc..2ab534d15d 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -68,7 +68,6 @@ export const aiToolsConfig = {
         ru: 'Прочитай {{url}}, чтобы я мог задавать вопросы по нему.',
         ja: '{{url}} を読んで、質問できるようにしてください。',
       },
-      includeDefaultPrompt: true,
       promptParam: 'q',
       openIn: '_blank',
     },

From 7b044c1a56d2451df7c2beca7f01287391560ba7 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Wed, 5 Nov 2025 19:46:40 +0000
Subject: [PATCH 18/43] Refactor translation system and add many more locales

---
 docusaurus/docs/ai-toolbar-translations.md    | 51 ++++++++++++++++++
 .../contributing/ai-toolbar-translations.md   | 54 +++++++++++++++++++
 .../AiToolbar/config/aiToolsConfig.js         | 31 ++---------
 3 files changed, 110 insertions(+), 26 deletions(-)
 create mode 100644 docusaurus/docs/ai-toolbar-translations.md
 create mode 100644 docusaurus/docs/contributing/ai-toolbar-translations.md

diff --git a/docusaurus/docs/ai-toolbar-translations.md b/docusaurus/docs/ai-toolbar-translations.md
new file mode 100644
index 0000000000..efee64c83c
--- /dev/null
+++ b/docusaurus/docs/ai-toolbar-translations.md
@@ -0,0 +1,51 @@
+# AI Toolbar Prompt Translations
+
+The AI toolbar (ChatGPT/Claude buttons) relies on a shared set of translated prompt strings. If you’d like to tweak an existing translation or contribute a new language, follow this guide.
+
+## Where prompts live
+
+- Edit `src/components/AiToolbar/config/aiPromptTemplates.js`.
+- Keys are ISO language tags (e.g., `en`, `fr`, `pt-BR`).
+- Values are strings that may contain placeholders such as `{{url}}`.
+
+```js
+export const aiPromptTemplates = {
+  'en': 'Read from {{url}} so I can ask questions about it.',
+  'fr': 'Lis {{url}} pour que je puisse poser des questions à son sujet.',
+  // Add new entries here …
+};
+```
+
+## Rules to follow
+
+1. **Keep placeholders intact.** `{{url}}` is required.
+2. **Use clear, neutral tone.** Mirror the English template.
+3. **One translation per language.** No duplicates.
+4. **Prefer UTF-8 text.** Don’t escape unless necessary.
+
+## Testing locally
+
+1. Change `navigator.language` via browser DevTools.
+2. Reload the docs page and click the toolbar button.
+3. Confirm the new tab or copied prompt shows your translation.
+
+## Validation script
+
+Run the built-in check before opening a PR:
+
+```bash
+node scripts/validate-prompts.js
+# or, if Node isn’t available in your environment:
+python scripts/validate-prompts.py
+```
+
+Both ensure the `{{url}}` placeholder is present and no translation is empty.
+
+## Adding a new language
+
+1. Add the entry in `aiPromptTemplates.js`.
+2. Update this document if helpful (e.g., to credit contributors).
+3. (Optional) Add a test case if you create one in the future.
+4. Include a screenshot/gif in your PR showing the prompt in action.
+
+Thanks for helping improve the AI tooling experience! 🙌
diff --git a/docusaurus/docs/contributing/ai-toolbar-translations.md b/docusaurus/docs/contributing/ai-toolbar-translations.md
new file mode 100644
index 0000000000..cf9e85fe49
--- /dev/null
+++ b/docusaurus/docs/contributing/ai-toolbar-translations.md
@@ -0,0 +1,54 @@
+---
+id: ai-toolbar-translations
+title: Update AI Toolbar Prompts
+---
+
+The AI toolbar (ChatGPT and Claude buttons) uses a set of translated prompt strings. If you want to tweak a translation or add a new language, use this guide.
+
+## Location
+
+- Edit `src/components/AiToolbar/config/aiPromptTemplates.js` in this repository.
+- Keys are ISO language tags (use lowercase, include region if needed, e.g. `pt-BR`).
+- Values are plain strings with placeholders like `{{url}}`.
+
+```js
+export const aiPromptTemplates = {
+  'en': 'Read from {{url}} so I can ask questions about it.',
+  'fr': 'Lis {{url}} pour que je puisse poser des questions à son sujet.',
+  // …
+};
+```
+
+## Contribution Rules
+
+1. **Keep placeholders**: `{{url}}` is mandatory so the current page URL is injected.
+2. **Preserve meaning**: Translate the English prompt faithfully; keep a neutral tone.
+3. **Avoid duplicates**: one entry per language tag.
+4. **Use UTF-8 characters** wherever possible; avoid HTML entities.
+
+## Testing Your Translation
+
+1. Override `navigator.language` via DevTools (Chrome Sensors panel or Firefox locale settings).
+2. Reload any docs page with the toolbar.
+3. Click “Open with ChatGPT/Claude” and confirm your translation appears in the prompt or clipboard.
+
+## Validation Script
+
+Before opening a pull request, run the placeholder check:
+
+```bash
+node scripts/validate-prompts.js
+# If Node isn’t available, run:
+python scripts/validate-prompts.py
+```
+
+The script ensures that each translation keeps the required placeholders and isn’t empty.
+
+## Adding a New Language
+
+1. Add your entry in `aiPromptTemplates.js`.
+2. Run the validation script.
+3. Include a screenshot or clip in your PR showing the translation in action (optional but helpful).
+4. Update this doc if you want to note any language-specific tips.
+
+Thanks for helping improve the AI tooling experience! 🙌
diff --git a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
index 2ab534d15d..aa84b52e3d 100644
--- a/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
+++ b/docusaurus/src/components/AiToolbar/config/aiToolsConfig.js
@@ -1,3 +1,5 @@
+import { aiPromptTemplates } from './aiPromptTemplates';
+
 export const aiToolsConfig = {
   primaryActionId: 'copy-markdown',
 
@@ -28,46 +30,23 @@ export const aiToolsConfig = {
     {
       id: 'open-chatgpt',
       label: 'Open with ChatGPT',
-      // description: 'Open ChatGPT with a prompt about this page',
       icon: 'open-ai-logo',
       actionType: 'open-llm',
       targetUrl: 'https://chat.openai.com/',
       promptTemplate: 'Read from {{url}} so I can ask questions about it.',
-      localizedPromptTemplates: {
-        en: 'Read from {{url}} so I can ask questions about it.',
-        zh: '请阅读 {{url}} 的内容，以便我能就其提出问题。',
-        es: 'Lee {{url}} para que pueda hacer preguntas al respecto.',
-        hi: '{{url}} पढ़ें ताकि मैं इसके बारे में प्रश्न पूछ सकूँ।',
-        ar: 'اقرأ من {{url}} حتى أتمكن من طرح أسئلة حوله.',
-        fr: 'Lis {{url}} pour que je puisse poser des questions à son sujet.',
-        pt: 'Leia {{url}} para que eu possa fazer perguntas sobre isso.',
-        bn: '{{url}} থেকে পড়ুন যাতে আমি এর সম্পর্কে প্রশ্ন করতে পারি।',
-        ru: 'Прочитай {{url}}, чтобы я мог задавать вопросы по нему.',
-        ja: '{{url}} を読んで、質問できるようにしてください。',
-      },
+      localizedPromptTemplates: aiPromptTemplates,
       promptParam: 'prompt',
       openIn: '_blank',
     },
     {
       id: 'open-claude',
       label: 'Open with Claude',
-      // description: 'Open Claude with a prompt about this page',
       icon: 'chat-teardrop-text',
       actionType: 'open-llm',
       targetUrl: 'https://claude.ai/new',
       promptTemplate: 'Read from {{url}} so I can ask questions about it.',
-      localizedPromptTemplates: {
-        en: 'Read from {{url}} so I can ask questions about it.',
-        zh: '请阅读 {{url}} 的内容，以便我能就其提出问题。',
-        es: 'Lee {{url}} para que pueda hacer preguntas al respecto.',
-        hi: '{{url}} पढ़ें ताकि मैं इसके बारे में प्रश्न पूछ सकूँ।',
-        ar: 'اقرأ من {{url}} حتى أتمكن من طرح أسئلة حوله.',
-        fr: 'Lis {{url}} pour que je puisse poser des questions à son sujet.',
-        pt: 'Leia {{url}} para que eu possa fazer perguntas sobre isso.',
-        bn: '{{url}} থেকে পড়ুন যাতে నేను এর সম্পর্কে প্রশ্ন করতে পারি।',
-        ru: 'Прочитай {{url}}, чтобы я мог задавать вопросы по нему.',
-        ja: '{{url}} を読んで、質問できるようにしてください。',
-      },
+      localizedPromptTemplates: aiPromptTemplates,
+      copyPromptToClipboard: true,
       promptParam: 'q',
       openIn: '_blank',
     },

From 42112071b362c6bf39cafbc80707a898a67817d5 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Wed, 5 Nov 2025 19:47:47 +0000
Subject: [PATCH 19/43] Add aiPromptTemplates.js

---
 .../AiToolbar/config/aiPromptTemplates.js     | 88 +++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 docusaurus/src/components/AiToolbar/config/aiPromptTemplates.js

diff --git a/docusaurus/src/components/AiToolbar/config/aiPromptTemplates.js b/docusaurus/src/components/AiToolbar/config/aiPromptTemplates.js
new file mode 100644
index 0000000000..473f86f0ad
--- /dev/null
+++ b/docusaurus/src/components/AiToolbar/config/aiPromptTemplates.js
@@ -0,0 +1,88 @@
+// Central list of localized prompts used by AI toolbar actions.
+// Contributors can add new language codes (ISO language tag) or adjust translations here.
+// Keep the {{url}} placeholder intact -- it will be replaced with the current document URL.
+
+export const aiPromptTemplates = {
+  'ar': 'اقرأ من {{url}} حتى أتمكن من طرح أسئلة حوله.',
+  'ay': '{{url}} uñt’asma ukhamarusa jupanxata jiskt’añataki.',
+  'be': 'Прачытай {{url}}, каб я мог задаваць пытанні пра гэта.',
+  'bg': 'Прочети {{url}}, за да мога да задавам въпроси за него.',
+  'bn': '{{url}} থেকে পড়ুন যাতে আমি এর সম্পর্কে প্রশ্ন করতে পারি।',
+  'bs': 'Pročitaj {{url}} kako bih mogao postavljati pitanja o tome.',
+  'ca': 'Llegeix {{url}} perquè pugui fer preguntes sobre això.',
+  'crk': 'Ka-pîhtokê {{url}} mîna nika isiyihkêw pimipahtâw.',
+  'cs': 'Přečti si {{url}}, abych mohl pokládat otázky.',
+  'cy': 'Darllen {{url}} fel y gallaf ofyn cwestiynau amdano.',
+  'da': 'Læs {{url}}, så jeg kan stille spørgsmål om det.',
+  'de': 'Lies {{url}}, damit ich Fragen dazu stellen kann.',
+  'el': 'Διάβασε το {{url}} ώστε να μπορώ να κάνω ερωτήσεις σχετικά.',
+  'en': 'Read from {{url}} so I can ask questions about it.',
+  'es': 'Lee {{url}} para que pueda hacer preguntas al respecto.',
+  'et': 'Loe {{url}}, et saaksin selle kohta küsimusi esitada.',
+  'fa': 'از {{url}} بخوان تا بتوانم در مورد آن سؤال بپرسم.',
+  'fi': 'Lue {{url}}, jotta voin esittää siitä kysymyksiä.',
+  'fil': 'Basahin ang {{url}} para makapagtanong ako tungkol dito.',
+  'fr': 'Lis {{url}} pour que je puisse poser des questions à son sujet.',
+  'ga': 'Léigh {{url}} ionas go mbeidh mé in ann ceisteanna a chur faoi.',
+  'gn': 'Emoñeʼẽ {{url}} ikatu hag̃ua porandu chupe rehe.',
+  'gu': '{{url}} વાંચો જેથી હું તેના વિશે પ્રશ્નો પૂછી શકું.',
+  'haw': 'E heluhelu i {{url}} i hiki iaʻu ke nīnau e pili ana iā ia.',
+  'he': 'קרא את {{url}} כדי שאוכל לשאול עליו שאלות.',
+  'hi': '{{url}} पढ़ें ताकि मैं इसके बारे में प्रश्न पूछ सकूँ।',
+  'hr': 'Pročitaj {{url}} kako bih mogao postavljati pitanja o tome.',
+  'ht': 'Li {{url}} pou mwen ka poze kesyon sou li.',
+  'hu': 'Olvasd el a {{url}} tartalmát, hogy kérdéseket tehessek fel róla.',
+  'id': 'Baca {{url}} agar saya bisa mengajukan pertanyaan tentangnya.',
+  'is': 'Lestu {{url}} svo ég geti spurt spurninga um það.',
+  'it': 'Leggi {{url}} così posso fare domande al riguardo.',
+  'ja': '{{url}} を読んで、質問できるようにしてください。',
+  'jv': 'Waca {{url}} supaya aku bisa takon babagan iki.',
+  'kk': '{{url}} оқыңыз, сонда мен оған қатысты сұрақтар қоя аламын.',
+  'km': 'អាន {{url}} ដើម្បីឲ្យខ្ញុំអាចសួរពីវាបាន.',
+  'kn': '{{url}} ಓದಿ, ನಾನು ಅದಕ್ಕೆ ಸಂಬಂಧಿಸಿದ ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳಲು ಸಾಧ್ಯವಾಗಲಿ.',
+  'ko': '{{url}} 를 읽어 보고 이에 대해 질문할 수 있게 해 주세요.',
+  'ku': '{{url}} bixwîne da ku bikaribim li ser wî pirsên li dayim.',
+  'ky': '{{url}} оку, ошондо мен андан суроолор бере алам.',
+  'lb': 'Lies {{url}}, fir datt ech Froen doriwwer stelle kann.',
+  'lo': 'ອ່ານ {{url}} ເພື່ອໃຫ້ຂ້ອຍສາມາດຖາມຄໍາຖາມກ່ຽວກັບມັນໄດ້.',
+  'lt': 'Perskaityk {{url}}, kad galėčiau užduoti klausimus apie tai.',
+  'lv': 'Izlasi {{url}}, lai es varētu uzdot jautājumus par to.',
+  'mk': 'Прочитај {{url}} за да можам да поставувам прашања за тоа.',
+  'ml': '{{url}} വായിക്കുക, അതിനെ കുറിച്ച് ഞാൻ ചോദ്യങ്ങൾ ചോദിക്കാനാകട്ടെ.',
+  'mn': '{{url}}-с уншаад, үүнээс асуулт асуух боломж олгоорой.',
+  'mr': '{{url}} वाचा म्हणजे मला त्याबद्दल प्रश्न विचारता येतील.',
+  'ms': 'Baca {{url}} supaya saya boleh bertanya soalan mengenainya.',
+  'mt': 'Aqra {{url}} sabiex inkun nista’ nistaqsi mistoqsijiet dwaru.',
+  'my': '{{url}} ကိုဖတ်ပြီးအဲဒါအကြောင်း မေးမြန်းနိုင်အောင်လုပ်ပါ။',
+  'nb': 'Les {{url}} slik at jeg kan stille spørsmål om det.',
+  'ne': '{{url}} पढ्नुहोस् ताकि म यसको बारेमा प्रश्न सोध्न सकूँ।',
+  'nl': 'Lees {{url}} zodat ik er vragen over kan stellen.',
+  'nv': 'Háíshį́įgo {{url}} yiníłʼį́įł doo tʼáá chʼíyáán dóó baa akʼíníshííł níłchííʼ.',
+  'oj': 'Na naa {{url}} ezhi-bimiwidoon omaa wikenh.',
+  'pa': '{{url}} ਪੜ੍ਹੋ ਤਾਂ ਜੋ ਮੈਂ ਇਸ ਬਾਰੇ ਸਵਾਲ ਪੁੱਛ ਸਕਾਂ।',
+  'pl': 'Przeczytaj {{url}}, żebym mógł zadawać pytania na ten temat.',
+  'ps': '{{url}} ولوله، ترڅو زه وکولای شم په اړه يې پوښتنې وکړم.',
+  'pt': 'Leia {{url}} para que eu possa fazer perguntas sobre isso.',
+  'qu': '{{url}} ñawinchay, chaymanta tapuykuna ruriyta atispaq.',
+  'ro': 'Citește {{url}} ca să pot pune întrebări despre el.',
+  'ru': 'Прочитай {{url}}, чтобы я мог задавать вопросы по нему.',
+  'si': '{{url}} කියවන්න, එතැන් පසු මට එය ගැන ප්‍රශ්න කිරීමට හැකිවනු ඇත.',
+  'sk': 'Prečítaj si {{url}}, aby som o tom mohol klásť otázky.',
+  'sl': 'Preberi {{url}}, da bom lahko postavljal vprašanja o tem.',
+  'sq': 'Lexo {{url}} që të mund të bëj pyetje rreth tij.',
+  'sr': 'Pročitaj {{url}} da bih mogao da постављam pitanja o tome.',
+  'sv': 'Läs {{url}} så att jag kan ställa frågor om det.',
+  'ta': '{{url}} படித்து நான் அதைப் பற்றி கேள்விகள் கேட்க முடியும்.',
+  'te': '{{url}} చదవండి, దాని గురించి నేను ప్రశ్నలు అడగగలను.',
+  'th': 'อ่าน {{url}} เพื่อที่ฉันจะได้ถามคำถามเกี่ยวกับมัน.',
+  'tg': '{{url}}-ро бихон, то тавонам дар бораи он савол диҳам.',
+  'tk': '{{url}}-i okaň, şonda men onuň barada sorag berip bilerin.',
+  'tr': '{{url}} oku ki hakkında sorular sorabileyim.',
+  'tt': '{{url}} укы, шуннан соң сораулар бирә алырмын.',
+  'ug': '{{url}} نى ئوقۇپ چىقىڭ، شۇ توغۇرىدا سوئال سورىيالايمەن.',
+  'uk': 'Прочитай {{url}}, щоб я міг ставити запитання про це.',
+  'ur': '{{url}} پڑھیں تاکہ میں اس کے بارے میں سوالات پوچھ سکوں۔',
+  'uz': '{{url}} ni o‘qing, shunda men undan savollar so‘ray olaman.',
+  'vi': 'Đọc {{url}} để tôi có thể đặt câu hỏi về nó.',
+  'zh': '请阅读 {{url}} 的内容，以便我能就其提出问题。',
+};

From b2f8c0352d789579aa0d6f87ebe8c2aac8c5ae80 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Wed, 5 Nov 2025 19:48:16 +0000
Subject: [PATCH 20/43] Add script for translated prompt validation

---
 docusaurus/scripts/validate-prompts.js | 58 ++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100755 docusaurus/scripts/validate-prompts.js

diff --git a/docusaurus/scripts/validate-prompts.js b/docusaurus/scripts/validate-prompts.js
new file mode 100755
index 0000000000..3694b080a8
--- /dev/null
+++ b/docusaurus/scripts/validate-prompts.js
@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const PROMPT_FILE = path.join(__dirname, '..', 'src', 'components', 'AiToolbar', 'config', 'aiPromptTemplates.js');
+const REQUIRED_PLACEHOLDERS = ['{{url}}'];
+
+function loadPromptMap(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const match = content.match(/export const aiPromptTemplates = (\{[\s\S]*?\});/);
+  if (!match) {
+    throw new Error('Unable to locate aiPromptTemplates export.');
+  }
+  // eslint-disable-next-line no-new-func
+  const factory = new Function(`return (${match[1]});`);
+  return factory();
+}
+
+function main() {
+  try {
+    const prompts = loadPromptMap(PROMPT_FILE);
+    const languages = Object.keys(prompts);
+
+    if (languages.length === 0) {
+      throw new Error('No prompt translations found.');
+    }
+
+    for (const lang of languages) {
+      const value = prompts[lang];
+      if (typeof value !== 'string') {
+        throw new Error(`Prompt for language "${lang}" must be a string.`);
+      }
+
+      const trimmed = value.trim();
+      if (trimmed.length === 0) {
+        throw new Error(`Prompt for language "${lang}" is empty.`);
+      }
+
+      if (trimmed !== value) {
+        console.warn(`Warning: prompt for "${lang}" has leading/trailing whitespace.`);
+      }
+
+      for (const placeholder of REQUIRED_PLACEHOLDERS) {
+        if (!value.includes(placeholder)) {
+          throw new Error(`Prompt for "${lang}" is missing placeholder ${placeholder}.`);
+        }
+      }
+    }
+
+    console.log(`Validated ${languages.length} prompt translations.`);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+main();

From 119eb1c7aa51363bc53b76f48e95610d0735e24c Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Wed, 5 Nov 2025 21:09:04 +0000
Subject: [PATCH 21/43] Added many more languages

---
 .../AiToolbar/config/aiPromptTemplates.js     | 42 ++++++++++++++++++-
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/docusaurus/src/components/AiToolbar/config/aiPromptTemplates.js b/docusaurus/src/components/AiToolbar/config/aiPromptTemplates.js
index 473f86f0ad..bfa1e13e73 100644
--- a/docusaurus/src/components/AiToolbar/config/aiPromptTemplates.js
+++ b/docusaurus/src/components/AiToolbar/config/aiPromptTemplates.js
@@ -3,10 +3,15 @@
 // Keep the {{url}} placeholder intact -- it will be replaced with the current document URL.
 
 export const aiPromptTemplates = {
+  'aa': 'Ku adha {{url}} si aan ugu faaqido su’aalo ka saabsan.',
+  'af': 'Lees {{url}} sodat ek vrae daaroor kan vra.',
+  'ak': 'Kenkan {{url}} sɛnea ɛbɛyɛ a metumi bisa nsɛm afa ho.',
+  'am': '{{url}} አንብብ እና ስለእሱ ጥያቄዎችን እችላለሁ.',
   'ar': 'اقرأ من {{url}} حتى أتمكن من طرح أسئلة حوله.',
   'ay': '{{url}} uñt’asma ukhamarusa jupanxata jiskt’añataki.',
   'be': 'Прачытай {{url}}, каб я мог задаваць пытанні пра гэта.',
   'bg': 'Прочети {{url}}, за да мога да задавам въпроси за него.',
+  'bm': 'Ka bɔ {{url}} walasa n ka se ka ɲininkaliw kɛ o ko la.',
   'bn': '{{url}} থেকে পড়ুন যাতে আমি এর সম্পর্কে প্রশ্ন করতে পারি।',
   'bs': 'Pročitaj {{url}} kako bih mogao postavljati pitanja o tome.',
   'ca': 'Llegeix {{url}} perquè pugui fer preguntes sobre això.',
@@ -15,17 +20,20 @@ export const aiPromptTemplates = {
   'cy': 'Darllen {{url}} fel y gallaf ofyn cwestiynau amdano.',
   'da': 'Læs {{url}}, så jeg kan stille spørgsmål om det.',
   'de': 'Lies {{url}}, damit ich Fragen dazu stellen kann.',
+  'ee': 'Xlẽ nu tso {{url}} ale be mateŋu abia nyawo tso eŋu.',
   'el': 'Διάβασε το {{url}} ώστε να μπορώ να κάνω ερωτήσεις σχετικά.',
   'en': 'Read from {{url}} so I can ask questions about it.',
   'es': 'Lee {{url}} para que pueda hacer preguntas al respecto.',
   'et': 'Loe {{url}}, et saaksin selle kohta küsimusi esitada.',
   'fa': 'از {{url}} بخوان تا بتوانم در مورد آن سؤال بپرسم.',
+  'ff': 'Janngo {{url}} ngam mi waawi naamnaade ɗum.',
   'fi': 'Lue {{url}}, jotta voin esittää siitä kysymyksiä.',
   'fil': 'Basahin ang {{url}} para makapagtanong ako tungkol dito.',
   'fr': 'Lis {{url}} pour que je puisse poser des questions à son sujet.',
   'ga': 'Léigh {{url}} ionas go mbeidh mé in ann ceisteanna a chur faoi.',
   'gn': 'Emoñeʼẽ {{url}} ikatu hag̃ua porandu chupe rehe.',
   'gu': '{{url}} વાંચો જેથી હું તેના વિશે પ્રશ્નો પૂછી શકું.',
+  'ha': 'Karanta daga {{url}} don haka zan iya yin tambayoyi a kansa.',
   'haw': 'E heluhelu i {{url}} i hiki iaʻu ke nīnau e pili ana iā ia.',
   'he': 'קרא את {{url}} כדי שאוכל לשאול עליו שאלות.',
   'hi': '{{url}} पढ़ें ताकि मैं इसके बारे में प्रश्न पूछ सकूँ।',
@@ -33,20 +41,29 @@ export const aiPromptTemplates = {
   'ht': 'Li {{url}} pou mwen ka poze kesyon sou li.',
   'hu': 'Olvasd el a {{url}} tartalmát, hogy kérdéseket tehessek fel róla.',
   'id': 'Baca {{url}} agar saya bisa mengajukan pertanyaan tentangnya.',
+  'ig': 'Gụọ {{url}} ka m nwee ike ịjụ ajụjụ gbasara ya.',
   'is': 'Lestu {{url}} svo ég geti spurt spurninga um það.',
   'it': 'Leggi {{url}} così posso fare domande al riguardo.',
   'ja': '{{url}} を読んで、質問できるようにしてください。',
   'jv': 'Waca {{url}} supaya aku bisa takon babagan iki.',
+  'kg': 'Tanga {{url}} sambu mono lenda yula bangiufula na yina me tala yo.',
+  'ki': 'Somana {{url}} ũndũ ngũũria ũhoro wake.',
+  'kj': 'Langula {{url}} okukala sova yoka ova tava ovili vadja.',
   'kk': '{{url}} оқыңыз, сонда мен оған қатысты сұрақтар қоя аламын.',
   'km': 'អាន {{url}} ដើម្បីឲ្យខ្ញុំអាចសួរពីវាបាន.',
   'kn': '{{url}} ಓದಿ, ನಾನು ಅದಕ್ಕೆ ಸಂಬಂಧಿಸಿದ ಪ್ರಶ್ನೆಗಳನ್ನು ಕೇಳಲು ಸಾಧ್ಯವಾಗಲಿ.',
   'ko': '{{url}} 를 읽어 보고 이에 대해 질문할 수 있게 해 주세요.',
+  'kr': 'Waɗtugo {{url}} so a yi’i ɗum ngam mi mbaɗi hayre baɗte ɗum.',
   'ku': '{{url}} bixwîne da ku bikaribim li ser wî pirsên li dayim.',
   'ky': '{{url}} оку, ошондо мен андан суроолор бере алам.',
   'lb': 'Lies {{url}}, fir datt ech Froen doriwwer stelle kann.',
+  'lg': 'Soma okuva mu {{url}} nsobole okubuuza ebibuuzo ku nsonga eno.',
+  'ln': 'Tanga {{url}} mpo na kotuna mituna na tina na yango.',
   'lo': 'ອ່ານ {{url}} ເພື່ອໃຫ້ຂ້ອຍສາມາດຖາມຄໍາຖາມກ່ຽວກັບມັນໄດ້.',
   'lt': 'Perskaityk {{url}}, kad galėčiau užduoti klausimus apie tai.',
+  'lu': 'Tangá {{url}} ukutulu bua kubuza malu a’yo.',
   'lv': 'Izlasi {{url}}, lai es varētu uzdot jautājumus par to.',
+  'mg': 'Vakio {{url}} mba hahafahako manontany fanontaniana momba izany.',
   'mk': 'Прочитај {{url}} за да можам да поставувам прашања за тоа.',
   'ml': '{{url}} വായിക്കുക, അതിനെ കുറിച്ച് ഞാൻ ചോദ്യങ്ങൾ ചോദിക്കാനാകട്ടെ.',
   'mn': '{{url}}-с уншаад, үүнээс асуулт асуух боломж олгоорой.',
@@ -55,34 +72,55 @@ export const aiPromptTemplates = {
   'mt': 'Aqra {{url}} sabiex inkun nista’ nistaqsi mistoqsijiet dwaru.',
   'my': '{{url}} ကိုဖတ်ပြီးအဲဒါအကြောင်း မေးမြန်းနိုင်အောင်လုပ်ပါ။',
   'nb': 'Les {{url}} slik at jeg kan stille spørsmål om det.',
+  'nd': 'Fundani {{url}} ukuze ngibuza imibuzo ngayo.',
   'ne': '{{url}} पढ्नुहोस् ताकि म यसको बारेमा प्रश्न सोध्न सकूँ।',
   'nl': 'Lees {{url}} zodat ik er vragen over kan stellen.',
+  'nr': 'Funda {{url}} ukuze ngibuza imibuzo ngayo.',
   'nv': 'Háíshį́įgo {{url}} yiníłʼį́įł doo tʼáá chʼíyáán dóó baa akʼíníshííł níłchííʼ.',
+  'ny': 'Werengani {{url}} kuti ndikhoze kufunsa mafunso zokhudza izo.',
   'oj': 'Na naa {{url}} ezhi-bimiwidoon omaa wikenh.',
+  'om': '{{url}} dubbisi, akka waa’ee isaa gaafachuu danda’u.',
   'pa': '{{url}} ਪੜ੍ਹੋ ਤਾਂ ਜੋ ਮੈਂ ਇਸ ਬਾਰੇ ਸਵਾਲ ਪੁੱਛ ਸਕਾਂ।',
   'pl': 'Przeczytaj {{url}}, żebym mógł zadawać pytania na ten temat.',
   'ps': '{{url}} ولوله، ترڅو زه وکولای شم په اړه يې پوښتنې وکړم.',
   'pt': 'Leia {{url}} para que eu possa fazer perguntas sobre isso.',
   'qu': '{{url}} ñawinchay, chaymanta tapuykuna ruriyta atispaq.',
+  'rn': 'Soma {{url}} kugira ngo nshobore kubaza ibibazo bijyanye na cyo.',
   'ro': 'Citește {{url}} ca să pot pune întrebări despre el.',
   'ru': 'Прочитай {{url}}, чтобы я мог задавать вопросы по нему.',
+  'rw': 'Soma {{url}} kugira ngo nshobore kubaza ibibazo kuri yo.',
+  'sg': 'Kɔmbɛ {{url}} na ndeke mbîgî tî ayeke na mabûnga na yê.',
   'si': '{{url}} කියවන්න, එතැන් පසු මට එය ගැන ප්‍රශ්න කිරීමට හැකිවනු ඇත.',
   'sk': 'Prečítaj si {{url}}, aby som o tom mohol klásť otázky.',
   'sl': 'Preberi {{url}}, da bom lahko postavljal vprašanja o tem.',
+  'sn': 'Verenga {{url}} kuti ndikwanise kubvunza mibvunzo nezvazvo.',
+  'so': 'Akhri {{url}} si aan u waydiiyo su’aalo ku saabsan.',
   'sq': 'Lexo {{url}} që të mund të bëj pyetje rreth tij.',
   'sr': 'Pročitaj {{url}} da bih mogao da постављam pitanja o tome.',
+  'ss': 'Funda ku {{url}} ukuze ngikwazi kubuta imibuto ngayo.',
+  'st': 'Bala {{url}} e le hore nka botsa lipotso ka eona.',
   'sv': 'Läs {{url}} så att jag kan ställa frågor om det.',
+  'sw': 'Soma {{url}} ili niweze kuuliza maswali kuihusu.',
   'ta': '{{url}} படித்து நான் அதைப் பற்றி கேள்விகள் கேட்க முடியும்.',
   'te': '{{url}} చదవండి, దాని గురించి నేను ప్రశ్నలు అడగగలను.',
-  'th': 'อ่าน {{url}} เพื่อที่ฉันจะได้ถามคำถามเกี่ยวกับมัน.',
   'tg': '{{url}}-ро бихон, то тавонам дар бораи он савол диҳам.',
+  'th': 'อ่าน {{url}} เพื่อที่ฉันจะได้ถามคำถามเกี่ยวกับมัน.',
+  'ti': 'ኣንብብ {{url}} እንታይ ጥያቄታት ክጠይቕ እችላይ።',
   'tk': '{{url}}-i okaň, şonda men onuň barada sorag berip bilerin.',
+  'tn': 'Bala go tswa go {{url}} gore ke kgone go botsa dipotso ka ga yona.',
   'tr': '{{url}} oku ki hakkında sorular sorabileyim.',
+  'ts': 'Hlaya {{url}} leswaku ndzi kota ku vutisa swivutiso hi swona.',
   'tt': '{{url}} укы, шуннан соң сораулар бирә алырмын.',
+  'tw': 'Kenkan fi {{url}} na metumi abisa nsɛmmisa afa ho.',
   'ug': '{{url}} نى ئوقۇپ چىقىڭ، شۇ توغۇرىدا سوئال سورىيالايمەن.',
   'uk': 'Прочитай {{url}}, щоб я міг ставити запитання про це.',
   'ur': '{{url}} پڑھیں تاکہ میں اس کے بارے میں سوالات پوچھ سکوں۔',
   'uz': '{{url}} ni o‘qing, shunda men undan savollar so‘ray olaman.',
+  've': 'Vhalani {{url}} uri ndi kone u vhudzisa mbudziso nga hazwo.',
   'vi': 'Đọc {{url}} để tôi có thể đặt câu hỏi về nó.',
+  'wo': 'Jàng {{url}} ngir ma mën laaj ci mbir mi.',
+  'xh': 'Funda {{url}} ukuze ndikwazi ukubuza imibuzo ngayo.',
+  'yo': 'Ka kika {{url}} ki n le beere awọn ibeere nipa rẹ.',
   'zh': '请阅读 {{url}} 的内容，以便我能就其提出问题。',
-};
+  'zu': 'Funda ku {{url}} ukuze ngikwazi ukubuza imibuzo ngayo.',
+};;

From 8d4461bd66a7334bf6d95660fc164a26032820e9 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 09:20:27 +0000
Subject: [PATCH 22/43] Include Tldr components content in llms.txt

---
 docusaurus/scripts/generate-llms.js | 42 +++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/docusaurus/scripts/generate-llms.js b/docusaurus/scripts/generate-llms.js
index 9ae9a1df05..9bf611fd4c 100644
--- a/docusaurus/scripts/generate-llms.js
+++ b/docusaurus/scripts/generate-llms.js
@@ -118,11 +118,13 @@ class DocusaurusLlmsGenerator {
           const { data: frontmatter, content } = matter(fileContent);
           
           const pageUrl = this.generatePageUrl(docId);
-          
+          const tldr = this.extractTldr(content);
+
           pages.push({
             id: docId,
             title: frontmatter.title || this.getTitleFromContent(content) || docId,
-            description: frontmatter.description || this.extractDescription(content),
+            description:
+              tldr || frontmatter.description || this.extractDescription(content),
             url: pageUrl,
             content: this.cleanContent(content),
             frontmatter
@@ -160,6 +162,42 @@ class DocusaurusLlmsGenerator {
     return '';
   }
 
+  extractTldr(content) {
+    const match = content.match(/<Tldr>([\s\S]*?)<\/Tldr>/i);
+
+    if (!match) {
+      return null;
+    }
+
+    const raw = match[1].trim();
+
+    if (!raw) {
+      return null;
+    }
+
+    return this.sanitizeInlineMarkdown(raw);
+  }
+
+  sanitizeInlineMarkdown(text) {
+    return text
+      // Remove fenced code blocks inside TLDR (rare but safe)
+      .replace(/```[\s\S]*?```/g, '')
+      // Strip inline code
+      .replace(/`([^`]+)`/g, '$1')
+      // Turn markdown links into plain text
+      .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1')
+      // Bold and italic markers
+      .replace(/\*\*([^*]+)\*\*/g, '$1')
+      .replace(/__([^_]+)__/g, '$1')
+      .replace(/\*([^*]+)\*/g, '$1')
+      .replace(/_([^_]+)_/g, '$1')
+      // Strip residual HTML tags (including MDX components)
+      .replace(/<[^>]+>/g, ' ')
+      // Collapse whitespace and trim
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
   cleanContent(content) {
     return content
       // Deletes frontmatter metadata

From 07e44c72386bdb54a8dc2b93547fb13c9833e69f Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 10:46:34 +0000
Subject: [PATCH 23/43] WIP: Add draft of generate-llms-code.js to work on 3
 sample files

---
 docusaurus/scripts/generate-llms-code.js | 516 +++++++++++++++++++++++
 1 file changed, 516 insertions(+)
 create mode 100644 docusaurus/scripts/generate-llms-code.js

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
new file mode 100644
index 0000000000..1d66e657ab
--- /dev/null
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -0,0 +1,516 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+const matter = require('gray-matter');
+
+const DEFAULT_DOCS = [
+  'cms/admin-panel-customization/bundlers',
+  'cms/backend-customization/middlewares',
+  'cms/features/api-tokens',
+];
+
+const DEFAULT_OUTPUT = path.join('static', 'llms-code.txt');
+const BASE_URL = 'https://docs.strapi.io';
+const HEADING_REGEX = /^(#{1,6})\s+(.*)/;
+
+const cleanInlineText = (value) => {
+  if (!value) {
+    return '';
+  }
+
+  return value
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/__([^_]+)__/g, '$1')
+    .replace(/\*([^*]+)\*/g, '$1')
+    .replace(/_([^_]+)_/g, '$1')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+};
+
+const summarizeDescription = (raw, fallback) => {
+  const cleaned = cleanInlineText(raw)
+    .replace(/^[0-9]+[.)]\s*/, '')
+    .replace(/^[-*•]\s*/, '')
+    .trim();
+
+  if (!cleaned || !/[a-zA-Z]/.test(cleaned)) {
+    return { description: fallback, useCase: null, fallbackUsed: true };
+  }
+
+  const sentences = cleaned.split(/(?<=[.!?])\s+/);
+  const description = (sentences[0] || cleaned).trim();
+  let useCase = null;
+
+  for (const sentence of sentences.slice(1)) {
+    const lower = sentence.toLowerCase();
+    if (lower.includes('use ') || lower.includes('when ') || lower.includes('recommended')) {
+      useCase = sentence.trim();
+      break;
+    }
+  }
+
+  return { description, useCase, fallbackUsed: false };
+};
+
+const parseArgs = () => {
+  const args = process.argv.slice(2);
+  const docs = [];
+  let output = DEFAULT_OUTPUT;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '--docs') {
+      const value = args[i + 1];
+      i += 1;
+      if (value) {
+        value.split(',').map((item) => item.trim()).filter(Boolean).forEach((item) => docs.push(item));
+      }
+    } else if (arg === '--output') {
+      const value = args[i + 1];
+      i += 1;
+      if (value) {
+        output = value;
+      }
+    } else if (arg === '--help' || arg === '-h') {
+      console.log('Usage: node generate-llms-code.js [--docs docA,docB] [--output path/to/file]');
+      process.exit(0);
+    } else {
+      docs.push(arg);
+    }
+  }
+
+  return {
+    docs: docs.length > 0 ? docs : DEFAULT_DOCS,
+    output,
+  };
+};
+
+class DocusaurusLlmsCodeGenerator {
+  constructor(config = {}) {
+    this.docsDir = config.docsDir || 'docs';
+    this.sidebarPath = config.sidebarPath || 'sidebars.js';
+    this.outputPath = config.outputPath || DEFAULT_OUTPUT;
+    this.docIds = config.docIds || DEFAULT_DOCS;
+  }
+
+  parseFenceInfo(info = '') {
+    const options = {};
+    if (!info) {
+      return { language: '', options };
+    }
+
+    const tokens = info.split(/\s+/).filter(Boolean);
+    const language = tokens.shift() || '';
+
+    tokens.forEach((token) => {
+      const [key, rawValue] = token.split('=');
+      if (!key) {
+        return;
+      }
+      if (rawValue === undefined) {
+        options[key] = true;
+        return;
+      }
+      const value = rawValue.replace(/^"|"$/g, '').replace(/^'|'$/g, '');
+      options[key] = value;
+    });
+
+    return { language, options };
+  }
+
+  async generate() {
+    try {
+      console.log('🔍 Collecting code snippets...');
+
+      const pages = [];
+
+      for (const docId of this.docIds) {
+        const filePath = this.findDocFile(docId);
+        if (!filePath) {
+          console.warn(`⚠️  Unable to locate file for ${docId}`);
+          continue;
+        }
+
+        const { frontmatter, content } = await this.parseDocument(filePath);
+        const title = frontmatter.title || this.deriveTitleFromId(docId);
+        const snippets = this.extractCodeSnippets(docId, title, content);
+
+        if (snippets.length === 0) {
+          console.warn(`ℹ️  Skipping ${docId}: no code snippets found.`);
+          continue;
+        }
+
+        pages.push({ docId, title, snippets });
+      }
+
+      if (pages.length === 0) {
+        console.warn('⚠️  No pages with code snippets were collected.');
+      }
+
+      const output = this.formatOutput(pages);
+
+      await fs.ensureDir(path.dirname(this.outputPath));
+      await fs.writeFile(this.outputPath, output, 'utf-8');
+
+      console.log(`✅ Wrote ${this.outputPath}`);
+    } catch (error) {
+      console.error('❌ Error while generating llms-code:', error);
+      throw error;
+    }
+  }
+
+  findDocFile(docId) {
+    const candidates = [
+      path.join(this.docsDir, `${docId}.md`),
+      path.join(this.docsDir, `${docId}.mdx`),
+      path.join(this.docsDir, docId, 'index.md'),
+      path.join(this.docsDir, docId, 'index.mdx'),
+    ];
+
+    for (const candidate of candidates) {
+      if (fs.pathExistsSync(candidate)) {
+        return candidate;
+      }
+    }
+
+    return null;
+  }
+
+  async parseDocument(filePath) {
+    const raw = await fs.readFile(filePath, 'utf-8');
+    return matter(raw);
+  }
+
+  deriveTitleFromId(docId) {
+    const parts = docId.split('/');
+    return parts[parts.length - 1]
+      .replace(/-/g, ' ')
+      .replace(/\b\w/g, (match) => match.toUpperCase());
+  }
+
+  formatLanguageName(language = '') {
+    const lower = language.toLowerCase();
+    switch (lower) {
+      case 'js':
+      case 'javascript':
+        return 'JavaScript';
+      case 'ts':
+      case 'typescript':
+        return 'TypeScript';
+      case 'bash':
+      case 'sh':
+        return 'Bash';
+      case 'yaml':
+      case 'yml':
+        return 'YAML';
+      case 'json':
+        return 'JSON';
+      case 'tsx':
+        return 'TSX';
+      case 'jsx':
+        return 'JSX';
+      default:
+        return language.toUpperCase();
+    }
+  }
+
+  buildFallbackDescription(snippet) {
+    const langLabel = snippet.language ? this.formatLanguageName(snippet.language) : 'code';
+    const section = snippet.section || 'this section';
+    return `Example showing how to work with ${section} using ${langLabel}.`;
+  }
+
+  currentSection(sections, defaultTitle) {
+    if (!sections || sections.length === 0) {
+      return defaultTitle;
+    }
+    return sections[sections.length - 1];
+  }
+
+  extractContextDescription(buffer, sections, defaultTitle) {
+    const descriptionLines = [];
+
+    for (let index = buffer.length - 1; index >= 0 && descriptionLines.length < 5; index -= 1) {
+      const entry = buffer[index];
+
+      if (entry === '\n') {
+        if (descriptionLines.length > 0) {
+          break;
+        }
+        continue;
+      }
+
+      if (entry.startsWith('```')) {
+        break;
+      }
+
+      if (entry.trim().startsWith('#')) {
+        break;
+      }
+
+      if (entry.trim()) {
+        descriptionLines.push(entry);
+      }
+    }
+
+    descriptionLines.reverse();
+    const rawDescription = descriptionLines.join('\n');
+    const fallback = `Code example from "${this.currentSection(sections, defaultTitle)}"`;
+
+    return summarizeDescription(rawDescription, fallback);
+  }
+
+  extractCodeSnippets(docId, title, content) {
+    const sections = [];
+    const contextBuffer = [];
+    const snippets = [];
+
+    let inCode = false;
+    let codeLanguage = '';
+    let codeLines = [];
+
+    const lines = content.split('\n');
+
+    lines.forEach((line) => {
+      const trimmed = line.trim();
+
+      if (trimmed.startsWith('```')) {
+        const info = trimmed.slice(3).trim();
+        const { language, options } = this.parseFenceInfo(info);
+        if (!inCode) {
+          inCode = true;
+          codeLines = [];
+          codeLanguage = language || '';
+
+          const { description, useCase, fallbackUsed } = this.extractContextDescription(
+            contextBuffer,
+            sections,
+            title,
+          );
+
+          snippets.push({
+            section: this.currentSection(sections, title),
+            language: codeLanguage,
+            options,
+            description,
+            useCase,
+            fallbackUsed,
+            code: null,
+            filePath: options?.title || null,
+            context: [...contextBuffer],
+          });
+        } else {
+          inCode = false;
+          if (snippets.length > 0) {
+            const current = snippets[snippets.length - 1];
+            current.code = codeLines.join('\n').trimEnd();
+            if (!current.filePath) {
+              const titleAttr = current.options?.title;
+              if (titleAttr) {
+                current.filePath = titleAttr;
+              } else {
+                current.filePath = this.inferFilePathFromContext(current.context);
+              }
+            }
+          }
+          codeLines = [];
+          codeLanguage = '';
+        }
+        return;
+      }
+
+      if (inCode) {
+        codeLines.push(line);
+        return;
+      }
+
+      const headingMatch = trimmed.match(HEADING_REGEX);
+      if (headingMatch) {
+        const level = headingMatch[1].length;
+        const headingText = cleanInlineText(headingMatch[2]) || `Heading level ${level}`;
+
+        while (sections.length >= level) {
+          sections.pop();
+        }
+
+        sections.push(headingText);
+        contextBuffer.push('\n');
+        return;
+      }
+
+      if (trimmed === '') {
+        contextBuffer.push('\n');
+      } else {
+        contextBuffer.push(trimmed);
+      }
+
+      if (contextBuffer.length > 50) {
+        contextBuffer.splice(0, contextBuffer.length - 50);
+      }
+    });
+
+    return snippets.filter((snippet) => Boolean(snippet.code));
+  }
+
+  deriveSnippetTitle(snippet, index) {
+    const baseDescription = snippet.description || '';
+
+    if (!snippet.fallbackUsed && baseDescription) {
+      const sentence = baseDescription.split(/(?<=[.!?])/)[0].trim();
+      if (sentence) {
+        return sentence.length > 80 ? `${sentence.slice(0, 77)}…` : sentence;
+      }
+    }
+
+    if (snippet.language) {
+      const langName = this.formatLanguageName(snippet.language);
+      return `Code example ${index + 1}: ${langName} version`;
+    }
+
+    return `Code example ${index + 1}`;
+  }
+
+  formatOutput(pages) {
+    const lines = [];
+
+    pages.forEach((page) => {
+      lines.push(`# ${page.title}`);
+      lines.push(`Source: ${BASE_URL}/${page.docId}`);
+      lines.push('');
+
+      const snippetsBySection = page.snippets.reduce((acc, snippet) => {
+        if (!acc.has(snippet.section)) {
+          acc.set(snippet.section, []);
+        }
+        acc.get(snippet.section).push(snippet);
+        return acc;
+      }, new Map());
+
+      snippetsBySection.forEach((sectionSnippets, sectionName) => {
+        lines.push(`## ${sectionName}`);
+        lines.push('');
+
+        const groups = this.groupVariantSnippets(sectionSnippets);
+
+        groups.forEach((group, index) => {
+          const primary = group.find((snippet) => !snippet.fallbackUsed) || group[0];
+          const description = primary.fallbackUsed
+            ? this.buildFallbackDescription(primary)
+            : primary.description;
+
+          lines.push(`### Example ${index + 1}`);
+          lines.push(`Description: ${description}`);
+
+          const primaryFile = primary.filePath || this.inferFilePathFromContext(primary.context);
+          if (primaryFile) {
+            lines.push(`File: ${primaryFile}`);
+          }
+
+          if (primary.useCase) {
+            lines.push(`Use Case: ${primary.useCase}`);
+          }
+
+          lines.push('');
+
+          group.forEach((variant, variantIndex) => {
+            if (variantIndex > 0) {
+              lines.push('---');
+            }
+
+            const language = variant.language
+              ? `Language: ${this.formatLanguageName(variant.language)}`
+              : 'Language: (unspecified)';
+            lines.push(language);
+
+            const resolvedFile = variant.filePath
+              || this.inferFilePathFromContext(variant.context)
+              || primaryFile;
+            if (resolvedFile && resolvedFile !== primaryFile) {
+              lines.push(`File: ${resolvedFile}`);
+            }
+
+            const fence = variant.language ? `
+```${variant.language}` : '```';
+            lines.push(variant.language ? `
+```${variant.language}` : '```');
+            lines.push(variant.code);
+            lines.push('```');
+            lines.push('');
+          });
+
+          lines.push('');
+        });
+
+        lines.push('');
+      });
+
+      lines.push('');
+    });
+
+    return lines.join('\n').trim() + '\n';
+  }
+
+  groupVariantSnippets(snippets) {
+    const groups = [];
+    let currentGroup = [];
+
+    snippets.forEach((snippet) => {
+      if (currentGroup.length === 0) {
+        currentGroup.push(snippet);
+        return;
+      }
+
+      const previous = currentGroup[currentGroup.length - 1];
+      const sameDescription = (snippet.description || '') === (previous.description || '');
+      const sameFile = (snippet.filePath || '') === (previous.filePath || '');
+
+      if (sameDescription && sameFile) {
+        currentGroup.push(snippet);
+      } else {
+        groups.push(currentGroup);
+        currentGroup = [snippet];
+      }
+    });
+
+    if (currentGroup.length > 0) {
+      groups.push(currentGroup);
+    }
+
+    return groups;
+  }
+
+  inferFilePathFromContext(buffer = []) {
+    for (let index = buffer.length - 1; index >= 0; index -= 1) {
+      const entry = buffer[index];
+      if (typeof entry !== 'string') {
+        continue;
+      }
+      const match = entry.match(/(?:\.|\/)[^\s]*\.(?:js|ts|jsx|tsx|json|ya?ml)/i);
+      if (match) {
+        return match[0];
+      }
+    }
+    return null;
+  }
+}
+
+if (require.main === module) {
+  const { docs, output } = parseArgs();
+  const generator = new DocusaurusLlmsCodeGenerator({
+    docIds: docs,
+    outputPath: output,
+  });
+
+  generator.generate().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+
+module.exports = DocusaurusLlmsCodeGenerator;

From 703d7f5fce7f76ab3e03f46b67eb208e26d6984d Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 11:42:02 +0000
Subject: [PATCH 24/43] Improve language detection

---
 docusaurus/scripts/generate-llms-code.js | 92 ++++++++++++++++++------
 1 file changed, 71 insertions(+), 21 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 1d66e657ab..620577bb08 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -404,18 +404,16 @@ class DocusaurusLlmsCodeGenerator {
             ? this.buildFallbackDescription(primary)
             : primary.description;
 
+          const primaryFile = this.resolveFilePath(primary);
+
           lines.push(`### Example ${index + 1}`);
           lines.push(`Description: ${description}`);
-
-          const primaryFile = primary.filePath || this.inferFilePathFromContext(primary.context);
           if (primaryFile) {
             lines.push(`File: ${primaryFile}`);
           }
-
           if (primary.useCase) {
             lines.push(`Use Case: ${primary.useCase}`);
           }
-
           lines.push('');
 
           group.forEach((variant, variantIndex) => {
@@ -423,22 +421,21 @@ class DocusaurusLlmsCodeGenerator {
               lines.push('---');
             }
 
-            const language = variant.language
-              ? `Language: ${this.formatLanguageName(variant.language)}`
+            const variantFile = this.resolveFilePath(variant);
+            const resolvedLanguage = this.resolveLanguage(variant, variantFile);
+            const languageLabel = resolvedLanguage
+              ? `Language: ${this.formatLanguageName(resolvedLanguage)}`
               : 'Language: (unspecified)';
-            lines.push(language);
+            lines.push(languageLabel);
 
-            const resolvedFile = variant.filePath
-              || this.inferFilePathFromContext(variant.context)
-              || primaryFile;
-            if (resolvedFile && resolvedFile !== primaryFile) {
-              lines.push(`File: ${resolvedFile}`);
+            if (variantFile && variantFile !== primaryFile) {
+              lines.push(`File: ${variantFile}`);
             }
 
-            const fence = variant.language ? `
-```${variant.language}` : '```';
-            lines.push(variant.language ? `
-```${variant.language}` : '```');
+            const fenceLanguage = resolvedLanguage || '';
+            const fence = fenceLanguage ? `
+```${fenceLanguage}` : '```';
+            lines.push(fence);
             lines.push(variant.code);
             lines.push('```');
             lines.push('');
@@ -466,9 +463,9 @@ class DocusaurusLlmsCodeGenerator {
         return;
       }
 
-      const previous = currentGroup[currentGroup.length - 1];
-      const sameDescription = (snippet.description || '') === (previous.description || '');
-      const sameFile = (snippet.filePath || '') === (previous.filePath || '');
+      const last = currentGroup[currentGroup.length - 1];
+      const sameDescription = (snippet.description || '') === (last.description || '');
+      const sameFile = (snippet.filePath || '') === (last.filePath || '');
 
       if (sameDescription && sameFile) {
         currentGroup.push(snippet);
@@ -485,17 +482,70 @@ class DocusaurusLlmsCodeGenerator {
     return groups;
   }
 
+  resolveFilePath(snippet) {
+    if (snippet.filePath) {
+      return snippet.filePath;
+    }
+
+    const inferred = this.inferFilePathFromContext(snippet.context || []);
+    if (inferred) {
+      return inferred;
+    }
+
+    const match = snippet.code.match(/(?:^|\s)([./\w-]+\.(?:js|ts|tsx|jsx|json|ya?ml))/i);
+    if (match) {
+      return match[1];
+    }
+
+    return null;
+  }
+
   inferFilePathFromContext(buffer = []) {
+    const REGEX = /(?:title\s*=\s*)?["']?([./\w-]+\.(?:js|ts|tsx|jsx|json|ya?ml))["']?/i;
+
     for (let index = buffer.length - 1; index >= 0; index -= 1) {
       const entry = buffer[index];
       if (typeof entry !== 'string') {
         continue;
       }
-      const match = entry.match(/(?:\.|\/)[^\s]*\.(?:js|ts|jsx|tsx|json|ya?ml)/i);
+      const match = entry.match(REGEX);
       if (match) {
-        return match[0];
+        return match[1];
       }
     }
+
+    return null;
+  }
+
+  inferLanguageFromFile(filePath) {
+    if (!filePath) {
+      return null;
+    }
+    const extension = filePath.split('.').pop().toLowerCase();
+    switch (extension) {
+      case 'ts':
+      case 'tsx':
+        return extension;
+      case 'js':
+      case 'jsx':
+        return extension;
+      case 'json':
+        return 'json';
+      case 'yml':
+      case 'yaml':
+        return 'yaml';
+      default:
+        return null;
+    }
+  }
+
+  inferLanguageFromCode(code = '') {
+    if (!code) {
+      return null;
+    }
+    if (/import\s+\{?.+\}?.+from\s+['"].+['"]/i.test(code) || /export\s+default/i.test(code)) {
+      return 'ts';
+    }
     return null;
   }
 }

From 46f095eb59bcff056ce3b09b50abdf4ed42585eb Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 13:40:42 +0000
Subject: [PATCH 25/43] Improve formatting and language detection

---
 docusaurus/scripts/generate-llms-code.js | 107 ++++++++++++++++++-----
 1 file changed, 84 insertions(+), 23 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 620577bb08..19fea6223b 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -96,7 +96,65 @@ class DocusaurusLlmsCodeGenerator {
     this.docsDir = config.docsDir || 'docs';
     this.sidebarPath = config.sidebarPath || 'sidebars.js';
     this.outputPath = config.outputPath || DEFAULT_OUTPUT;
-    this.docIds = config.docIds || DEFAULT_DOCS;
+    this.docIds = config.docIds || [];
+  }
+
+  loadSidebarConfig() {
+    try {
+      // Resolve from CWD to allow running from repo root
+      const sidebarAbs = path.resolve(this.sidebarPath);
+      delete require.cache[require.resolve(sidebarAbs)];
+      return require(sidebarAbs);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  async getAllMdFiles(dir, prefix = '') {
+    const files = [];
+    const fullDir = path.join(dir);
+    if (!fs.pathExistsSync(fullDir)) return files;
+    const entries = await fs.readdir(fullDir);
+    for (const entry of entries) {
+      const fullPath = path.join(fullDir, entry);
+      const stat = await fs.stat(fullPath);
+      if (stat.isDirectory()) {
+        const nested = await this.getAllMdFiles(path.join(dir, entry), path.join(prefix, entry));
+        files.push(...nested);
+      } else if (entry.endsWith('.md') || entry.endsWith('.mdx')) {
+        const rel = path.join(prefix, entry).replace(/\\/g, '/');
+        files.push(rel);
+      }
+    }
+    return files;
+  }
+
+  // Convert a docs file path (e.g., guide/intro.md) to a docId (guide/intro)
+  filePathToDocId(filePath) {
+    return filePath.replace(/\.(md|mdx)$/i, '').replace(/^\/*/, '');
+  }
+
+  collectDocIdsFromSidebar(sidebar) {
+    const ids = new Set();
+    const walk = (items) => {
+      if (!Array.isArray(items)) return;
+      for (const item of items) {
+        if (typeof item === 'string') {
+          ids.add(item);
+        } else if (item && typeof item === 'object') {
+          if (item.type === 'doc' && item.id) {
+            ids.add(item.id);
+          }
+          if (item.items) {
+            walk(item.items);
+          }
+        }
+      }
+    };
+    for (const key of Object.keys(sidebar)) {
+      walk(sidebar[key]);
+    }
+    return Array.from(ids);
   }
 
   parseFenceInfo(info = '') {
@@ -130,7 +188,20 @@ class DocusaurusLlmsCodeGenerator {
 
       const pages = [];
 
-      for (const docId of this.docIds) {
+      // Resolve the set of docIds: prefer explicit, else sidebar, else directory scan
+      let docIds = Array.isArray(this.docIds) && this.docIds.length > 0 ? this.docIds : null;
+      if (!docIds) {
+        const sidebar = this.loadSidebarConfig();
+        if (sidebar) {
+          docIds = this.collectDocIdsFromSidebar(sidebar);
+        }
+      }
+      if (!docIds || docIds.length === 0) {
+        const files = await this.getAllMdFiles(this.docsDir);
+        docIds = files.map((f) => this.filePathToDocId(f));
+      }
+
+      for (const docId of docIds) {
         const filePath = this.findDocFile(docId);
         if (!filePath) {
           console.warn(`⚠️  Unable to locate file for ${docId}`);
@@ -398,22 +469,15 @@ class DocusaurusLlmsCodeGenerator {
 
         const groups = this.groupVariantSnippets(sectionSnippets);
 
-        groups.forEach((group, index) => {
+        groups.forEach((group) => {
           const primary = group.find((snippet) => !snippet.fallbackUsed) || group[0];
           const description = primary.fallbackUsed
             ? this.buildFallbackDescription(primary)
             : primary.description;
 
-          const primaryFile = this.resolveFilePath(primary);
-
-          lines.push(`### Example ${index + 1}`);
-          lines.push(`Description: ${description}`);
-          if (primaryFile) {
-            lines.push(`File: ${primaryFile}`);
-          }
-          if (primary.useCase) {
-            lines.push(`Use Case: ${primary.useCase}`);
-          }
+          lines.push('Description');
+          lines.push(description);
+          lines.push(`(Source: ${BASE_URL}/${page.docId})`);
           lines.push('');
 
           group.forEach((variant, variantIndex) => {
@@ -424,17 +488,14 @@ class DocusaurusLlmsCodeGenerator {
             const variantFile = this.resolveFilePath(variant);
             const resolvedLanguage = this.resolveLanguage(variant, variantFile);
             const languageLabel = resolvedLanguage
-              ? `Language: ${this.formatLanguageName(resolvedLanguage)}`
-              : 'Language: (unspecified)';
-            lines.push(languageLabel);
-
-            if (variantFile && variantFile !== primaryFile) {
-              lines.push(`File: ${variantFile}`);
-            }
+              ? this.formatLanguageName(resolvedLanguage)
+              : '(unspecified)';
+            lines.push(`Language: ${languageLabel}`);
+            lines.push(`File path: ${variantFile || '-'}`);
+            lines.push('');
 
-            const fenceLanguage = resolvedLanguage || '';
-            const fence = fenceLanguage ? `
-```${fenceLanguage}` : '```';
+            const fence = resolvedLanguage ? `
+```${resolvedLanguage}` : '```';
             lines.push(fence);
             lines.push(variant.code);
             lines.push('```');

From efd5cc98eb0cb825d43b7e22128689bf72c0cd27 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 14:57:02 +0000
Subject: [PATCH 26/43] Improve generation

---
 docusaurus/scripts/generate-llms-code.js | 181 +++++------------------
 1 file changed, 35 insertions(+), 146 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 19fea6223b..1d66e657ab 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -96,65 +96,7 @@ class DocusaurusLlmsCodeGenerator {
     this.docsDir = config.docsDir || 'docs';
     this.sidebarPath = config.sidebarPath || 'sidebars.js';
     this.outputPath = config.outputPath || DEFAULT_OUTPUT;
-    this.docIds = config.docIds || [];
-  }
-
-  loadSidebarConfig() {
-    try {
-      // Resolve from CWD to allow running from repo root
-      const sidebarAbs = path.resolve(this.sidebarPath);
-      delete require.cache[require.resolve(sidebarAbs)];
-      return require(sidebarAbs);
-    } catch (error) {
-      return null;
-    }
-  }
-
-  async getAllMdFiles(dir, prefix = '') {
-    const files = [];
-    const fullDir = path.join(dir);
-    if (!fs.pathExistsSync(fullDir)) return files;
-    const entries = await fs.readdir(fullDir);
-    for (const entry of entries) {
-      const fullPath = path.join(fullDir, entry);
-      const stat = await fs.stat(fullPath);
-      if (stat.isDirectory()) {
-        const nested = await this.getAllMdFiles(path.join(dir, entry), path.join(prefix, entry));
-        files.push(...nested);
-      } else if (entry.endsWith('.md') || entry.endsWith('.mdx')) {
-        const rel = path.join(prefix, entry).replace(/\\/g, '/');
-        files.push(rel);
-      }
-    }
-    return files;
-  }
-
-  // Convert a docs file path (e.g., guide/intro.md) to a docId (guide/intro)
-  filePathToDocId(filePath) {
-    return filePath.replace(/\.(md|mdx)$/i, '').replace(/^\/*/, '');
-  }
-
-  collectDocIdsFromSidebar(sidebar) {
-    const ids = new Set();
-    const walk = (items) => {
-      if (!Array.isArray(items)) return;
-      for (const item of items) {
-        if (typeof item === 'string') {
-          ids.add(item);
-        } else if (item && typeof item === 'object') {
-          if (item.type === 'doc' && item.id) {
-            ids.add(item.id);
-          }
-          if (item.items) {
-            walk(item.items);
-          }
-        }
-      }
-    };
-    for (const key of Object.keys(sidebar)) {
-      walk(sidebar[key]);
-    }
-    return Array.from(ids);
+    this.docIds = config.docIds || DEFAULT_DOCS;
   }
 
   parseFenceInfo(info = '') {
@@ -188,20 +130,7 @@ class DocusaurusLlmsCodeGenerator {
 
       const pages = [];
 
-      // Resolve the set of docIds: prefer explicit, else sidebar, else directory scan
-      let docIds = Array.isArray(this.docIds) && this.docIds.length > 0 ? this.docIds : null;
-      if (!docIds) {
-        const sidebar = this.loadSidebarConfig();
-        if (sidebar) {
-          docIds = this.collectDocIdsFromSidebar(sidebar);
-        }
-      }
-      if (!docIds || docIds.length === 0) {
-        const files = await this.getAllMdFiles(this.docsDir);
-        docIds = files.map((f) => this.filePathToDocId(f));
-      }
-
-      for (const docId of docIds) {
+      for (const docId of this.docIds) {
         const filePath = this.findDocFile(docId);
         if (!filePath) {
           console.warn(`⚠️  Unable to locate file for ${docId}`);
@@ -469,15 +398,24 @@ class DocusaurusLlmsCodeGenerator {
 
         const groups = this.groupVariantSnippets(sectionSnippets);
 
-        groups.forEach((group) => {
+        groups.forEach((group, index) => {
           const primary = group.find((snippet) => !snippet.fallbackUsed) || group[0];
           const description = primary.fallbackUsed
             ? this.buildFallbackDescription(primary)
             : primary.description;
 
-          lines.push('Description');
-          lines.push(description);
-          lines.push(`(Source: ${BASE_URL}/${page.docId})`);
+          lines.push(`### Example ${index + 1}`);
+          lines.push(`Description: ${description}`);
+
+          const primaryFile = primary.filePath || this.inferFilePathFromContext(primary.context);
+          if (primaryFile) {
+            lines.push(`File: ${primaryFile}`);
+          }
+
+          if (primary.useCase) {
+            lines.push(`Use Case: ${primary.useCase}`);
+          }
+
           lines.push('');
 
           group.forEach((variant, variantIndex) => {
@@ -485,18 +423,22 @@ class DocusaurusLlmsCodeGenerator {
               lines.push('---');
             }
 
-            const variantFile = this.resolveFilePath(variant);
-            const resolvedLanguage = this.resolveLanguage(variant, variantFile);
-            const languageLabel = resolvedLanguage
-              ? this.formatLanguageName(resolvedLanguage)
-              : '(unspecified)';
-            lines.push(`Language: ${languageLabel}`);
-            lines.push(`File path: ${variantFile || '-'}`);
-            lines.push('');
+            const language = variant.language
+              ? `Language: ${this.formatLanguageName(variant.language)}`
+              : 'Language: (unspecified)';
+            lines.push(language);
+
+            const resolvedFile = variant.filePath
+              || this.inferFilePathFromContext(variant.context)
+              || primaryFile;
+            if (resolvedFile && resolvedFile !== primaryFile) {
+              lines.push(`File: ${resolvedFile}`);
+            }
 
-            const fence = resolvedLanguage ? `
-```${resolvedLanguage}` : '```';
-            lines.push(fence);
+            const fence = variant.language ? `
+```${variant.language}` : '```';
+            lines.push(variant.language ? `
+```${variant.language}` : '```');
             lines.push(variant.code);
             lines.push('```');
             lines.push('');
@@ -524,9 +466,9 @@ class DocusaurusLlmsCodeGenerator {
         return;
       }
 
-      const last = currentGroup[currentGroup.length - 1];
-      const sameDescription = (snippet.description || '') === (last.description || '');
-      const sameFile = (snippet.filePath || '') === (last.filePath || '');
+      const previous = currentGroup[currentGroup.length - 1];
+      const sameDescription = (snippet.description || '') === (previous.description || '');
+      const sameFile = (snippet.filePath || '') === (previous.filePath || '');
 
       if (sameDescription && sameFile) {
         currentGroup.push(snippet);
@@ -543,70 +485,17 @@ class DocusaurusLlmsCodeGenerator {
     return groups;
   }
 
-  resolveFilePath(snippet) {
-    if (snippet.filePath) {
-      return snippet.filePath;
-    }
-
-    const inferred = this.inferFilePathFromContext(snippet.context || []);
-    if (inferred) {
-      return inferred;
-    }
-
-    const match = snippet.code.match(/(?:^|\s)([./\w-]+\.(?:js|ts|tsx|jsx|json|ya?ml))/i);
-    if (match) {
-      return match[1];
-    }
-
-    return null;
-  }
-
   inferFilePathFromContext(buffer = []) {
-    const REGEX = /(?:title\s*=\s*)?["']?([./\w-]+\.(?:js|ts|tsx|jsx|json|ya?ml))["']?/i;
-
     for (let index = buffer.length - 1; index >= 0; index -= 1) {
       const entry = buffer[index];
       if (typeof entry !== 'string') {
         continue;
       }
-      const match = entry.match(REGEX);
+      const match = entry.match(/(?:\.|\/)[^\s]*\.(?:js|ts|jsx|tsx|json|ya?ml)/i);
       if (match) {
-        return match[1];
+        return match[0];
       }
     }
-
-    return null;
-  }
-
-  inferLanguageFromFile(filePath) {
-    if (!filePath) {
-      return null;
-    }
-    const extension = filePath.split('.').pop().toLowerCase();
-    switch (extension) {
-      case 'ts':
-      case 'tsx':
-        return extension;
-      case 'js':
-      case 'jsx':
-        return extension;
-      case 'json':
-        return 'json';
-      case 'yml':
-      case 'yaml':
-        return 'yaml';
-      default:
-        return null;
-    }
-  }
-
-  inferLanguageFromCode(code = '') {
-    if (!code) {
-      return null;
-    }
-    if (/import\s+\{?.+\}?.+from\s+['"].+['"]/i.test(code) || /export\s+default/i.test(code)) {
-      return 'ts';
-    }
     return null;
   }
 }

From 91644b89ec5c1f9181afa6c1a61851db7e5fefb4 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 15:48:23 +0000
Subject: [PATCH 27/43] Enhance file path and title logic

---
 docusaurus/scripts/generate-llms-code.js | 43 +++++++++++++++++++++---
 1 file changed, 39 insertions(+), 4 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 1d66e657ab..08172666ec 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -99,6 +99,18 @@ class DocusaurusLlmsCodeGenerator {
     this.docIds = config.docIds || DEFAULT_DOCS;
   }
 
+  normalizeTitlePath(value) {
+    if (!value || typeof value !== 'string') return null;
+    let v = value.trim();
+    if (/^path\s*:/i.test(v)) {
+      v = v.replace(/^path\s*:\s*/i, '');
+    }
+    if (v.includes(' or ')) {
+      v = v.split(' or ')[0].trim();
+    }
+    return v || null;
+  }
+
   parseFenceInfo(info = '') {
     const options = {};
     if (!info) {
@@ -302,7 +314,7 @@ class DocusaurusLlmsCodeGenerator {
             useCase,
             fallbackUsed,
             code: null,
-            filePath: options?.title || null,
+            filePath: this.normalizeTitlePath(options?.title) || null,
             context: [...contextBuffer],
           });
         } else {
@@ -311,11 +323,13 @@ class DocusaurusLlmsCodeGenerator {
             const current = snippets[snippets.length - 1];
             current.code = codeLines.join('\n').trimEnd();
             if (!current.filePath) {
-              const titleAttr = current.options?.title;
+              const titleAttr = this.normalizeTitlePath(current.options?.title);
               if (titleAttr) {
                 current.filePath = titleAttr;
               } else {
-                current.filePath = this.inferFilePathFromContext(current.context);
+                // Prefer nearby "path:" hints before generic filename regex
+                const ctxPath = this.inferFilePathFromContext(current.context, { preferHints: true });
+                current.filePath = ctxPath;
               }
             }
           }
@@ -485,7 +499,28 @@ class DocusaurusLlmsCodeGenerator {
     return groups;
   }
 
-  inferFilePathFromContext(buffer = []) {
+  inferFilePathFromContext(buffer = [], opts = { preferHints: false }) {
+    // 1) Prefer explicit "path:" hints nearby (last ~20 lines)
+    if (opts && opts.preferHints) {
+      const start = Math.max(0, buffer.length - 20);
+      for (let index = buffer.length - 1; index >= start; index -= 1) {
+        const entry = buffer[index];
+        if (typeof entry !== 'string') {
+          continue;
+        }
+        const hint = entry.match(/(?:^|\b)path\s*:\s*([^\s,;]+[^\s]*)/i);
+        if (hint && hint[1]) {
+          const normalized = this.normalizeTitlePath(hint[0]);
+          if (normalized) {
+            return normalized;
+          }
+          // Fallback to raw capture
+          return hint[1];
+        }
+      }
+    }
+
+    // 2) Fallback: scan for any obvious file-like tokens with known extensions
     for (let index = buffer.length - 1; index >= 0; index -= 1) {
       const entry = buffer[index];
       if (typeof entry !== 'string') {

From 1b9f0076016968363af819bff8546a46978c7271 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 15:48:48 +0000
Subject: [PATCH 28/43] Improve fenced code blocks detection and generation

---
 docusaurus/scripts/generate-llms-code.js | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 08172666ec..2dbfc2d662 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -449,10 +449,9 @@ class DocusaurusLlmsCodeGenerator {
               lines.push(`File: ${resolvedFile}`);
             }
 
-            const fence = variant.language ? `
-```${variant.language}` : '```';
-            lines.push(variant.language ? `
-```${variant.language}` : '```');
+            // Proper fenced code block without spurious leading newlines
+            const fence = variant.language ? `\`\`\`${variant.language}` : '```';
+            lines.push(fence);
             lines.push(variant.code);
             lines.push('```');
             lines.push('');

From 4d86acdcc3fca976d38d9924fce85f233dfce7f1 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 15:49:16 +0000
Subject: [PATCH 29/43] Handle dependencies "lazy loading"

---
 docusaurus/scripts/generate-llms-code.js | 31 ++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 2dbfc2d662..e521b6411b 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -1,8 +1,35 @@
 #!/usr/bin/env node
 
-const fs = require('fs-extra');
+// Prefer optional deps; fall back to built-ins for sandboxed runs
+let fs = null;
+try {
+  fs = require('fs-extra');
+} catch (e) {
+  fs = require('fs');
+  // polyfills to mimic fs-extra subset used here
+  fs.ensureDir = async (dir) => fs.promises.mkdir(dir, { recursive: true });
+  fs.pathExistsSync = (p) => fs.existsSync(p);
+  fs.writeFile = fs.promises.writeFile.bind(fs.promises);
+  fs.readFile = fs.promises.readFile.bind(fs.promises);
+}
 const path = require('path');
-const matter = require('gray-matter');
+
+let matter = null;
+try {
+  matter = require('gray-matter');
+} catch (e) {
+  // Minimal frontmatter parser fallback
+  matter = (raw) => {
+    if (raw.startsWith('---')) {
+      const end = raw.indexOf('\n---', 3);
+      if (end !== -1) {
+        const body = raw.slice(end + 4);
+        return { data: {}, content: body };
+      }
+    }
+    return { data: {}, content: raw };
+  };
+}
 
 const DEFAULT_DOCS = [
   'cms/admin-panel-customization/bundlers',

From 3159a2500cb96d69f2b6cc3aede6ced1b17fad15 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 15:49:37 +0000
Subject: [PATCH 30/43] Improve metadata parsing

---
 docusaurus/scripts/generate-llms-code.js | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index e521b6411b..f16aefd9d1 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -176,9 +176,10 @@ class DocusaurusLlmsCodeGenerator {
           continue;
         }
 
-        const { frontmatter, content } = await this.parseDocument(filePath);
-        const title = frontmatter.title || this.deriveTitleFromId(docId);
-        const snippets = this.extractCodeSnippets(docId, title, content);
+        const parsed = await this.parseDocument(filePath);
+        const fm = parsed.data || parsed.frontmatter || {};
+        const title = fm.title || this.deriveTitleFromId(docId);
+        const snippets = this.extractCodeSnippets(docId, title, parsed.content);
 
         if (snippets.length === 0) {
           console.warn(`ℹ️  Skipping ${docId}: no code snippets found.`);

From fc23ce59b16f877fd1aac74ca530115214ca45f8 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 15:50:04 +0000
Subject: [PATCH 31/43] Print out llms-code to stdout

---
 docusaurus/scripts/generate-llms-code.js | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index f16aefd9d1..299243a64b 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -195,6 +195,13 @@ class DocusaurusLlmsCodeGenerator {
 
       const output = this.formatOutput(pages);
 
+      // Support stdout preview when --output - is provided
+      if (this.outputPath === '-' || this.outputPath === '/dev/stdout') {
+        process.stdout.write(output);
+        console.log('\n✅ Printed llms-code to stdout');
+        return;
+      }
+
       await fs.ensureDir(path.dirname(this.outputPath));
       await fs.writeFile(this.outputPath, output, 'utf-8');
 

From bf550fbfbc456b78fbe52f431f859068e88b6cbd Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 16:08:03 +0000
Subject: [PATCH 32/43] Improve file path and language detection further

---
 docusaurus/scripts/generate-llms-code.js | 49 +++++++++++++++++++++---
 1 file changed, 43 insertions(+), 6 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 299243a64b..6d8c3abe05 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -267,6 +267,41 @@ class DocusaurusLlmsCodeGenerator {
     }
   }
 
+  // Prefer language implied by file extension when it contradicts the code fence
+  resolveLanguage(fenceLanguage = '', filePath = '') {
+    const ext = (filePath || '').split('.').pop()?.toLowerCase() || '';
+    const fence = (fenceLanguage || '').toLowerCase();
+
+    const extToLang = {
+      js: 'js',
+      jsx: 'jsx',
+      ts: 'ts',
+      tsx: 'tsx',
+      json: 'json',
+      yml: 'yaml',
+      yaml: 'yaml',
+      sh: 'bash',
+      bash: 'bash',
+    };
+
+    const preferred = extToLang[ext] || '';
+    if (!preferred) {
+      return fenceLanguage || '';
+    }
+
+    // If no fence language, adopt the extension-derived language
+    if (!fence) {
+      return preferred;
+    }
+
+    // If they clearly contradict across JS/TS families, prefer the file extension
+    const family = (lang) => (lang.startsWith('ts') ? 'ts' : (lang.startsWith('js') ? 'js' : lang));
+    if (family(fence) !== family(preferred)) {
+      return preferred;
+    }
+    return fenceLanguage || preferred;
+  }
+
   buildFallbackDescription(snippet) {
     const langLabel = snippet.language ? this.formatLanguageName(snippet.language) : 'code';
     const section = snippet.section || 'this section';
@@ -472,20 +507,22 @@ class DocusaurusLlmsCodeGenerator {
               lines.push('---');
             }
 
-            const language = variant.language
-              ? `Language: ${this.formatLanguageName(variant.language)}`
-              : 'Language: (unspecified)';
-            lines.push(language);
-
             const resolvedFile = variant.filePath
               || this.inferFilePathFromContext(variant.context)
               || primaryFile;
+
+            const chosenLang = this.resolveLanguage(variant.language, resolvedFile);
+            const language = chosenLang
+              ? `Language: ${this.formatLanguageName(chosenLang)}`
+              : 'Language: (unspecified)';
+            lines.push(language);
+
             if (resolvedFile && resolvedFile !== primaryFile) {
               lines.push(`File: ${resolvedFile}`);
             }
 
             // Proper fenced code block without spurious leading newlines
-            const fence = variant.language ? `\`\`\`${variant.language}` : '```';
+            const fence = chosenLang ? `\`\`\`${chosenLang}` : '```';
             lines.push(fence);
             lines.push(variant.code);
             lines.push('```');

From c5615abbb50a154062d134c5c1e9e9760babde2c Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 16:18:47 +0000
Subject: [PATCH 33/43] Handle more languages in a heuristic way

---
 docusaurus/scripts/generate-llms-code.js | 64 +++++++++++++++---------
 1 file changed, 39 insertions(+), 25 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 6d8c3abe05..fadad6eb73 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -267,39 +267,53 @@ class DocusaurusLlmsCodeGenerator {
     }
   }
 
-  // Prefer language implied by file extension when it contradicts the code fence
-  resolveLanguage(fenceLanguage = '', filePath = '') {
-    const ext = (filePath || '').split('.').pop()?.toLowerCase() || '';
+  // Resolve language from fence, file path, and code content (content-first heuristics)
+  resolveLanguage(fenceLanguage = '', filePath = '', code = '') {
+    const ext = (filePath || '').split('/').pop() || '';
+    const extLower = (ext.split('.').pop() || '').toLowerCase();
     const fence = (fenceLanguage || '').toLowerCase();
-
+    const head = (code || '').split('\n').map((l) => l.trim()).filter(Boolean).slice(0, 10);
+
+    // Content-first heuristics
+    const first = head[0] || '';
+    if (/^#!\/.+\b(bash|sh|env\s+bash|env\s+sh)\b/.test(first)) return 'bash';
+    if (/^FROM\s+\S+/i.test(first) || head.some((l) => /^(RUN|CMD|ENTRYPOINT|COPY|ADD|WORKDIR|ENV|EXPOSE|USER)\b/i.test(l))) return 'dockerfile';
+    if (head.some((l) => /^(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|WITH)\b/i.test(l))) return 'sql';
+    if (/^(query|mutation|subscription|fragment|schema)\b/.test(first)) return 'graphql';
+    if (first === '---' || head.some((l) => /^\w[\w-]*\s*:\s*[^\s]/.test(l))) return 'yaml';
+    if (/^[\[{]/.test(first) && head.some((l) => /:\s*/.test(l))) return 'json';
+    if (head.length > 0 && head.every((l) => /^(?:\$\s+)?(npm|yarn|pnpm|npx|strapi|node|cd|cp|mv|rm|mkdir|curl|wget|git|docker|kubectl|helm|openssl|grep|sed|awk|touch|chmod|chown|tee|cat)\b/.test(l) || l.startsWith('#'))) return 'bash';
+
+    // Extension-derived mapping
     const extToLang = {
-      js: 'js',
-      jsx: 'jsx',
-      ts: 'ts',
-      tsx: 'tsx',
-      json: 'json',
-      yml: 'yaml',
-      yaml: 'yaml',
-      sh: 'bash',
-      bash: 'bash',
+      js: 'js', jsx: 'jsx',
+      ts: 'ts', tsx: 'tsx',
+      json: 'json', yml: 'yaml', yaml: 'yaml',
+      sh: 'bash', bash: 'bash', zsh: 'bash',
+      graphql: 'graphql', gql: 'graphql',
+      sql: 'sql',
+      env: 'dotenv',
+      dockerfile: 'dockerfile',
+      html: 'html', css: 'css', scss: 'scss',
+      py: 'python', rb: 'ruby', go: 'go', php: 'php', java: 'java',
+      c: 'c', h: 'c', cc: 'cpp', cpp: 'cpp', cxx: 'cpp', cs: 'csharp',
+      ini: 'ini', toml: 'toml', md: 'md', mdx: 'mdx',
     };
 
-    const preferred = extToLang[ext] || '';
-    if (!preferred) {
-      return fenceLanguage || '';
-    }
+    let preferred = '';
+    if (/^dockerfile$/i.test(ext)) preferred = 'dockerfile';
+    else if (/^\.env(\..+)?$/i.test(ext)) preferred = 'dotenv';
+    else preferred = extToLang[extLower] || '';
 
     // If no fence language, adopt the extension-derived language
-    if (!fence) {
-      return preferred;
-    }
+    if (!fence && preferred) return preferred;
 
-    // If they clearly contradict across JS/TS families, prefer the file extension
+    // JS/TS family resolution: prefer file extension if it contradicts fence
     const family = (lang) => (lang.startsWith('ts') ? 'ts' : (lang.startsWith('js') ? 'js' : lang));
-    if (family(fence) !== family(preferred)) {
-      return preferred;
-    }
-    return fenceLanguage || preferred;
+    if (preferred && family(fence) !== family(preferred)) return preferred;
+
+    // Fall back to fence or preferred
+    return fenceLanguage || preferred || '';
   }
 
   buildFallbackDescription(snippet) {

From dd5aa9f643ebb14fbb50bee77e09d9bf9f699419 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 16:26:55 +0000
Subject: [PATCH 34/43] Add normalizeOutputPath to better handle carelss
 mistakes and add support for powershell blocks

---
 docusaurus/scripts/generate-llms-code.js | 33 +++++++++++++++++++-----
 1 file changed, 26 insertions(+), 7 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index fadad6eb73..6eba87397b 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -253,6 +253,11 @@ class DocusaurusLlmsCodeGenerator {
       case 'bash':
       case 'sh':
         return 'Bash';
+      case 'powershell':
+      case 'pwsh':
+        return 'PowerShell';
+      case 'fish':
+        return 'Fish';
       case 'yaml':
       case 'yml':
         return 'YAML';
@@ -281,8 +286,12 @@ class DocusaurusLlmsCodeGenerator {
     if (head.some((l) => /^(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|WITH)\b/i.test(l))) return 'sql';
     if (/^(query|mutation|subscription|fragment|schema)\b/.test(first)) return 'graphql';
     if (first === '---' || head.some((l) => /^\w[\w-]*\s*:\s*[^\s]/.test(l))) return 'yaml';
-    if (/^[\[{]/.test(first) && head.some((l) => /:\s*/.test(l))) return 'json';
+    if (/^[\[{]/.test(first) && head.some((l) => /"?\w+"?\s*:\s*/.test(l))) return 'json';
     if (head.length > 0 && head.every((l) => /^(?:\$\s+)?(npm|yarn|pnpm|npx|strapi|node|cd|cp|mv|rm|mkdir|curl|wget|git|docker|kubectl|helm|openssl|grep|sed|awk|touch|chmod|chown|tee|cat)\b/.test(l) || l.startsWith('#'))) return 'bash';
+    if (head.some((l) => /^(param\s*\(|Write-Host\b|Get-Item\b|Set-Item\b|New-Object\b)/i.test(l))) return 'powershell';
+    if (head.some((l) => /^(function\s+\w+|set\s+-l\s+\w+|end\s*$)/.test(l))) return 'fish';
+    if (/(export\s+(interface|type)\b|:\s*\w+<|\bimplements\b|\bas\s+const\b)/.test(code)) return 'ts';
+    if (/from\s+['"][^'"\n]+\.ts['"]/i.test(code)) return 'ts';
 
     // Extension-derived mapping
     const extToLang = {
@@ -293,12 +302,13 @@ class DocusaurusLlmsCodeGenerator {
       graphql: 'graphql', gql: 'graphql',
       sql: 'sql',
       env: 'dotenv',
-      dockerfile: 'dockerfile',
+      dockerfile: 'dockerfile', ps1: 'powershell', psm1: 'powershell', fish: 'fish',
       html: 'html', css: 'css', scss: 'scss',
       py: 'python', rb: 'ruby', go: 'go', php: 'php', java: 'java',
       c: 'c', h: 'c', cc: 'cpp', cpp: 'cpp', cxx: 'cpp', cs: 'csharp',
       ini: 'ini', toml: 'toml', md: 'md', mdx: 'mdx',
     };
+    
 
     let preferred = '';
     if (/^dockerfile$/i.test(ext)) preferred = 'dockerfile';
@@ -316,6 +326,15 @@ class DocusaurusLlmsCodeGenerator {
     return fenceLanguage || preferred || '';
   }
 
+  normalizeOutputPath(p) {
+    if (!p) return p;
+    if (/^https?:\/\//i.test(p)) return p;
+    let out = p;
+    if (out.startsWith('//')) out = out.replace(/^\/+/, '/');
+    out = out.replace(/([^:])\/\/+/, '$1/');
+    return out;
+  }
+
   buildFallbackDescription(snippet) {
     const langLabel = snippet.language ? this.formatLanguageName(snippet.language) : 'code';
     const section = snippet.section || 'this section';
@@ -505,7 +524,7 @@ class DocusaurusLlmsCodeGenerator {
           lines.push(`### Example ${index + 1}`);
           lines.push(`Description: ${description}`);
 
-          const primaryFile = primary.filePath || this.inferFilePathFromContext(primary.context);
+          const primaryFile = this.normalizeOutputPath(primary.filePath || this.inferFilePathFromContext(primary.context));
           if (primaryFile) {
             lines.push(`File: ${primaryFile}`);
           }
@@ -521,11 +540,11 @@ class DocusaurusLlmsCodeGenerator {
               lines.push('---');
             }
 
-            const resolvedFile = variant.filePath
-              || this.inferFilePathFromContext(variant.context)
-              || primaryFile;
+            const resolvedFile = this.normalizeOutputPath(
+              variant.filePath || this.inferFilePathFromContext(variant.context) || primaryFile
+            );
 
-            const chosenLang = this.resolveLanguage(variant.language, resolvedFile);
+            const chosenLang = this.resolveLanguage(variant.language, resolvedFile, variant.code);
             const language = chosenLang
               ? `Language: ${this.formatLanguageName(chosenLang)}`
               : 'Language: (unspecified)';

From 028260c851345dda7501c5abf06b50a67b57d163 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 16:52:41 +0000
Subject: [PATCH 35/43] Add support for anchors in sources

---
 docusaurus/scripts/generate-llms-code.js | 32 +++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 6eba87397b..869842287a 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -88,6 +88,7 @@ const parseArgs = () => {
   const args = process.argv.slice(2);
   const docs = [];
   let output = DEFAULT_OUTPUT;
+  let anchors = false;
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -104,6 +105,8 @@ const parseArgs = () => {
       if (value) {
         output = value;
       }
+    } else if (arg === '--anchors' || arg === '--with-anchors') {
+      anchors = true;
     } else if (arg === '--help' || arg === '-h') {
       console.log('Usage: node generate-llms-code.js [--docs docA,docB] [--output path/to/file]');
       process.exit(0);
@@ -115,6 +118,7 @@ const parseArgs = () => {
   return {
     docs: docs.length > 0 ? docs : DEFAULT_DOCS,
     output,
+    anchors,
   };
 };
 
@@ -124,6 +128,7 @@ class DocusaurusLlmsCodeGenerator {
     this.sidebarPath = config.sidebarPath || 'sidebars.js';
     this.outputPath = config.outputPath || DEFAULT_OUTPUT;
     this.docIds = config.docIds || DEFAULT_DOCS;
+    this.includeSectionAnchors = Boolean(config.includeSectionAnchors);
   }
 
   normalizeTitlePath(value) {
@@ -326,6 +331,25 @@ class DocusaurusLlmsCodeGenerator {
     return fenceLanguage || preferred || '';
   }
 
+  // Slugify heading text similarly to GitHub/Docusaurus and dedupe within a page
+  slugify(text, seen) {
+    if (!text) return '';
+    let slug = String(text)
+      .toLowerCase()
+      .normalize('NFKD')
+      .replace(/[\u0300-\u036f]/g, '') // strip diacritics
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .replace(/-{2,}/g, '-');
+    if (!seen.has(slug)) {
+      seen.set(slug, 0);
+      return slug;
+    }
+    const n = seen.get(slug) + 1;
+    seen.set(slug, n);
+    return `${slug}-${n}`;
+  }
+
   normalizeOutputPath(p) {
     if (!p) return p;
     if (/^https?:\/\//i.test(p)) return p;
@@ -509,8 +533,13 @@ class DocusaurusLlmsCodeGenerator {
         return acc;
       }, new Map());
 
+      const seenSlugs = new Map();
       snippetsBySection.forEach((sectionSnippets, sectionName) => {
         lines.push(`## ${sectionName}`);
+        if (this.includeSectionAnchors) {
+          const anchor = this.slugify(sectionName, seenSlugs);
+          lines.push(`Source: ${BASE_URL}/${page.docId}#${anchor}`);
+        }
         lines.push('');
 
         const groups = this.groupVariantSnippets(sectionSnippets);
@@ -640,10 +669,11 @@ class DocusaurusLlmsCodeGenerator {
 }
 
 if (require.main === module) {
-  const { docs, output } = parseArgs();
+  const { docs, output, anchors } = parseArgs();
   const generator = new DocusaurusLlmsCodeGenerator({
     docIds: docs,
     outputPath: output,
+    includeSectionAnchors: anchors,
   });
 
   generator.generate().catch((error) => {

From 033628d75e783d7448635691b19964638e11f511 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 17:18:51 +0000
Subject: [PATCH 36/43] Handle custom headings

---
 docusaurus/scripts/generate-llms-code.js | 31 ++++++++++++++++++------
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 869842287a..4cd6132efb 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -184,14 +184,16 @@ class DocusaurusLlmsCodeGenerator {
         const parsed = await this.parseDocument(filePath);
         const fm = parsed.data || parsed.frontmatter || {};
         const title = fm.title || this.deriveTitleFromId(docId);
-        const snippets = this.extractCodeSnippets(docId, title, parsed.content);
+        const extracted = this.extractCodeSnippets(docId, title, parsed.content);
+        const snippets = extracted.snippets || [];
+        const sectionAnchors = extracted.sectionAnchors || {};
 
         if (snippets.length === 0) {
           console.warn(`ℹ️  Skipping ${docId}: no code snippets found.`);
           continue;
         }
 
-        pages.push({ docId, title, snippets });
+        pages.push({ docId, title, snippets, sectionAnchors });
       }
 
       if (pages.length === 0) {
@@ -290,8 +292,14 @@ class DocusaurusLlmsCodeGenerator {
     if (/^FROM\s+\S+/i.test(first) || head.some((l) => /^(RUN|CMD|ENTRYPOINT|COPY|ADD|WORKDIR|ENV|EXPOSE|USER)\b/i.test(l))) return 'dockerfile';
     if (head.some((l) => /^(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|WITH)\b/i.test(l))) return 'sql';
     if (/^(query|mutation|subscription|fragment|schema)\b/.test(first)) return 'graphql';
-    if (first === '---' || head.some((l) => /^\w[\w-]*\s*:\s*[^\s]/.test(l))) return 'yaml';
-    if (/^[\[{]/.test(first) && head.some((l) => /"?\w+"?\s*:\s*/.test(l))) return 'json';
+    // JS/TS module cues before YAML/JSON
+    if (/(?:^|\b)(module\.exports|require\(["']|exports?\.|console\.log\()/.test(code)) return extLower.startsWith('ts') ? 'ts' : 'js';
+    if (/(?:^|\b)(import\s+[^;]+from\s+["'][^"']+["']|export\s+(default|const|function|class)\b)/.test(code)) return extLower.startsWith('ts') ? 'ts' : 'js';
+    // YAML detection: frontmatter or multiple key: value lines without JS syntax
+    const yamlKeyLines = head.filter((l) => /^\w[\w-]*\s*:\s*\S/.test(l)).length;
+    if (first === '---' || (yamlKeyLines >= 2 && !/[{}();]/.test(head.join(' ')))) return 'yaml';
+    // JSON detection: leading brace/bracket and key: value patterns, but avoid JS/TS
+    if (/^[\[{]/.test(first) && head.some((l) => /"?\w+"?\s*:\s*/.test(l)) && !/(module\.exports|import\s|export\s)/.test(code)) return 'json';
     if (head.length > 0 && head.every((l) => /^(?:\$\s+)?(npm|yarn|pnpm|npx|strapi|node|cd|cp|mv|rm|mkdir|curl|wget|git|docker|kubectl|helm|openssl|grep|sed|awk|touch|chmod|chown|tee|cat)\b/.test(l) || l.startsWith('#'))) return 'bash';
     if (head.some((l) => /^(param\s*\(|Write-Host\b|Get-Item\b|Set-Item\b|New-Object\b)/i.test(l))) return 'powershell';
     if (head.some((l) => /^(function\s+\w+|set\s+-l\s+\w+|end\s*$)/.test(l))) return 'fish';
@@ -409,6 +417,7 @@ class DocusaurusLlmsCodeGenerator {
     const sections = [];
     const contextBuffer = [];
     const snippets = [];
+    const sectionAnchors = {};
 
     let inCode = false;
     let codeLanguage = '';
@@ -474,13 +483,20 @@ class DocusaurusLlmsCodeGenerator {
       const headingMatch = trimmed.match(HEADING_REGEX);
       if (headingMatch) {
         const level = headingMatch[1].length;
-        const headingText = cleanInlineText(headingMatch[2]) || `Heading level ${level}`;
+        const rawHeading = headingMatch[2];
+        const customAnchorMatch = rawHeading.match(/\{#([A-Za-z0-9\-_]+)\}/);
+        const customAnchor = customAnchorMatch ? customAnchorMatch[1] : null;
+        const headingBase = rawHeading.replace(/\{#([A-Za-z0-9\-_]+)\}/, '').trim();
+        const headingText = cleanInlineText(headingBase) || `Heading level ${level}`;
 
         while (sections.length >= level) {
           sections.pop();
         }
 
         sections.push(headingText);
+        if (customAnchor) {
+          sectionAnchors[headingText] = customAnchor;
+        }
         contextBuffer.push('\n');
         return;
       }
@@ -496,7 +512,7 @@ class DocusaurusLlmsCodeGenerator {
       }
     });
 
-    return snippets.filter((snippet) => Boolean(snippet.code));
+    return { snippets: snippets.filter((snippet) => Boolean(snippet.code)), sectionAnchors };
   }
 
   deriveSnippetTitle(snippet, index) {
@@ -537,7 +553,8 @@ class DocusaurusLlmsCodeGenerator {
       snippetsBySection.forEach((sectionSnippets, sectionName) => {
         lines.push(`## ${sectionName}`);
         if (this.includeSectionAnchors) {
-          const anchor = this.slugify(sectionName, seenSlugs);
+          const custom = page.sectionAnchors && page.sectionAnchors[sectionName];
+          const anchor = custom || this.slugify(sectionName, seenSlugs);
           lines.push(`Source: ${BASE_URL}/${page.docId}#${anchor}`);
         }
         lines.push('');

From c96f73736541134936b8a64dc5f2defc0372e305 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 17:45:27 +0000
Subject: [PATCH 37/43] Add anchors tag to generation script in package.json

---
 docusaurus/package.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docusaurus/package.json b/docusaurus/package.json
index 9ac09cd2eb..0a78ea09bc 100644
--- a/docusaurus/package.json
+++ b/docusaurus/package.json
@@ -15,8 +15,8 @@
     "release-notes": "bash ./scripts/release-notes-script.sh",
     "redirections-analysis": "node ./scripts/redirection-analysis/redirect-analyzer.js",
     "generate-llms": "node scripts/generate-llms.js",
-    "dev:with-llms": "yarn generate-llms && docusaurus start --port 8080 --no-open",
-    "build:with-llms": "yarn generate-llms && docusaurus build",
+    "dev:with-llms": "yarn generate-llms && node scripts/generate-llms-code.js --anchors --output static/llms-code.txt && docusaurus start --port 8080 --no-open",
+    "build:with-llms": "yarn generate-llms && node scripts/generate-llms-code.js --anchors --output static/llms-code.txt && docusaurus build",
     "meilisearch:update-order": "node -r dotenv/config scripts/meilisearch/add-category-order.js"
   },
   "dependencies": {

From 0a5d88cfac352931da117369a128cdfcb45f024c Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 17:45:50 +0000
Subject: [PATCH 38/43] Improve SQL block language inference

---
 docusaurus/scripts/generate-llms-code.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 4cd6132efb..976b2a5132 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -290,7 +290,8 @@ class DocusaurusLlmsCodeGenerator {
     const first = head[0] || '';
     if (/^#!\/.+\b(bash|sh|env\s+bash|env\s+sh)\b/.test(first)) return 'bash';
     if (/^FROM\s+\S+/i.test(first) || head.some((l) => /^(RUN|CMD|ENTRYPOINT|COPY|ADD|WORKDIR|ENV|EXPOSE|USER)\b/i.test(l))) return 'dockerfile';
-    if (head.some((l) => /^(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|WITH)\b/i.test(l))) return 'sql';
+    // SQL: require clear SQL shape; avoid JS objects like `delete:` keys
+    if (head.some((l) => /(^select\b.+\bfrom\b)|(^insert\b\s+into\b)|(^update\b\s+\w+\b)|(^delete\b\s+from\b)|(^create\b\s+(table|index|view)\b)|(^alter\b\s+table\b)|(^drop\b\s+(table|index|view)\b)|(^with\b\s+\w+\s+as\b)/i.test(l))) return 'sql';
     if (/^(query|mutation|subscription|fragment|schema)\b/.test(first)) return 'graphql';
     // JS/TS module cues before YAML/JSON
     if (/(?:^|\b)(module\.exports|require\(["']|exports?\.|console\.log\()/.test(code)) return extLower.startsWith('ts') ? 'ts' : 'js';

From 9e7fe9a3554931595ad80dfce54b0142045d7325 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 17:56:09 +0000
Subject: [PATCH 39/43] Append empty strings to ensure we don't miss language
 blocks

---
 docusaurus/scripts/generate-llms-code.js | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 976b2a5132..811bc7f025 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -601,6 +601,9 @@ class DocusaurusLlmsCodeGenerator {
               lines.push(`File: ${resolvedFile}`);
             }
 
+            // Visual separation before the code fence to avoid accidental inline rendering
+            lines.push('');
+
             // Proper fenced code block without spurious leading newlines
             const fence = chosenLang ? `\`\`\`${chosenLang}` : '```';
             lines.push(fence);

From a8d97ffeba8e45e19cafefb80920b3abf0578a40 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 18:24:55 +0000
Subject: [PATCH 40/43] Better handle Docusaurus tabs detection

---
 docusaurus/scripts/generate-llms-code.js | 81 +++++++++++++++++++++++-
 1 file changed, 78 insertions(+), 3 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 811bc7f025..1394e92248 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -419,6 +419,13 @@ class DocusaurusLlmsCodeGenerator {
     const contextBuffer = [];
     const snippets = [];
     const sectionAnchors = {};
+    // Track MDX Tabs/TabItem context to group language variants
+    let inTabs = false;
+    let tabsCounter = 0;
+    let currentTabsGroupId = null; // from <Tabs groupId="...">
+    let currentTabLabel = null; // from <TabItem label="...">
+    let currentTabValue = null; // from <TabItem value="...">
+    let currentVariantGroupId = null; // computed group key for variants
 
     let inCode = false;
     let codeLanguage = '';
@@ -452,6 +459,9 @@ class DocusaurusLlmsCodeGenerator {
             fallbackUsed,
             code: null,
             filePath: this.normalizeTitlePath(options?.title) || null,
+            variantGroupId: currentVariantGroupId,
+            tabLabel: currentTabLabel,
+            tabValue: currentTabValue,
             context: [...contextBuffer],
           });
         } else {
@@ -481,6 +491,48 @@ class DocusaurusLlmsCodeGenerator {
         return;
       }
 
+      // Detect MDX Tabs and TabItem wrappers to group variants
+      // <Tabs groupId="..."> start
+      const tabsOpen = trimmed.match(/^<Tabs\b([^>]*)>/);
+      if (tabsOpen) {
+        inTabs = true;
+        tabsCounter += 1;
+        const attrs = tabsOpen[1] || '';
+        const gidMatch = attrs.match(/groupId\s*=\s*(?:"([^"]+)"|'([^']+)')/);
+        const gid = gidMatch ? (gidMatch[1] || gidMatch[2]) : 'default';
+        currentTabsGroupId = gid;
+        currentVariantGroupId = `${docId}::${this.currentSection(sections, title)}::tabs${tabsCounter}:${gid}`;
+        return;
+      }
+      // </Tabs> end
+      if (/^<\/Tabs>\s*$/.test(trimmed)) {
+        inTabs = false;
+        currentTabsGroupId = null;
+        currentVariantGroupId = null;
+        return;
+      }
+      // <TabItem ...> start
+      const tabItemOpen = trimmed.match(/^<TabItem\b([^>]*)>/);
+      if (tabItemOpen) {
+        const attrs = tabItemOpen[1] || '';
+        const labelMatch = attrs.match(/label\s*=\s*(?:"([^"]+)"|'([^']+)')/);
+        const valueMatch = attrs.match(/value\s*=\s*(?:"([^"]+)"|'([^']+)')/);
+        currentTabLabel = labelMatch ? (labelMatch[1] || labelMatch[2]) : null;
+        currentTabValue = valueMatch ? (valueMatch[1] || valueMatch[2]) : null;
+        // Ensure we have a variant group during TabItem even if <Tabs> attrs missing
+        if (!currentVariantGroupId) {
+          tabsCounter += 1;
+          currentVariantGroupId = `${docId}::${this.currentSection(sections, title)}::tabs${tabsCounter}:${currentTabsGroupId || 'default'}`;
+        }
+        return;
+      }
+      // </TabItem> end
+      if (/^<\/TabItem>\s*$/.test(trimmed)) {
+        currentTabLabel = null;
+        currentTabValue = null;
+        return;
+      }
+
       const headingMatch = trimmed.match(HEADING_REGEX);
       if (headingMatch) {
         const level = headingMatch[1].length;
@@ -498,6 +550,12 @@ class DocusaurusLlmsCodeGenerator {
         if (customAnchor) {
           sectionAnchors[headingText] = customAnchor;
         }
+        // Reset any ongoing Tabs grouping when changing section
+        inTabs = false;
+        currentTabsGroupId = null;
+        currentVariantGroupId = null;
+        currentTabLabel = null;
+        currentTabValue = null;
         contextBuffer.push('\n');
         return;
       }
@@ -625,10 +683,26 @@ class DocusaurusLlmsCodeGenerator {
   }
 
   groupVariantSnippets(snippets) {
-    const groups = [];
+    // First, group by explicit variantGroupId when present (MDX Tabs),
+    // otherwise fall back to old behavior of grouping consecutive snippets
+    const explicitGroups = new Map();
+    const sequentialGroups = [];
     let currentGroup = [];
 
     snippets.forEach((snippet) => {
+      if (snippet.variantGroupId) {
+        if (!explicitGroups.has(snippet.variantGroupId)) {
+          explicitGroups.set(snippet.variantGroupId, []);
+        }
+        explicitGroups.get(snippet.variantGroupId).push(snippet);
+        // Flush any ongoing sequential group before switching context
+        if (currentGroup.length > 0) {
+          sequentialGroups.push(currentGroup);
+          currentGroup = [];
+        }
+        return;
+      }
+
       if (currentGroup.length === 0) {
         currentGroup.push(snippet);
         return;
@@ -641,15 +715,16 @@ class DocusaurusLlmsCodeGenerator {
       if (sameDescription && sameFile) {
         currentGroup.push(snippet);
       } else {
-        groups.push(currentGroup);
+        sequentialGroups.push(currentGroup);
         currentGroup = [snippet];
       }
     });
 
     if (currentGroup.length > 0) {
-      groups.push(currentGroup);
+      sequentialGroups.push(currentGroup);
     }
 
+    const groups = [...explicitGroups.values(), ...sequentialGroups];
     return groups;
   }
 

From 0de4925df9e1c902ea362a10e9bd2f2600e246c6 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 18:39:17 +0000
Subject: [PATCH 41/43] Add additional scripts to handle file existence and
 project root

---
 docusaurus/scripts/generate-llms-code.js | 41 ++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/docusaurus/scripts/generate-llms-code.js b/docusaurus/scripts/generate-llms-code.js
index 1394e92248..98371706c4 100644
--- a/docusaurus/scripts/generate-llms-code.js
+++ b/docusaurus/scripts/generate-llms-code.js
@@ -89,6 +89,8 @@ const parseArgs = () => {
   const docs = [];
   let output = DEFAULT_OUTPUT;
   let anchors = false;
+  let checkFiles = false;
+  let projectRoot = process.cwd();
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -110,6 +112,14 @@ const parseArgs = () => {
     } else if (arg === '--help' || arg === '-h') {
       console.log('Usage: node generate-llms-code.js [--docs docA,docB] [--output path/to/file]');
       process.exit(0);
+    } else if (arg === '--check-files') {
+      checkFiles = true;
+    } else if (arg === '--project-root') {
+      const value = args[i + 1];
+      i += 1;
+      if (value) {
+        projectRoot = value;
+      }
     } else {
       docs.push(arg);
     }
@@ -119,6 +129,8 @@ const parseArgs = () => {
     docs: docs.length > 0 ? docs : DEFAULT_DOCS,
     output,
     anchors,
+    checkFiles,
+    projectRoot,
   };
 };
 
@@ -129,6 +141,8 @@ class DocusaurusLlmsCodeGenerator {
     this.outputPath = config.outputPath || DEFAULT_OUTPUT;
     this.docIds = config.docIds || DEFAULT_DOCS;
     this.includeSectionAnchors = Boolean(config.includeSectionAnchors);
+    this.includeFileChecks = Boolean(config.includeFileChecks);
+    this.projectRoot = config.projectRoot || process.cwd();
   }
 
   normalizeTitlePath(value) {
@@ -368,6 +382,23 @@ class DocusaurusLlmsCodeGenerator {
     return out;
   }
 
+  resolveAbsolutePathForCheck(relPath = '') {
+    if (!relPath) return null;
+    const clean = relPath.replace(/^\/+/, '');
+    const candidate = path.join(this.projectRoot, clean);
+    return candidate;
+  }
+
+  fileExists(relPath = '') {
+    try {
+      const abs = this.resolveAbsolutePathForCheck(relPath);
+      if (!abs) return false;
+      return fs.pathExistsSync ? fs.pathExistsSync(abs) : fs.existsSync(abs);
+    } catch (e) {
+      return false;
+    }
+  }
+
   buildFallbackDescription(snippet) {
     const langLabel = snippet.language ? this.formatLanguageName(snippet.language) : 'code';
     const section = snippet.section || 'this section';
@@ -631,7 +662,8 @@ class DocusaurusLlmsCodeGenerator {
 
           const primaryFile = this.normalizeOutputPath(primary.filePath || this.inferFilePathFromContext(primary.context));
           if (primaryFile) {
-            lines.push(`File: ${primaryFile}`);
+            const suffix = this.includeFileChecks && !this.fileExists(primaryFile) ? ' (missing)' : '';
+            lines.push(`File: ${primaryFile}${suffix}`);
           }
 
           if (primary.useCase) {
@@ -656,7 +688,8 @@ class DocusaurusLlmsCodeGenerator {
             lines.push(language);
 
             if (resolvedFile && resolvedFile !== primaryFile) {
-              lines.push(`File: ${resolvedFile}`);
+              const suffix = this.includeFileChecks && !this.fileExists(resolvedFile) ? ' (missing)' : '';
+              lines.push(`File: ${resolvedFile}${suffix}`);
             }
 
             // Visual separation before the code fence to avoid accidental inline rendering
@@ -765,11 +798,13 @@ class DocusaurusLlmsCodeGenerator {
 }
 
 if (require.main === module) {
-  const { docs, output, anchors } = parseArgs();
+  const { docs, output, anchors, checkFiles, projectRoot } = parseArgs();
   const generator = new DocusaurusLlmsCodeGenerator({
     docIds: docs,
     outputPath: output,
     includeSectionAnchors: anchors,
+    includeFileChecks: checkFiles,
+    projectRoot,
   });
 
   generator.generate().catch((error) => {

From b585ea4dce557b0b174f043202e5152179b9b526 Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 22:01:44 +0000
Subject: [PATCH 42/43] Add validator script

---
 docusaurus/package.json                  |   1 +
 docusaurus/scripts/validate-llms-code.js | 436 +++++++++++++++++++++++
 2 files changed, 437 insertions(+)
 create mode 100644 docusaurus/scripts/validate-llms-code.js

diff --git a/docusaurus/package.json b/docusaurus/package.json
index 0a78ea09bc..c781657d0b 100644
--- a/docusaurus/package.json
+++ b/docusaurus/package.json
@@ -17,6 +17,7 @@
     "generate-llms": "node scripts/generate-llms.js",
     "dev:with-llms": "yarn generate-llms && node scripts/generate-llms-code.js --anchors --output static/llms-code.txt && docusaurus start --port 8080 --no-open",
     "build:with-llms": "yarn generate-llms && node scripts/generate-llms-code.js --anchors --output static/llms-code.txt && docusaurus build",
+    "validate:llms-code": "node scripts/validate-llms-code.js --path static/llms-code.txt --strict --check-files --verify-anchors --project-root ..",
     "meilisearch:update-order": "node -r dotenv/config scripts/meilisearch/add-category-order.js"
   },
   "dependencies": {
diff --git a/docusaurus/scripts/validate-llms-code.js b/docusaurus/scripts/validate-llms-code.js
new file mode 100644
index 0000000000..ba54716891
--- /dev/null
+++ b/docusaurus/scripts/validate-llms-code.js
@@ -0,0 +1,436 @@
+#!/usr/bin/env node
+
+/**
+ * llms-code validator
+ *
+ * Validates the generated static/llms-code.txt structure and metadata:
+ * - Section structure and required fields
+ * - Balanced code fences and language tags
+ * - Recognized languages
+ * - File path presence and existence (when --check-files)
+ * - Source URL format and optional anchor syntax
+ * - Optional anchor verification against source MD/MDX (when --verify-anchors)
+ *
+ * Exit code:
+ * - 0 when clean (no errors; warnings ignored unless --strict)
+ * - 1 when errors found (or warnings found with --strict)
+ */
+
+let fs = null;
+try {
+  fs = require('fs-extra');
+} catch {
+  fs = require('fs');
+  fs.ensureDir = async (dir) => fs.promises.mkdir(dir, { recursive: true });
+  fs.pathExistsSync = (p) => fs.existsSync(p);
+  fs.writeFile = fs.promises.writeFile.bind(fs.promises);
+  fs.readFile = fs.promises.readFile.bind(fs.promises);
+}
+const path = require('path');
+const { URL } = require('url');
+
+const DEFAULT_INPUT = path.join('static', 'llms-code.txt');
+const DEFAULT_PROJECT_ROOT = path.resolve('..');
+const BASE_HOSTS = new Set([
+  'docs.strapi.io',
+  'localhost',
+  '127.0.0.1',
+]);
+
+const RECOGNIZED_LANGS = new Set([
+  'javascript', 'typescript', 'tsx', 'jsx',
+  'json', 'yaml', 'yml',
+  'bash', 'sh', 'zsh', 'fish',
+  'powershell', 'ps1',
+  'sql', 'dockerfile',
+  'toml', 'ini', 'env', 'diff',
+]);
+
+const DISPLAY_LANG_MAP = new Map([
+  ['javascript', 'javascript'],
+  ['typescript', 'typescript'],
+  ['tsx', 'tsx'],
+  ['jsx', 'jsx'],
+  ['json', 'json'],
+  ['yaml', 'yaml'],
+  ['yml', 'yml'],
+  ['bash', 'bash'],
+  ['shell', 'bash'],
+  ['sh', 'sh'],
+  ['zsh', 'zsh'],
+  ['fish', 'fish'],
+  ['powershell', 'powershell'],
+  ['ps1', 'ps1'],
+  ['sql', 'sql'],
+  ['dockerfile', 'dockerfile'],
+  ['toml', 'toml'],
+  ['ini', 'ini'],
+  ['env', 'env'],
+  ['diff', 'diff'],
+]);
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let inputPath = DEFAULT_INPUT;
+  let strict = false;
+  let report = 'text';
+  let checkFiles = false;
+  let verifyAnchors = false;
+  let projectRoot = DEFAULT_PROJECT_ROOT;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    const next = args[i + 1];
+
+    if (arg === '--path') {
+      inputPath = next || inputPath;
+      i += 1;
+    } else if (arg === '--strict') {
+      strict = true;
+    } else if (arg === '--report') {
+      report = (next || report).toLowerCase();
+      i += 1;
+    } else if (arg === '--check-files') {
+      checkFiles = true;
+    } else if (arg === '--verify-anchors') {
+      verifyAnchors = true;
+    } else if (arg === '--project-root') {
+      projectRoot = next ? path.resolve(next) : projectRoot;
+      i += 1;
+    } else if (arg === '--help' || arg === '-h') {
+      console.log(`Usage:\n  node scripts/validate-llms-code.js [--path static/llms-code.txt] [--strict]\n                                     [--check-files] [--verify-anchors]\n                                     [--project-root ..] [--report json|text]`);
+      process.exit(0);
+    }
+  }
+
+  return { inputPath, strict, report, checkFiles, verifyAnchors, projectRoot };
+}
+
+function slugifyHeading(text) {
+  if (!text) return '';
+  const cleaned = String(text)
+    .replace(/\{#([A-Za-z0-9\-_]+)\}\s*$/, '')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/[.,\/#!$%^&*;:{}=_`~()"'?<>\[\]|+]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+
+  return cleaned
+    .replace(/[^a-z0-9\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-');
+}
+
+function extractHeadingId(line) {
+  const m = line.match(/^\s*#{1,6}\s+(.+?)\s*(\{#([A-Za-z0-9\-_]+)\})?\s*$/);
+  if (!m) return null;
+  const [, title, , custom] = m;
+  if (custom) return custom;
+  return slugifyHeading(title);
+}
+
+function collectAnchorsFromDoc(content) {
+  const lines = content.split(/\r?\n/);
+  const anchors = new Set();
+  for (const ln of lines) {
+    const id = extractHeadingId(ln);
+    if (id) anchors.add(id);
+  }
+  return anchors;
+}
+
+function findDocFileForUrl(sourceUrl, projectRoot) {
+  let url;
+  try {
+    url = new URL(sourceUrl);
+  } catch {
+    return null;
+  }
+  const pathname = url.pathname.replace(/\/+$/, '');
+  if (!pathname || pathname === '/') return null;
+
+  const candidatesRoots = [
+    path.join(projectRoot, 'docusaurus', 'docs'),
+    path.join(projectRoot, 'docs'),
+    path.join(projectRoot, 'website', 'docs'),
+    path.join(projectRoot, 'content', 'docs'),
+  ];
+
+  const suffixes = ['', '.mdx', '.md', '/index.mdx', '/index.md'];
+
+  for (const root of candidatesRoots) {
+    for (const suf of suffixes) {
+      const attempt = path.join(root, pathname + suf);
+      if (fs.existsSync(attempt)) return attempt;
+    }
+  }
+  return null;
+}
+
+function isAbsoluteHttpUrl(u) {
+  try {
+    const parsed = new URL(u);
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+function normalizeDisplayLang(name) {
+  if (!name) return null;
+  const key = String(name).trim().toLowerCase();
+  return DISPLAY_LANG_MAP.get(key) || null;
+}
+
+function fileExistsMaybe(projectRoot, filePath) {
+  if (!filePath || filePath === 'N/A') return false;
+  const cleaned = filePath.replace(/\s+\(file not found\)\s*$/, '');
+  const resolved = path.isAbsolute(cleaned)
+    ? cleaned
+    : path.resolve(projectRoot, cleaned);
+  return fs.existsSync(resolved);
+}
+
+function splitSectionsByHeading(inputText) {
+  const lines = inputText.split(/\r?\n/);
+  const sections = [];
+  let current = null;
+
+  const flush = () => {
+    if (current) {
+      current.endLine = current.startLine + current.lines.length - 1;
+      sections.push(current);
+      current = null;
+    }
+  };
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (line.startsWith('## ')) {
+      flush();
+      current = {
+        titleLine: line,
+        title: line.slice(3).trim(),
+        startLine: i + 1,
+        lines: [line],
+      };
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+
+function validateSection(section, opts) {
+  const { checkFiles, verifyAnchors, projectRoot } = opts;
+
+  const diagnostics = [];
+  const lines = section.lines;
+  const title = section.title;
+
+  const push = (severity, message, relLineIdx = 0) => {
+    diagnostics.push({
+      severity,
+      message,
+      section: title,
+      line: section.startLine + relLineIdx,
+    });
+  };
+
+  if (!lines[0] || !lines[0].startsWith('## ')) {
+    push('error', 'Section does not start with "## " heading', 0);
+    return diagnostics;
+  }
+
+  let idx = 1;
+  const findLineIndex = (re, start) => {
+    for (let i = start; i < lines.length; i += 1) {
+      if (re.test(lines[i])) return i;
+    }
+    return -1;
+  };
+
+  while (idx < lines.length && lines[idx].trim() === '') idx += 1;
+
+  const descIdx = lines[idx] && /^Description:\s*/i.test(lines[idx]) ? idx : -1;
+  if (descIdx === -1) {
+    push('error', 'Missing "Description:" line', idx);
+    return diagnostics;
+  }
+  const desc = lines[descIdx].replace(/^Description:\s*/i, '').trim();
+  if (!desc) {
+    push('error', '"Description:" is empty', descIdx);
+  } else if (/^(tbd|todo|n\/a|1|none)$/i.test(desc)) {
+    push('warning', 'Description appears placeholder-like', descIdx);
+  }
+  idx = descIdx + 1;
+
+  while (idx < lines.length && lines[idx].trim() === '') idx += 1;
+
+  if (!lines[idx] || !/^\(Source:\s*.+\)$/.test(lines[idx])) {
+    push('error', 'Missing or malformed "(Source: ...)" line', idx);
+    return diagnostics;
+  }
+  const sourceLine = lines[idx];
+  const sourceUrl = sourceLine.replace(/^\(Source:\s*/i, '').replace(/\)\s*$/, '').trim();
+  if (!isAbsoluteHttpUrl(sourceUrl)) {
+    push('error', 'Source is not an absolute URL', idx);
+  } else {
+    try {
+      const u = new URL(sourceUrl);
+      if (!BASE_HOSTS.has(u.hostname)) {
+        push('warning', `Source host not in known set: ${u.hostname}`, idx);
+      }
+    } catch {
+      push('error', 'Source URL failed to parse', idx);
+    }
+  }
+
+  let sourceAnchor = null;
+  try {
+    const u = new URL(sourceUrl);
+    sourceAnchor = u.hash ? u.hash.replace(/^#/, '') : null;
+  } catch {}
+  idx += 1;
+
+  let sawAnyVariant = false;
+  while (idx < lines.length) {
+    if (lines[idx].startsWith('## ')) break;
+    while (idx < lines.length && lines[idx].trim() === '') idx += 1;
+    if (idx >= lines.length || lines[idx].startsWith('## ')) break;
+
+    if (lines[idx].trim() === '---') {
+      idx += 1;
+      while (idx < lines.length && lines[idx].trim() === '') idx += 1;
+    }
+
+    if (!lines[idx] || !/^Language:\s*/i.test(lines[idx])) {
+      if (!sawAnyVariant) push('error', 'Missing "Language:" before code block', idx);
+      break;
+    }
+    const displayLangRaw = lines[idx].replace(/^Language:\s*/i, '').trim();
+    const canonicalLang = normalizeDisplayLang(displayLangRaw);
+    if (!canonicalLang) {
+      push('error', `Unrecognized language: ${displayLangRaw}`, idx);
+    } else if (!RECOGNIZED_LANGS.has(canonicalLang)) {
+      push('warning', `Language recognized but not in allowlist: ${canonicalLang}`, idx);
+    }
+    idx += 1;
+
+    if (!lines[idx] || !/^File path:\s*/i.test(lines[idx])) {
+      push('error', 'Missing "File path:" line', idx);
+      break;
+    }
+    const filePathValue = lines[idx].replace(/^File path:\s*/i, '').trim();
+    if (!filePathValue) {
+      push('error', '"File path:" is empty', idx);
+    } else if (checkFiles) {
+      const exists = fileExistsMaybe(projectRoot, filePathValue);
+      if (!exists) {
+        push('error', `Referenced file does not exist: ${filePathValue}`, idx);
+      }
+    }
+    idx += 1;
+
+    while (idx < lines.length && lines[idx].trim() === '') idx += 1;
+
+    const fenceStart = lines[idx] || '';
+    const fenceStartMatch = fenceStart.match(/^```([a-z0-9]+)\s*$/i);
+    if (!fenceStartMatch) {
+      push('error', 'Missing opening code fence ```<lang>', idx);
+      break;
+    }
+    const fenceLang = fenceStartMatch[1].toLowerCase();
+    if (canonicalLang && fenceLang !== canonicalLang) {
+      push('error', `Fence language "${fenceLang}" does not match declared Language "${displayLangRaw}"`, idx);
+    }
+    idx += 1;
+
+    let closed = false;
+    while (idx < lines.length) {
+      if (/^```/.test(lines[idx])) {
+        closed = true;
+        idx += 1;
+        break;
+      }
+      idx += 1;
+    }
+    if (!closed) {
+      push('error', 'Unclosed code fence', idx);
+      break;
+    }
+
+    sawAnyVariant = true;
+  }
+
+  if (!sawAnyVariant) {
+    push('error', 'No code example variants found in section', 0);
+  }
+
+  if (verifyAnchors && sourceAnchor) {
+    const docFile = findDocFileForUrl(sourceUrl, projectRoot);
+    if (!docFile) {
+      push('warning', `Could not locate local doc file for source to verify anchor: ${sourceUrl}`, 0);
+    } else {
+      try {
+        const raw = fs.readFileSync(docFile, 'utf8');
+        const anchors = collectAnchorsFromDoc(raw);
+        if (!anchors.has(sourceAnchor)) {
+          push('error', `Anchor "#${sourceAnchor}" not found in ${path.relative(projectRoot, docFile)}`, 0);
+        }
+      } catch (e) {
+        push('warning', `Failed reading doc for anchor verification: ${e.message}`, 0);
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+(async function main() {
+  const args = parseArgs();
+  const { inputPath, strict, report, checkFiles, verifyAnchors, projectRoot } = args;
+
+  if (!fs.existsSync(inputPath)) {
+    console.error(`ERROR: Input file not found: ${inputPath}`);
+    process.exit(1);
+  }
+
+  const raw = await fs.readFile(inputPath, 'utf8');
+  const sections = splitSectionsByHeading(raw);
+
+  const diagnostics = [];
+  for (const sec of sections) {
+    const diags = validateSection(sec, { checkFiles, verifyAnchors, projectRoot });
+    diagnostics.push(...diags);
+  }
+
+  const errors = diagnostics.filter(d => d.severity === 'error');
+  const warnings = diagnostics.filter(d => d.severity === 'warning');
+
+  if (report === 'json') {
+    console.log(JSON.stringify({ errors, warnings, count: diagnostics.length }, null, 2));
+  } else {
+    for (const d of diagnostics) {
+      const tag = d.severity.toUpperCase();
+      const loc = d.line ? `:${d.line}` : '';
+      console.log(`[${tag}] ${d.section}${loc} - ${d.message}`);
+    }
+    if (diagnostics.length === 0) {
+      console.log('llms-code validation passed: no issues found.');
+    } else {
+      console.log(`\nSummary: ${errors.length} error(s), ${warnings.length} warning(s)`);
+    }
+  }
+
+  const exitWithError = errors.length > 0 || (strict && warnings.length > 0);
+  process.exit(exitWithError ? 1 : 0);
+})().catch((e) => {
+  console.error('Validator crashed:', e);
+  process.exit(1);
+});
+

From bbb32b82ce9a283f54080702c86ee32f20fef88c Mon Sep 17 00:00:00 2001
From: Pierre Wizla <pwizla+github@gmail.com>
Date: Thu, 6 Nov 2025 22:03:59 +0000
Subject: [PATCH 43/43] Add script to both generate and validate

---
 docusaurus/package.json | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docusaurus/package.json b/docusaurus/package.json
index c781657d0b..a4a6126e4c 100644
--- a/docusaurus/package.json
+++ b/docusaurus/package.json
@@ -15,8 +15,9 @@
     "release-notes": "bash ./scripts/release-notes-script.sh",
     "redirections-analysis": "node ./scripts/redirection-analysis/redirect-analyzer.js",
     "generate-llms": "node scripts/generate-llms.js",
-    "dev:with-llms": "yarn generate-llms && node scripts/generate-llms-code.js --anchors --output static/llms-code.txt && docusaurus start --port 8080 --no-open",
-    "build:with-llms": "yarn generate-llms && node scripts/generate-llms-code.js --anchors --output static/llms-code.txt && docusaurus build",
+    "dev:with-llms": "yarn generate-llms && node scripts/generate-llms-code.js --anchors --output static/llms-code.txt && node scripts/validate-llms-code.js --path static/llms-code.txt --strict --check-files --verify-anchors --project-root .. && docusaurus start --port 8080 --no-open",
+    "build:with-llms": "yarn generate-llms && node scripts/generate-llms-code.js --anchors --output static/llms-code.txt && node scripts/validate-llms-code.js --path static/llms-code.txt --strict --check-files --verify-anchors --project-root .. && docusaurus build",
+    "llms:generate-and-validate": "yarn generate-llms && node scripts/generate-llms-code.js --anchors --output static/llms-code.txt && node scripts/validate-llms-code.js --path static/llms-code.txt --strict --check-files --verify-anchors --project-root ..",
     "validate:llms-code": "node scripts/validate-llms-code.js --path static/llms-code.txt --strict --check-files --verify-anchors --project-root ..",
     "meilisearch:update-order": "node -r dotenv/config scripts/meilisearch/add-category-order.js"
   },