feat(ask-ai): add help in Ask AI widget placeholder

- InfluxDB placeholder recommends specifying product and version
- Fix page-context.js to use products.influxdb_cloud instead of products.cloud
- Add UI tests verifying version-specific naming in Kapa widget script tags

Author: jstirnaman

.github/instructions/layouts.instructions.md

@@ -11,10 +11,11 @@ applyTo: "layouts/**/*.html"
 
 When creating or modifying Hugo layouts and shortcodes:
 
-1. Use Hugo template syntax and functions
-2. Follow existing patterns in `/layouts/shortcodes/`
-3. Test in [content/example.md](../../content/example.md)
-4. Document new shortcodes in [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md)
+1. Use test-driven development using `/cypress/`
+2. Use Hugo template syntax and functions
+3. Follow existing patterns in `/layouts/shortcodes/`
+4. Test in [content/example.md](../../content/example.md)
+5. Document new shortcodes in [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md)
 
 ## Shortcode Pattern
 
@@ -30,9 +31,32 @@ When creating or modifying Hugo layouts and shortcodes:
 
 ## Testing
 
-Add usage examples to `content/example.md` to verify:
+**IMPORTANT:** Use test-driven development with Cypress.
+
+Add shortcode usage examples to `content/example.md` to verify:
+
 - Rendering in browser
 - Hugo build succeeds
 - No console errors
+- JavaScript functionality works as expected (check browser console for errors)
+- Interactive elements behave correctly (click links, buttons, etc.)
+
+### TDD Workflow
+
+1. Add Cypress tests (high-level to start).
+2. Run tests and make sure they fail.
+3. Implement code changes
+4. Run tests and make sure they pass.
+5. Add and refine tests.
+6. Repeat.
+
+### Manual Testing Workflow
+
+1. Make changes to shortcode/layout files
+2. Wait for Hugo to rebuild (check terminal output)
+3. Get the server URL from the log
+4. Open browser DevTools console (F12)
+5. Test the functionality and check for JavaScript errors
+6. Verify the feature works as intended before marking complete
 
 See [DOCS-SHORTCODES.md](../../DOCS-SHORTCODES.md) for complete shortcode documentation.

assets/js/ask-ai-trigger.js

@@ -1,19 +1,117 @@
 import AskAI from './ask-ai.js';
 
+/**
+ * Global state for Ask AI initialization
+ */
+const state = {
+  kapaInitialized: false,
+  linksListenerInitialized: false,
+};
+
+/**
+ * Initialize the Kapa widget
+ */
+function initializeKapa() {
+  if (!state.kapaInitialized) {
+    AskAI();
+    state.kapaInitialized = true;
+
+    // Store in global namespace for debugging
+    window.influxdatadocs = window.influxdatadocs || {};
+    window.influxdatadocs.kapaInitialized = true;
+  }
+}
+
+/**
+ * Show the trigger button by removing inline display: none style
+ * @param {HTMLElement} element - The trigger button element
+ */
 function showTrigger(element) {
-  // Remove the inline display: none style
-  element.removeAttribute('style');
+  if (element) {
+    element.removeAttribute('style');
+  }
 }
 
