@redpanda-data/docs-extensions-and-macros 5.35.1 → 5.37.0

package/bin/doc-tools.js

@@ -2312,6 +2312,107 @@ automation
     }
   })
 
+/**
+ * generate kapa-source-groups
+ *
+ * @description
+ * Reads the source-group tree and the per-source group assignments from Kapa's ingestion API
+ * and writes a mapping from each docs URL version segment to the Kapa source group that scopes
+ * retrieval to that version. Consumers pass the group id as `sourceGroupIdsInclude` (Agent SDK),
+ * `sourceGroupIDsInclude` (Chat SDK, note the capital ID) or `_meta.source_group_ids_include`
+ * (hosted MCP server).
+ *
+ * The mapping is keyed on the URL segment, not Antora's page.version, because the two disagree
+ * for the latest release: latest_version_segment: 'current' publishes 26.2 at
+ * /streaming/current/ while page.version reads 26.2.
+ *
+ * This command only ever reads from Kapa. Kapa publishes no write API ("we do not provide an API
+ * endpoint for uploading or managing sources"), so the groups and their source assignments are
+ * created by hand in the Kapa dashboard under Sources > Manage groups. Run this afterwards to
+ * record what is there.
+ *
+ * Refuses rather than writing a misleading mapping when: no groups exist, no group has children,
+ * any version group has no sources assigned, or --default-segment is not one of the groups. An
+ * empty version group is worse than no group, because scoping a query to it returns only the
+ * global sources and the reader silently gets no version-specific content.
+ *
+ * @why
+ * Kapa indexes one separately crawled source per published docs version. Without retrieval
+ * scoping a reader gets answers drawn from any of them: a measured call for "What is a Redpanda
+ * topic partition?" returned 12 sections, six of which were the same get-started/architecture
+ * page at six different versions. Source groups fix that at retrieval time, but the group UUIDs
+ * live in Kapa while the version list lives in Antora, so something has to join the two. Because
+ * a new docs version appears with no file change in docs-site (the playbook globs branches: v/*),
+ * a hand-maintained mapping goes stale silently; generating it and diff-checking the result in CI
+ * is what makes drift loud.
+ *
+ * @example
+ * # Write the mapping to its default location
+ * export KAPA_API_KEY=... KAPA_PROJECT_ID=...
+ * npx doc-tools generate kapa-source-groups
+ *
+ * # Preview without writing
+ * npx doc-tools generate kapa-source-groups --dry-run
+ *
+ * # Scope unversioned pages to something other than "current"
+ * npx doc-tools generate kapa-source-groups --default-segment 26.1
+ *
+ * # Disambiguate when more than one group has children
+ * npx doc-tools generate kapa-source-groups --parent-group Streaming
+ *
+ * @requirements
+ * - Kapa API key and project ID, set via KAPA_API_KEY and KAPA_PROJECT_ID
+ * - Create the key in the Kapa platform under Configuration > API Keys; the project ID is the
+ *   UUID in the dashboard URL (https://app.kapa.ai/<project-id>)
+ * - The parent group and its version sub groups must already exist in Kapa, with each version
+ *   group holding at least one source
+ * - Internet connection to reach https://api.kapa.ai
+ */
+automation
+  .command('kapa-source-groups')
+  .description('Generate the docs version segment to Kapa source group mapping from Kapa\'s ingestion API')
+  .option('--output <file>', 'Output file (relative to repo root, must stay inside the repository)', 'docs-data/kapa-source-groups.json')
+  .option('--default-segment <segment>', 'Segment used for pages with no version of their own', 'current')
+  .option('--parent-group <name>', 'Restrict to one parent group by name (default: the only group that has children)')
+  .option('--dry-run', 'Print output to stdout instead of writing file')
+  .action(async (options) => {
+    const { generateKapaSourceGroups } = require('../tools/kapa-source-groups/generate-kapa-source-groups.js')
+    const { requireKapaCredentials } = require('../cli-utils/kapa-credentials')
+
+    try {
+      const repoRoot = findRepoRoot()
+      // resolveInsideRepo for the same reason every other generator uses it: this
+      // command is reachable from the MCP server, where a write option that escapes
+      // the repo is a write-anywhere primitive.
+      const absOutput = options.dryRun ? undefined : resolveInsideRepo(repoRoot, options.output, '--output')
+
+      // Fail loud on a missing credential rather than emitting an empty mapping:
+      // unauthenticated would look identical to "Kapa has no source groups", and the
+      // drift check would then report false drift forever.
+      const { apiKey, projectId } = requireKapaCredentials()
+
+      const out = await generateKapaSourceGroups({
+        apiKey,
+        projectId,
+        defaultSegment: options.defaultSegment,
+        parentGroupName: options.parentGroup,
+      })
+
+      if (options.dryRun) {
+        process.stdout.write(out)
+        return
+      }
+
+      fs.mkdirSync(path.dirname(absOutput), { recursive: true })
+      fs.writeFileSync(absOutput, out, 'utf8')
+      const segments = Object.keys(JSON.parse(out).segments)
+      console.log(`Done: Wrote ${absOutput} (${segments.length} version segments: ${segments.join(', ')})`)
+    } catch (err) {
+      console.error(`Error: Failed to generate Kapa source groups: ${err.message}`)
+      process.exit(1)
+    }
+  })
+
 const validation = new Command('validate').description('Validate docs data against internal sources of truth')
 
 /**
@@ -2734,6 +2835,167 @@ overridesGroup
   })
 
 programCli.addCommand(automation)
+/**
+ * validate kapa-source-groups
+ *
+ * @description
+ * Checks that every streaming docs version currently published has a Kapa source, so Ask AI
+ * can scope answers to it. Exit status is meaningful: 0 every version is covered, 1 a version
+ * is missing, 2 the command itself failed (Kapa or the sitemap unreachable, bad credentials).
+ *
+ * A version counts as covered when Kapa has a source named `Documentation (X)` for it, that
+ * source is assigned to a source group, AND the committed mapping (docs-data/kapa-source-groups.json)
+ * has a segment for it whose group_id is a group that source actually sits in. Four gaps are
+ * reported, each with its own line:
+ *
+ * - missing: the version is published but Kapa has no `Documentation (X)` source.
+ * - unassigned: the source exists but is in no group, so it is global in Kapa and returned for
+ *   EVERY query on every version.
+ * - unmapped: Kapa has the grouped source but the committed mapping has no segment for it. Every
+ *   deployed surface reads the mapping, not Kapa, so readers on that version silently get the
+ *   default segment until the mapping is regenerated and released.
+ * - mismatched: the mapping has the segment but its group_id is not a group the version's source
+ *   sits in, which is what a group deleted and recreated in the dashboard, or a source moved into
+ *   another version's group, looks like. Every Ask AI query on that version is then scoped to a
+ *   group that no longer holds its docs, until the mapping is regenerated and released.
+ *
+ * The prerelease segment (/streaming/beta/) is ignored: a beta publishes there for the whole
+ * pre-GA cycle and is not expected to have a Kapa group of its own.
+ *
+ * @why
+ * The latest release always publishes at /streaming/current/, and the `Documentation (current)`
+ * crawl follows it, so latest is never the version that goes missing. The one that goes missing
+ * is the version that just got archived: when 26.3 ships, 26.2 moves to /streaming/26.2/ and
+ * needs a crawl of its own that nobody has made yet. Kapa has no write API, so that crawl is
+ * created by hand in the dashboard, and nothing else notices when it is forgotten. Readers on the
+ * archived version then silently fall back to the default segment.
+ *
+ * Run it on a schedule so the gap opens an issue rather than waiting for a bug report.
+ *
+ * @example
+ * export KAPA_API_KEY=... KAPA_PROJECT_ID=...
+ * npx doc-tools validate kapa-source-groups
+ *
+ * # Check a preview or staging site instead of production
+ * npx doc-tools validate kapa-source-groups --site-url https://deploy-preview-123--redpanda-documentation.netlify.app
+ *
+ * @requirements
+ * - Kapa API key and project ID, set via KAPA_API_KEY and KAPA_PROJECT_ID
+ * - Internet connection to reach https://api.kapa.ai and the docs site's sitemap
+ */
+validation
+  .command('kapa-source-groups')
+  .description('Check every published streaming version has a grouped Kapa source and the committed mapping points at that group (exit 0 in sync, 1 gap, 2 error)')
+  .option('--site-url <url>', 'Docs site whose sitemap says which versions are published', 'https://docs.redpanda.com')
+  .option('--mapping <file>', 'Committed mapping every surface reads', 'docs-data/kapa-source-groups.json')
+  .action(async (options) => {
+    const { fetchKapaSourceVersions } = require('../tools/kapa-source-groups/kapa-source-versions.js')
+    const { fetchPublishedSegments, isPrereleaseSegment } = require('../tools/kapa-source-groups/published-segments.js')
+    const { requireKapaCredentials } = require('../cli-utils/kapa-credentials')
+
+    // Printed only where a gap has actually been established, and required by
+    // kapa-source-groups-drift.sh before it files an issue. Exit 1 alone is not
+    // trustworthy: Commander exits 1 on a usage error and an uncaught throw
+    // exits 1 too, so without this a typo'd flag would file an issue quoting a
+    // stack trace as the report.
+    const SENTINEL = 'KAPA_DRIFT_CONFIRMED'
+
+    // Exit 2 is reserved for "could not find out", so the scheduled job can tell
+    // "a version is missing" apart from "Kapa was down" and not file a false issue.
+    let published, kapa
+    try {
+      const { apiKey, projectId } = requireKapaCredentials()
+      ;[published, kapa] = await Promise.all([
+        fetchPublishedSegments({ siteUrl: options.siteUrl }),
+        fetchKapaSourceVersions({ apiKey, projectId }),
+      ])
+    } catch (err) {
+      console.error(`Error: Could not check Kapa sources: ${err.message}`)
+      process.exit(2)
+    }
+
+    // The committed mapping is what every surface actually reads (the Antora
+    // extension, docs-ui, the /api/ proxy, the MCP server). Kapa having a
+    // grouped source is necessary but not sufficient: if nobody regenerated and
+    // released the mapping, readers on that version still get the default
+    // segment and nothing else would ever say so.
+    let mappedSegments, mappedGroupIds
+    try {
+      const mappingPath = path.resolve(options.mapping)
+      const mapping = JSON.parse(fs.readFileSync(mappingPath, 'utf8'))
+      if (!mapping || typeof mapping.segments !== 'object' || mapping.segments === null) {
+        throw new Error('no segments object')
+      }
+      mappedSegments = new Set(Object.keys(mapping.segments))
+      mappedGroupIds = new Map(Object.entries(mapping.segments)
+        .map(([seg, entry]) => [seg, entry && entry.group_id != null ? String(entry.group_id) : null]))
+    } catch (err) {
+      console.error(`Error: Could not read the committed mapping at ${options.mapping}: ${err.message}`)
+      process.exit(2)
+    }
+
+    // A beta publishes at /streaming/beta/ for the whole pre-GA cycle and has no
+    // group of its own by design. Reporting it would file a false issue weekly.
+    const prerelease = published.filter(isPrereleaseSegment)
+    const versions = published.filter((v) => !isPrereleaseSegment(v))
+
+    const missing = versions.filter((v) => !kapa.covered.has(v) && !kapa.unassigned.has(v))
+    const unassigned = versions.filter((v) => kapa.unassigned.has(v))
+    const unmapped = versions.filter((v) => kapa.covered.has(v) && !mappedSegments.has(v))
+    // The mapping is what gets sent with every query, so its group_id has to be a
+    // group the version's source is in right now. A group deleted and recreated
+    // keeps its name and gets a new id; a source moved to another version's
+    // group leaves the old id pointing at a group without these docs. Kapa
+    // reports neither, and the three checks above pass in both cases.
+    const mismatched = versions.filter((v) => {
+      if (!kapa.covered.has(v) || !mappedSegments.has(v)) return false
+      const want = mappedGroupIds.get(v)
+      const have = kapa.groups.get(v) || new Set()
+      return !want || !have.has(want)
+    })
+
+    if (prerelease.length) {
+      console.log(`  (ignoring prerelease segment${prerelease.length > 1 ? 's' : ''} ${prerelease.join(', ')}, ` +
+        'which publishes for the pre-GA cycle and is not expected to have a Kapa group)')
+    }
+
+    if (missing.length === 0 && unassigned.length === 0 && unmapped.length === 0 && mismatched.length === 0) {
+      console.log(`✓ Every published streaming version (${versions.join(', ')}) has a Kapa source in a group, ` +
+        `and ${options.mapping} points each one at that group.`)
+      process.exit(0)
+    }
+
+    console.log('✗ Kapa and the committed mapping are out of sync for published streaming docs versions.\n')
+    for (const v of missing) {
+      console.log(`  - ${v}: published at /streaming/${v}/ but Kapa has no "Documentation (${v})" source. ` +
+        'Readers on this version fall back to the default segment.')
+    }
+    for (const v of unassigned) {
+      console.log(`  - ${v}: "Documentation (${v})" exists but is not in a source group, so it is global ` +
+        'and returned for every query on every version.')
+    }
+    for (const v of unmapped) {
+      console.log(`  - ${v}: Kapa has a grouped "Documentation (${v})" source, but ${options.mapping} has no ` +
+        `"${v}" segment. Readers on this version fall back to the default segment until the mapping is ` +
+        'regenerated and released.')
+    }
+    for (const v of mismatched) {
+      const want = mappedGroupIds.get(v)
+      const have = [...(kapa.groups.get(v) || [])]
+      console.log(`  - ${v}: ${options.mapping} scopes this version to group ${want || '(no group_id)'}, but Kapa has ` +
+        `"Documentation (${v})" in ${have.length === 1 ? 'group' : 'groups'} ${have.join(', ')}. Every Ask AI query on ` +
+        'this version is sent with a group that no longer holds its docs until the mapping is regenerated and released.')
+    }
+    if (missing.length || unassigned.length) {
+      console.log('\nIn the Kapa dashboard: Sources > Add source for the crawl, then assign it to the version ' +
+        'group under Sources > Manage groups. Then regenerate the mapping:\n  doc-tools generate kapa-source-groups')
+    } else {
+      console.log('\nRegenerate the mapping and release docs-extensions-and-macros:\n  doc-tools generate kapa-source-groups')
+    }
+    console.log(`\n${SENTINEL}`)
+    process.exit(1)
+  })
+
 programCli.addCommand(validation)
 programCli.addCommand(overridesGroup)
 programCli.parse(process.argv)

