DOC-2450: scope Ask AI to the reader's docs version

package.json

@@ -81,7 +81,8 @@
     "test:negative-cache": "node tests/negative-cache/test-runner.js",
     "test:head-meta": "node --test tests/head-meta/*.test.js",
     "test:property-tooltips": "node --test tests/property-tooltips/*.test.js",
-    "test:all": "npm run test:playground && npm run test:interactive && npm run test:negative-cache && npm run test:head-meta && npm run test:property-tooltips",
+    "test:kapa-source-groups": "node --test tests/kapa-source-groups/*.test.js",
+    "test:all": "npm run test:playground && npm run test:interactive && npm run test:negative-cache && npm run test:head-meta && npm run test:property-tooltips && npm run test:kapa-source-groups",
     "build:wasm": "cd blobl-editor/wasm && GOOS=js GOARCH=wasm go build -o ../../src/static/blobl.wasm .",
     "copy:wasm-exec": "cp \"$(go env GOROOT)/lib/wasm/wasm_exec.js\" src/js/vendor/",
     "serve:playground": "npx serve ."

src/helpers/get-kapa-source-groups.js

@@ -0,0 +1,155 @@
+'use strict'
+
+/**
+ * Resolves the Kapa source group that scopes Ask AI retrieval to the docs
+ * version the reader is actually on.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Kapa indexes one separately crawled source per published docs version. With no
+ * scoping, a question is answered from any of them. Measured against the live
+ * retrieval API for "hardware requirements for enterprise redpanda self-hosted",
+ * the exact question in DOC-2450: 11 results spread across 24.2, 24.3, 25.1,
+ * 25.2, 25.3 and current, with only ONE from current. Scoped to the current
+ * group, 14 of 14 came from current.
+ *
+ * HOW THE SEGMENT IS DERIVED
+ * --------------------------
+ * From `page.url`, not from page.version. The two disagree for the latest
+ * release: `latest_version_segment: 'current'` publishes 26.2 at
+ * /streaming/current/ while page.version reads 26.2. The Kapa mapping is keyed on
+ * the URL segment because that is what Kapa's own source_url values use, so
+ * reading the URL avoids having to know which version is currently latest.
+ *
+ * WHAT IT RETURNS
+ * ---------------
+ * An array, because that is the shape both Kapa providers want
+ * (sourceGroupIdsInclude on AgentProvider, sourceGroupIDsInclude on
+ * KapaProvider). An EMPTY array means "send no filter", which is the pre-DOC-2450
+ * behaviour: Kapa searches everything. That is the deliberate degradation for any
+ * case where scoping cannot be resolved, because a wrong group is worse than no
+ * group -- scoping to a group that does not hold the reader's version returns
+ * only Kapa's global sources, so the reader gets no version-specific content at
+ * all and no error either.
+ *
+ * Unversioned pages (Cloud, Connect, Agentic Data Plane, labs, home, search, the
+ * 404 page) resolve to the mapping's default_segment rather than to nothing.
+ * Sending no filter there is what produced DOC-2450 in the first place: the
+ * reporter was on a page with no version of its own.
+ *
+ * Note that scoping to a version group does NOT hide Cloud, Connect or Agentic
+ * Data Plane content. Those sources are deliberately left unassigned in Kapa, so
+ * they are "global" and come through alongside whichever group is selected.
+ * Verified live: scoped to the 25.2 group, an Agentic Data Plane question
+ * returned 10 of 10 results from /agentic-data-plane/.
+ *
+ * Usage in templates:
+ *   window.KAPA_SOURCE_GROUP_IDS = [
+ *     {{#each (get-kapa-source-groups)}}"{{{this}}}"{{#unless @last}},{{/unless}}{{/each}}
+ *   ];
+ *
+ * @param {object} options - Handlebars options with data.root.page and data.root.site
+ * @returns {string[]} Zero or one Kapa source group id
+ */
+module.exports = function (options) {
+  const root = (options && options.data && options.data.root) || {}
+  const { page, site } = root
+
+  const mapping = readMapping(page, site)
+  if (!mapping || !mapping.segments) return []
+
+  const segment = versionSegmentFromUrl(page && page.url, mapping.segments)
+
+  // A versioned page whose segment has no group is the case the drift check
+  // exists to catch: a version was published and nobody created the Kapa source
+  // and group. Fall back to the default rather than sending nothing, so the
+  // reader gets current-version answers instead of every version at once.
+  const entry = (segment && mapping.segments[segment]) || mapping.segments[mapping.default_segment]
+  if (!entry || !entry.group_id) return []
+
+  return [entry.group_id]
+}
+
+/**
+ * The mapping is generated in docs-extensions-and-macros
+ * (docs-data/kapa-source-groups.json) and surfaced to the UI as an AsciiDoc
+ * attribute, because docs-ui does not depend on that package and must not carry
+ * a second copy that can drift.
+ *
+ * Read from the component version first and the site second, matching how
+ * add-global-attributes.js merges shared attributes onto every component
+ * version. Absent in a bare docs-ui preview, which is why every failure path
+ * degrades to "no filter" rather than throwing.
+ */
+function readMapping (page, site) {
+  const candidates = [
+    page && page.componentVersion && page.componentVersion.asciidoc && page.componentVersion.asciidoc.attributes,
+    page && page.component && page.component.asciidoc && page.component.asciidoc.attributes,
+    page && page.attributes,
+    site && site.asciidoc && site.asciidoc.attributes,
+    // site.keys last but never redundant: it is the ONLY channel that reaches a
+    // page with no component. The 404 page renders the Ask AI panel yet has no
+    // page.component or page.componentVersion, so without this it would search
+    // every docs version -- and a 404 is a plausible place to ask the AI where
+    // something went.
+    site && site.keys,
+  ]
+
+  for (const attrs of candidates) {
+    const raw = attrs && (attrs['kapa-source-groups'] || attrs.kapa_source_groups)
+    if (!raw) continue
+    if (typeof raw === 'object') return raw
+    try {
+      return JSON.parse(raw)
+    } catch (err) {
+      // A malformed attribute must not break the page. Losing version scoping is
+      // a degraded answer; a thrown helper is a broken build.
+      return null
+    }
+  }
+  return null
+}
+
+/**
+ * Pull the version segment out of a page URL.
+ *
+ * Recognises a segment by looking it up in the mapping, rather than by matching
+ * a hardcoded /streaming/ prefix, and checks the first TWO path positions:
+ *
+ *   /streaming/25.2/manage/monitoring/  -> 25.2   (today's layout)
+ *   /24.3/manage/monitoring/            -> 24.3   (the pre-rename layout)
+ *
+ * Both are checked because the layout has already changed once: the docs
+ * component was renamed from ROOT to streaming, which moved every versioned
+ * page from /<version>/ to /streaming/<version>/. A prefix-matching version of
+ * this function silently returned null for the old layout, so an all-components
+ * build over pre-rename branches produced 451 pages of 24.3 content advertising
+ * the current group. Nothing failed; the answers were just wrong.
+ *
+ * Driven off the mapping's own keys, so this stays correct if a second
+ * component is ever versioned, and cannot mistake an ordinary path word for a
+ * version: /connect/current/ only resolves if 'current' is a real segment, and
+ * /cloud-data-platform/manage/ never resolves because 'manage' is not.
+ *
+ * @param {string} url - e.g. /streaming/25.2/get-started/intro-to-events/
+ * @param {object} segments - The mapping's segments, keyed by URL segment
+ * @returns {string|null} e.g. '25.2', 'current', or null when not versioned
+ */
+function versionSegmentFromUrl (url, segments) {
+  if (typeof url !== 'string' || !segments) return null
+  // Leading empty string from the leading slash, so [1] and [2] are the first
+  // two path positions.
+  const parts = url.split('/')
+  for (const candidate of [parts[1], parts[2]]) {
+    // Requires a trailing slash after the candidate, so a FILE named after a
+    // version (/25.2.html, or /streaming/25.2.json) is not read as a segment.
+    if (candidate && Object.prototype.hasOwnProperty.call(segments, candidate) &&
+        url.includes(`/${candidate}/`)) {
+      return candidate
+    }
+  }
+  return null
+}
+
+module.exports.versionSegmentFromUrl = versionSegmentFromUrl
+module.exports.readMapping = readMapping