+/**
+ * Initialize Ask AI trigger button component
+ * @param {Object} options - Component options
+ * @param {HTMLElement} options.component - The trigger button element
+ */
 export default function AskAITrigger({ component }) {
   const kapaContainer = document.querySelector('#kapa-widget-container');
+
   if (!component && !kapaContainer) {
     return;
   }
+
   if (!kapaContainer) {
     // Initialize the chat widget
     AskAI({ onChatLoad: () => showTrigger(component) });
+    state.kapaInitialized = true;
+    window.influxdatadocs = window.influxdatadocs || {};
+    window.influxdatadocs.kapaInitialized = true;
   } else {
     showTrigger(component);
   }
-}
+}
+
+/**
+ * Handle ask-ai-link clicks globally
+ * This ensures ask-ai-link shortcodes work even without the trigger button
+ */
+function handleAskAILinks() {
+  if (state.linksListenerInitialized) {
+    return;
+  }
+
+  state.linksListenerInitialized = true;
+
+  // Store in global namespace for debugging
+  window.influxdatadocs = window.influxdatadocs || {};
+  window.influxdatadocs.askAILinksInitialized = true;
+
+  // Listen for clicks on ask-ai-link elements
+  document.addEventListener(
+    'click',
+    (event) => {
+      const link = event.target.closest('.ask-ai-open');
+      if (!link) return;
+
+      const query = link.getAttribute('data-query');
+
+      // Initialize Kapa if not already done
+      if (!state.kapaInitialized) {
+        initializeKapa();
+
+        // Wait for Kapa to be ready, then open with query
+        if (query && window.Kapa?.open) {
+          // Give Kapa a moment to initialize
+          setTimeout(() => {
+            if (window.Kapa?.open) {
+              window.Kapa.open({
+                mode: 'ai',
+                query: query,
+              });
+            }
+          }, 100);
+        }
+      } else {
+        // Kapa is already initialized - open with query if provided
+        if (query && window.Kapa?.open) {
+          window.Kapa.open({
+            mode: 'ai',
+            query: query,
+          });
+        }
+      }
+    },
+    { passive: true }
+  );
+}
+
+// Initialize ask-ai-link handling when DOM is ready
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', handleAskAILinks);
+} else {
+  handleAskAILinks();
+}

assets/js/ask-ai.ts

@@ -47,6 +47,8 @@ type KapaFunction = (command: string, options?: unknown) => void;
 
 interface ChatAttributes extends Record<string, string | undefined> {
   modalExampleQuestions?: string;
+  modalAskAiInputPlaceholder?: string;
+  modalDisclaimer?: string;
   sourceGroupIdsInclude?: string;
 }
 