package/cli-utils/kapa-credentials.js

@@ -0,0 +1,109 @@
+/**
+ * Kapa API Credentials Utility
+ *
+ * Provides a consistent way to retrieve Kapa API credentials from environment
+ * variables, so no generator reads process.env.KAPA_* directly. Mirrors
+ * cli-utils/github-token.js: resolve here, return null when absent, and let the
+ * calling command decide whether a missing credential is fatal.
+ *
+ * The variable names are not new. They are already the established pair in
+ * redpanda-data/docs-site (netlify/functions/kapa-session.mjs) and in
+ * docs-team-standards/scripts/docs_analytics/kapa_probe.py, so a third spelling
+ * would just be a fourth place to get it wrong.
+ */
+
+// Kapa's public API. Both the ingestion and query endpoints live here, and both
+// authenticate with the same project API key -- there is no separate ingestion
+// key and no scope model.
+const KAPA_API_BASE = 'https://api.kapa.ai';
+
+// Kapa's OpenAPI schema spells the header X-API-KEY; their prose pages also use
+// X-API-Key in places. HTTP header names are case-insensitive so either works,
+// but pin the canonical spelling from the schema.
+const KAPA_API_KEY_HEADER = 'X-API-KEY';
+
+/**
+ * Get the Kapa API key.
+ *
+ * @param {object} [env] - Environment to read (defaults to process.env)
+ * @returns {string|null} The API key, or null when unset/blank
+ */
+function getKapaApiKey (env = process.env) {
+  const key = (env.KAPA_API_KEY || '').trim()
+  return key || null
+}
+
+/**
+ * Get the Kapa project ID.
+ *
+ * @param {object} [env] - Environment to read (defaults to process.env)
+ * @returns {string|null} The project ID, or null when unset/blank
+ */
+function getKapaProjectId (env = process.env) {
+  const id = (env.KAPA_PROJECT_ID || '').trim()
+  return id || null
+}
+
+/**
+ * True when both credentials are present.
+ *
+ * @param {object} [env] - Environment to read (defaults to process.env)
+ * @returns {boolean}
+ */
+function hasKapaCredentials (env = process.env) {
+  return Boolean(getKapaApiKey(env) && getKapaProjectId(env))
+}
+
+/**
+ * Resolve both credentials, or throw with a remediation hint naming exactly
+ * what is missing.
+ *
+ * Generators that write published content call this and let it throw: an
+ * unauthenticated run would otherwise produce an empty mapping that looks
+ * identical to "Kapa has no source groups", and the drift check would then
+ * report false drift forever. Fail loud, like cloud-regions does for its
+ * GitHub token.
+ *
+ * @param {object} [env] - Environment to read (defaults to process.env)
+ * @returns {{apiKey: string, projectId: string, apiBase: string, headerName: string}}
+ * @throws {Error} When either credential is missing
+ */
+function requireKapaCredentials (env = process.env) {
+  const apiKey = getKapaApiKey(env)
+  const projectId = getKapaProjectId(env)
+
+  const missing = []
+  if (!apiKey) missing.push('KAPA_API_KEY')
+  if (!projectId) missing.push('KAPA_PROJECT_ID')
+
+  if (missing.length) {
+    throw new Error(
+      `Kapa credentials are required: ${missing.join(' and ')} ${missing.length > 1 ? 'are' : 'is'} not set. ` +
+      'Create an API key in the Kapa platform under Configuration > API Keys, and find the project ID ' +
+      'in the dashboard URL (https://app.kapa.ai/<project-id>). ' +
+      'In CI these come from AWS Secrets Manager via OIDC, not from GitHub secrets directly.'
+    )
+  }
+
+  return { apiKey, projectId, apiBase: KAPA_API_BASE, headerName: KAPA_API_KEY_HEADER }
+}
+
+/**
+ * Build the auth headers for a Kapa API request.
+ *
+ * @param {string} apiKey
+ * @returns {object} Headers suitable for fetch()
+ */
+function kapaAuthHeaders (apiKey) {
+  return { [KAPA_API_KEY_HEADER]: apiKey, Accept: 'application/json' }
+}
+
+module.exports = {
+  KAPA_API_BASE,
+  KAPA_API_KEY_HEADER,
+  getKapaApiKey,
+  getKapaProjectId,
+  hasKapaCredentials,
+  requireKapaCredentials,
+  kapaAuthHeaders,
+}