src/js/react/AskAI.jsx

@@ -287,6 +287,32 @@ const CUSTOM_INSTRUCTIONS = `## Domain context
 // The docs page the widget is open on, appended to the agent instructions so it
 // can infer the user's product (Cloud / Self-Managed / ADP) from context before
 // asking. Antora sets <body data-component> to the docs component.
+// Kapa source group scoping retrieval to the docs version of THIS page
+// (DOC-1807, DOC-2450). The array is emitted per page by chat-panel.hbs via the
+// get-kapa-source-groups helper, so it varies by URL without rebuilding the bundle.
+//
+// The two SDKs spell the same option differently, and Kapa documents the
+// inconsistency deliberately (dev/agent/migrating-from-chat-sdk):
+//
+//   Agent SDK (signed in)  sourceGroupIdsInclude   lowercase d
+//   Chat SDK  (anonymous)  sourceGroupIDsInclude   capital ID
+//
+// A typo in either fails silently -- an unknown prop is ignored, no filter is
+// sent, and answers quietly come from every docs version. So the name is derived
+// from one place rather than written out at each call site.
+//
+// Spread rather than passed directly so that an empty array omits the prop
+// entirely instead of sending []. Kapa treats an explicit empty list as "clear
+// filtering", which is the same outcome, but omitting keeps the provider props
+// identical to their pre-DOC-2450 shape when scoping cannot be resolved.
+const SOURCE_GROUP_PROP = { agent: 'sourceGroupIdsInclude', chat: 'sourceGroupIDsInclude' }
+
+function sourceGroupProps (tier) {
+  const ids = Array.isArray(window.KAPA_SOURCE_GROUP_IDS) ? window.KAPA_SOURCE_GROUP_IDS.filter(Boolean) : []
+  if (!ids.length) return {}
+  return { [SOURCE_GROUP_PROP[tier]]: ids }
+}
+
 function currentPageContext () {
   try {
     const path = window.location.pathname
@@ -419,6 +445,7 @@ function App () {
         tools={agentTools}
         customInstructions={CUSTOM_INSTRUCTIONS + currentPageContext()}
         user={user?.email ? { email: user.email } : undefined}
+        {...sourceGroupProps('agent')}
         enableHistory
         onEvent={handleAgentEvent}
         theme={{ accentColor: '#444ce7', colorScheme }}
@@ -441,6 +468,7 @@ function App () {
       <KapaProvider
         integrationId={window.KAPA_CHAT_INTEGRATION_ID}
         apiService={persistentApiService}
+        {...sourceGroupProps('chat')}
         callbacks={{
           askAI: {
             onQuerySubmit: (data) => {

src/partials/chat-panel-bump.hbs

@@ -61,6 +61,17 @@
     ];
     // Signed-in agent tier: tool-showcasing prompts (static here — the standalone
     // Bump widget has no Antora component context for get-agent-suggestions).
+    {{!-- KAPA_SOURCE_GROUP_IDS is deliberately NOT set here. This partial is compiled
+          at build time from context/chat-panel.json (compileWidgets in gulpfile.js),
+          which carries no Antora page or site data, so get-kapa-source-groups has
+          nothing to resolve against.
+          /api/ pages should scope to the latest version, and docs-site sets it: its
+          proxy-api-docs edge function already fetches this widget's compiled HTML and
+          rewrites the DOM, and it has the source-group mapping available, so it
+          injects the "current" group id there. Keeping the id out of this template
+          avoids a second hardcoded copy that would go stale the moment a group is
+          recreated -- a stale id scopes to a group holding nothing, which silently
+          returns only global sources. --}}
     window.AGENT_SUGGESTIONS = [
       'Write and test a Bloblang mapping that flattens nested JSON',
       "What's the latest Redpanda Streaming version?",

src/partials/chat-panel.hbs

@@ -56,6 +56,15 @@
       "{{{this}}}"{{#unless @last}},{{/unless}}
       {{/each}}
     ];
+    {{!-- Kapa source group scoping retrieval to THIS page's docs version (DOC-1807,
+          DOC-2450). Empty array means send no filter, which is the pre-DOC-2450
+          behaviour of searching every version at once. Emitted per page rather than
+          bundled, so it varies by URL for free. --}}
+    window.KAPA_SOURCE_GROUP_IDS = window.KAPA_SOURCE_GROUP_IDS || [
+      {{#each (get-kapa-source-groups)}}
+      "{{{this}}}"{{#unless @last}},{{/unless}}
+      {{/each}}
+    ];
     {{!-- Signed-in agent tier: per-component prompts that showcase the agent tools --}}
     window.AGENT_SUGGESTIONS = window.AGENT_SUGGESTIONS || [
       {{#each (get-agent-suggestions)}}