@@ -96,6 +98,7 @@ function initializeChat({
 
   const optionalAttributes = {
     modalDisclaimer:
+      chatAttributes.modalDisclaimer ||
       'This AI can access [documentation for InfluxDB, clients, and related tools](https://docs.influxdata.com). Information you submit is used in accordance with our [Privacy Policy](https://www.influxdata.com/legal/privacy-policy/).',
     modalExampleQuestions:
       'Use Python to write data to InfluxDB 3,How do I query using SQL?,How do I use MQTT with Telegraf?',
@@ -175,27 +178,7 @@ function getProductExampleQuestions(): string {
     return '';
   }
 
-  // Only add version hints for InfluxDB database products
-  // Other tools like Explorer, Telegraf, Chronograf, Kapacitor,
-  // Flux don't need version hints
-  const productNamespace = productData?.product?.namespace;
-  const shouldAddVersionHint =
-    productNamespace === 'influxdb' ||
-    productNamespace === 'influxdb3' ||
-    productNamespace === 'enterprise_influxdb';
-
-  if (!shouldAddVersionHint) {
-    return questions.join(',');
-  }
-
-  const productName = productData?.product?.name || 'InfluxDB';
-
-  // Append version hint to each question
-  const questionsWithHint = questions.map((question) => {
-    return `${question} My version: ${productName}`;
-  });
-
-  return questionsWithHint.join(',');
+  return questions.join(',');
 }
 
 function getProductSourceGroupIds(): string {
@@ -205,60 +188,37 @@ function getProductSourceGroupIds(): string {
   return sourceGroupIds || '';
 }
 
-function getVersionContext(): string {
-  // Only add version context for InfluxDB database products
-  const productNamespace = productData?.product?.namespace;
-  const shouldAddVersionContext =
-    productNamespace === 'influxdb' ||
-    productNamespace === 'influxdb3' ||
-    productNamespace === 'enterprise_influxdb';
-
-  if (!shouldAddVersionContext) {
-    return '';
-  }
-
-  const productName = productData?.product?.name || 'InfluxDB';
+function getProductInputPlaceholder(): string {
+  const placeholder = getVersionSpecificConfig('ai_input_placeholder') as
+    | string
+    | undefined;
 
-  return `My version: ${productName}`;
+  // Return product-specific placeholder or default
+  return (
+    placeholder ||
+    'Ask questions about InfluxDB. Specify your product and version ' +
+      'for better results'
+  );
 }
 
-function setupVersionPrefill(): void {
-  const versionContext = getVersionContext();
-  if (!versionContext) {
-    return;
-  }
-
-  // Wait for Kapa to be available
-  const checkKapa = (): void => {
-    if (!window.Kapa || typeof window.Kapa !== 'function') {
-      setTimeout(checkKapa, 100);
-      return;
-    }
+function getProductDisclaimer(): string {
+  // Build version-specific note if version is available
+  const versionNote =
+    version && version !== 'n/a' && productData?.product?.name
+      ? `**Viewing documentation for ${productData.product.name}**\n\n`
+      : '';
 
-    // Find the Ask AI button and add click handler to prefill version
-    const askAIButton = document.querySelector('.ask-ai-open');
-    if (askAIButton) {
-      askAIButton.addEventListener(
-        'click',
-        (e) => {
-          e.preventDefault();
-          e.stopPropagation();
-          window.Kapa('open', { query: versionContext });
-        },
-        true
-      ); // Use capture phase to run before Kapa's handler
-    }
+  // Check for product-specific custom disclaimer note
+  const customNote = getVersionSpecificConfig('ai_disclaimer_note') as
+    | string
+    | undefined;
+  const noteContent = customNote ? `${customNote}\n\n` : '';
 
-    // Listen for conversation reset to re-fill version context
-    window.Kapa('onAskAIConversationReset', () => {
-      // Small delay to ensure the reset is complete
-      setTimeout(() => {
-        window.Kapa('open', { query: versionContext });
-      }, 100);
-    });
-  };
+  // Base disclaimer with privacy policy link
+  const baseDisclaimer =
+    'This AI can access [documentation for InfluxDB, clients, and related tools](https://docs.influxdata.com). Information you submit is used in accordance with our [Privacy Policy](https://www.influxdata.com/legal/privacy-policy/).';
 
-  checkKapa();
+  return `${versionNote}${noteContent}${baseDisclaimer}`;
 }
 
 /**
@@ -277,16 +237,18 @@ export default function AskAI({
   ...chatParams
 }: AskAIParams): void {
   const modalExampleQuestions = getProductExampleQuestions();
+  const modalAskAiInputPlaceholder = getProductInputPlaceholder();
+  const modalDisclaimer = getProductDisclaimer();
   const sourceGroupIds = getProductSourceGroupIds();
   const chatAttributes: ChatAttributes = {
     ...(modalExampleQuestions && { modalExampleQuestions }),
+    ...(modalAskAiInputPlaceholder && { modalAskAiInputPlaceholder }),
+    ...(modalDisclaimer && { modalDisclaimer }),
     ...(sourceGroupIds && { sourceGroupIdsInclude: sourceGroupIds }),
     ...(chatParams as Record<string, string>),
   };
 
   const wrappedOnChatLoad = (): void => {
-    // Setup version pre-fill after widget loads
-    setupVersionPrefill();
     // Call original onChatLoad if provided
     if (onChatLoad) {
       onChatLoad();

assets/js/page-context.js

@@ -9,7 +9,7 @@ function getCurrentProductData() {
   const mappings = [
     {
       pattern: /\/influxdb\/cloud\//,
-      product: products.cloud,
+      product: products.influxdb_cloud,
       urls: influxdbUrls.influxdb_cloud,
     },
     {

content/enterprise_influxdb/v1/administration/identify-version.md

@@ -0,0 +1,21 @@
+---
+title: Identify InfluxDB Enterprise v1 version
+description: Learn how to identify your InfluxDB Enterprise v1 version using command-line tools, HTTP endpoints, and other methods.
+menu:
+  enterprise_influxdb_v1:
+    name: Identify version
+    parent: Administration
+weight: 10
+source: /shared/identify-version.md
+related:
+  - /enterprise_influxdb/v1/install-and-deploy/
+alt_links:
+  v1: /influxdb/v1/administration/identify-version/
+  v2: /influxdb/v2/admin/identify-version/
+  cloud: /influxdb/cloud/admin/identify-version/
+  cloud-serverless: /influxdb3/cloud-serverless/admin/identify-version/
+  cloud-dedicated: /influxdb3/cloud-dedicated/admin/identify-version/
+  clustered: /influxdb3/clustered/admin/identify-version/
+  core: /influxdb3/core/admin/identify-version/
+  enterprise: /influxdb3/enterprise/admin/identify-version/
+---