package/docs-data/kapa-source-groups.json

@@ -0,0 +1,119 @@
+{
+  "project_id": "97f44223-f930-4fb9-ae1e-ecd436a4d85c",
+  "parent_group": {
+    "id": "238b3c08-5cf6-4615-937c-fa2f5a2e83a4",
+    "name": "Streaming",
+    "type": "product"
+  },
+  "default_segment": "current",
+  "segments": {
+    "23.3": {
+      "group_id": "625e5538-aa73-4969-a5c1-4c35a0108a94",
+      "group_name": "23.3",
+      "source_ids": [
+        "21672ac9-cc94-4529-8835-55334ede0a18"
+      ],
+      "source_names": [
+        "Documentation (23.3)"
+      ]
+    },
+    "24.1": {
+      "group_id": "29357fc1-30b1-46d4-a9de-e30f9b696b2f",
+      "group_name": "24.1",
+      "source_ids": [
+        "0d68df8c-1f9b-45f6-baa3-25d8bb46b164"
+      ],
+      "source_names": [
+        "Documentation (24.1)"
+      ]
+    },
+    "24.2": {
+      "group_id": "3442b9cb-67db-4800-a320-9def40551b93",
+      "group_name": "24.2",
+      "source_ids": [
+        "11659ad5-b7df-4a06-9e8b-4e9913795889"
+      ],
+      "source_names": [
+        "Documentation (24.2)"
+      ]
+    },
+    "24.3": {
+      "group_id": "11288265-8a9e-4a49-8c63-2f9fbe459b76",
+      "group_name": "24.3",
+      "source_ids": [
+        "f1377953-8bcc-48c9-a0e7-acb8efae701e"
+      ],
+      "source_names": [
+        "Documentation (24.3)"
+      ]
+    },
+    "25.1": {
+      "group_id": "317edba8-6c78-4cca-bad5-1dfe47c9d3dc",
+      "group_name": "25.1",
+      "source_ids": [
+        "6cfe84a2-4d5b-4123-b302-f372a5500d02"
+      ],
+      "source_names": [
+        "Documentation (25.1)"
+      ]
+    },
+    "25.2": {
+      "group_id": "639427c4-06fb-4b8f-8df3-d6a444b85101",
+      "group_name": "25.2",
+      "source_ids": [
+        "4d4d1a66-08e7-46aa-ac72-fea301f96b5f"
+      ],
+      "source_names": [
+        "Documentation (25.2)"
+      ]
+    },
+    "25.3": {
+      "group_id": "65723bc1-941c-4b3b-b5ba-2c601f7b3ba9",
+      "group_name": "25.3",
+      "source_ids": [
+        "d1213d06-6132-47e2-abca-43fe0a85dde6"
+      ],
+      "source_names": [
+        "Documentation (25.3)"
+      ]
+    },
+    "26.1": {
+      "group_id": "f0751d2d-de07-4a9c-8d75-7960121178b7",
+      "group_name": "26.1",
+      "source_ids": [
+        "ec6810ab-6208-4e6b-acef-83da55d45762"
+      ],
+      "source_names": [
+        "Documentation (26.1)"
+      ]
+    },
+    "current": {
+      "group_id": "35567e94-30c7-4608-ab5d-1ff982339d05",
+      "group_name": "current",
+      "source_ids": [
+        "f5c1e522-be3a-45f6-8463-11abc1b35ea9"
+      ],
+      "source_names": [
+        "Documentation (current)"
+      ]
+    }
+  },
+  "global_sources": [
+    "Admin API",
+    "Agentic Data Plane",
+    "Cloud Controlplane API",
+    "Cloud Dataplane API",
+    "Corrected Responses",
+    "Documentation (Cloud)",
+    "Documentation (RPCN)",
+    "GitHub Discussions",
+    "HTTP Proxy API",
+    "pylon",
+    "Recruitment Scam Page",
+    "Redpanda Connect Release Notes",
+    "Redpanda Core Release Notes",
+    "Schema Registry API",
+    "Terraform provider",
+    "YouTube Tutorials"
+  ]
+}

package/docs-data/kapa-source-groups.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://redpanda.com/schemas/kapa-source-groups.schema.json",
+  "title": "Kapa source groups",
+  "description": "Generated mapping from a docs URL version segment to the Kapa source group that scopes retrieval to that version. Produced by `doc-tools generate kapa-source-groups` from Kapa's ingestion API; do not hand-edit. Kapa publishes no write API, so the groups and their source assignments are created in the Kapa dashboard and this file only records what is there. See tools/kapa-source-groups/generate-kapa-source-groups.js.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["project_id", "parent_group", "default_segment", "segments", "global_sources"],
+  "properties": {
+    "project_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Kapa project the groups belong to. Matches KAPA_PROJECT_ID. Recorded so a mapping generated against the wrong project is obvious rather than silently wrong."
+    },
+    "parent_group": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "name", "type"],
+      "description": "The product-level group the version groups hang off. Kapa's hierarchy is two levels and is expressed top-down via sub_groups; there is no parent_id field anywhere in its schema, so the generator finds this by 'the group that has children' rather than by name. Renaming it in the dashboard is therefore safe.",
+      "properties": {
+        "id": { "type": "string", "format": "uuid" },
+        "name": { "type": "string" },
+        "type": {
+          "type": ["string", "null"],
+          "enum": ["product", "version", null],
+          "description": "Kapa requires every group to be typed. The enum appears only in Kapa's API schema, not in any prose doc. Nothing in Kapa's documented retrieval semantics reads it, so it is recorded for humans rather than relied on."
+        }
+      }
+    },
+    "default_segment": {
+      "type": "string",
+      "description": "Segment used for any page with no version of its own: Cloud, Connect, Agentic Data Plane, labs, home, search, the 404 page, and the Bump-rendered /api/ pages. Must be a key of `segments`. Deliberately set rather than left unset: sending no group filter makes Kapa search every version at once, which is the DOC-2450 failure (a reader on an unversioned page was answered from 25.2 instead of current)."
+    },
+    "segments": {
+      "type": "object",
+      "minProperties": 1,
+      "description": "Keyed by the docs URL version segment, not by the Antora `page.version` attribute. The two disagree for the latest release: `latest_version_segment: 'current'` publishes 26.2 at /streaming/current/ while page.version reads 26.2. Kapa source_url values and the URL prefixes in docs-site's lib/platform-filter.mjs both use the segment, so that is what this keys on.",
+      "additionalProperties": { "$ref": "#/$defs/segment" }
+    },
+    "global_sources": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Names of the Kapa sources deliberately assigned to no group. These are the 'global' set: always returned alongside whichever group a query scopes to. Recorded because the design depends on it: Agentic Data Plane, Cloud and Connect content must stay reachable from every page, whatever version the reader is on. Note 'Global' is NOT a real Kapa group despite the dashboard showing a Global row: the API returns no such object and an unassigned source reports source_groups: []."
+    }
+  },
+  "$defs": {
+    "segment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["group_id", "group_name", "source_ids", "source_names"],
+      "properties": {
+        "group_id": {
+          "type": "string",
+          "format": "uuid",
+          "description": "The value to pass as sourceGroupIdsInclude (Agent SDK), sourceGroupIDsInclude (Chat SDK, note the capital ID), or _meta.source_group_ids_include (hosted MCP server). Kapa group IDs are stable across renames."
+        },
+        "group_name": { "type": "string" },
+        "source_ids": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "format": "uuid" },
+          "description": "Sources assigned to this group. minItems is 1 on purpose: a version group with no sources is worse than no group at all, because scoping to it returns only the global set and the reader silently gets nothing version-specific. The generator refuses to emit such a mapping."
+        },
+        "source_names": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" },
+          "description": "Human-readable counterpart to source_ids, so a reviewer can sanity-check the mapping without opening the Kapa dashboard."
+        }
+      }
+    }
+  }
+}