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

package/bin/doc-tools.js

@@ -122,9 +122,9 @@ programCli
  * - A GitHub token with access to redpanda-data/streaming-enterprise, which is
  *   private. Redpanda releases are published there now, and the old public repo
  *   is frozen, so this command exits rather than report a stale version when it
- *   has no token. Resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN,
- *   ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in
- *   that priority order
+ *   has no token. Resolved from REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN,
+ *   GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, GH_TOKEN, or GIT_CREDENTIALS, in that
+ *   priority order (an API call, so the git credential is the last resort)
  */
 programCli
   .command('get-redpanda-version')
@@ -1908,7 +1908,7 @@ automation
  *
  * @requirements
  * - GitHub token with access to redpanda-data/cloudv2-infra repository
- * - Token is resolved from GIT_CREDENTIALS, REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, or GH_TOKEN, in that priority order
+ * - Token is resolved from REDPANDA_GITHUB_TOKEN, ACTIONS_BOT_TOKEN, GITHUB_TOKEN, VBOT_GITHUB_API_TOKEN, GH_TOKEN, or GIT_CREDENTIALS, in that priority order (an API call, so the git credential is the last resort)
  * - Internet connection to access GitHub API
  */
 automation
@@ -1925,7 +1925,7 @@ automation
   .option('--dry-run', 'Print output to stdout instead of writing file')
   .action(async (options, command) => {
     const { generateCloudRegions } = require('../tools/cloud-regions/generate-cloud-regions.js')
-    const { getGitHubToken } = require('../cli-utils/github-token')
+    const { getGitHubApiToken } = require('../cli-utils/github-token')
 
     try {
       // The default output path holds the unfiltered table, so a filtered run
@@ -1947,7 +1947,7 @@ automation
       const absOutput = options.dryRun
         ? undefined
         : resolveInsideRepo(repoRoot, options.output, '--output')
-      const token = getGitHubToken()
+      const token = getGitHubApiToken()
       if (!token) {
         throw new Error('GitHub token is required to fetch from private cloudv2-infra repo.')
       }
@@ -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/enterprise-sources.js

@@ -12,7 +12,7 @@
 
 const fs = require('fs')
 const path = require('path')
-const { getGitHubToken } = require('./github-token')
+const { getGitHubApiToken } = require('./github-token')
 
 const RAW = 'https://raw.githubusercontent.com'
 
@@ -62,7 +62,7 @@ async function discardBody (resp) {
  * check runs on a weekly cron where nobody is watching live.
  *
  * @param {object} [deps]
- * @param {string|null} [deps.token] - GitHub token (defaults to getGitHubToken())
+ * @param {string|null} [deps.token] - GitHub token (defaults to getGitHubApiToken())
  * @param {Function} [deps.fetchImpl] - fetch implementation (defaults to global fetch)
  * @param {Function} [deps.warn] - warning sink (defaults to console.warn)
  * @param {Function} [deps.sleep] - delay implementation, for tests
@@ -72,7 +72,7 @@ async function discardBody (resp) {
  *   check that never ran. Failures without a sourceName throw instead.
  */
 function createSourceFetcher (deps = {}) {
-  const ghToken = deps.token !== undefined ? deps.token : getGitHubToken()
+  const ghToken = deps.token !== undefined ? deps.token : getGitHubApiToken()
   const fetchImpl = deps.fetchImpl || ((...args) => fetch(...args))
   const warn = deps.warn || ((msg) => console.warn(msg))
   const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))

package/cli-utils/github-token.js

@@ -47,9 +47,25 @@ function getTokenFromGitCredentials(credentials = process.env.GIT_CREDENTIALS) {
   return null;
 }
 
+const API_TOKEN_VARS = [
+  'REDPANDA_GITHUB_TOKEN',
+  'ACTIONS_BOT_TOKEN',
+  'GITHUB_TOKEN',
+  'VBOT_GITHUB_API_TOKEN',
+  'GH_TOKEN'
+];
+
+function firstApiTokenVar() {
+  for (const name of API_TOKEN_VARS) {
+    if (process.env[name]) return process.env[name];
+  }
+  return null;
+}
+
 /**
- * Get GitHub token from environment variables
- * Checks multiple common variable names in priority order:
+ * Get the GitHub token for git operations (clone, fetch, authenticated URLs).
+ *
+ * Checks, in priority order:
  * 1. GIT_CREDENTIALS - Antora's credential store contents (github.com entry)
  * 2. REDPANDA_GITHUB_TOKEN - Custom Redpanda token
  * 3. ACTIONS_BOT_TOKEN - GitHub Actions bot token
@@ -57,21 +73,44 @@ function getTokenFromGitCredentials(credentials = process.env.GIT_CREDENTIALS) {
  * 5. VBOT_GITHUB_API_TOKEN - Legacy bot token
  * 6. GH_TOKEN - GitHub CLI default
  *
- * Note: this resolver feeds both git clone/fetch auth and GitHub API clients
- * (Octokit). Wherever GIT_CREDENTIALS is set (for example, Antora builds on
- * Netlify), API calls authenticate with that same token, whose API scopes may
- * differ from the token env vars it outranks.
+ * GIT_CREDENTIALS wins here on purpose: it is the credential Antora itself
+ * clones the content repos with, so anything else that clones in the same
+ * build should use the same identity. It is a git credential, not an API
+ * one; for REST calls use getGitHubApiToken().
  *
  * @returns {string|null} GitHub token or null if not found
  */
 function getGitHubToken() {
-  return getTokenFromGitCredentials() ||
-         process.env.REDPANDA_GITHUB_TOKEN ||
-         process.env.ACTIONS_BOT_TOKEN ||
-         process.env.GITHUB_TOKEN ||
-         process.env.VBOT_GITHUB_API_TOKEN ||
-         process.env.GH_TOKEN ||
-         null;
+  return getTokenFromGitCredentials() || firstApiTokenVar();
+}
+
+/**
+ * Get the GitHub token for REST API calls (Octokit, api.github.com,
+ * raw.githubusercontent.com).
+ *
+ * Same variables as getGitHubToken(), but GIT_CREDENTIALS comes LAST:
+ *
+ * 1. REDPANDA_GITHUB_TOKEN
+ * 2. ACTIONS_BOT_TOKEN
+ * 3. GITHUB_TOKEN
+ * 4. VBOT_GITHUB_API_TOKEN
+ * 5. GH_TOKEN
+ * 6. GIT_CREDENTIALS
+ *
+ * Why the different order: on the Netlify Antora sites GIT_CREDENTIALS holds
+ * a token scoped only to cloning the private docs content repos. Letting it
+ * outrank REDPANDA_GITHUB_TOKEN meant the release lookup against the private
+ * streaming-enterprise repo authenticated with a token that cannot see that
+ * repo, got a 404, and every latest-redpanda-* attribute went unset in the
+ * production build even though a token with access was sitting right there.
+ * An explicitly named API token always beats the git credential; the git
+ * credential remains a fallback so a build with only GIT_CREDENTIALS still
+ * authenticates.
+ *
+ * @returns {string|null} GitHub token or null if not found
+ */
+function getGitHubApiToken() {
+  return firstApiTokenVar() || getTokenFromGitCredentials();
 }
 
 /**
@@ -106,6 +145,7 @@ function hasGitHubToken() {
 
 module.exports = {
   getGitHubToken,
+  getGitHubApiToken,
   getTokenFromGitCredentials,
   getAuthenticatedGitHubUrl,
   hasGitHubToken

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/cli-utils/octokit-client.js

@@ -1,7 +1,7 @@
 'use strict'
 
 const { Octokit } = require('@octokit/rest')
-const { getGitHubToken } = require('./github-token')
+const { getGitHubApiToken } = require('./github-token')
 
 /**
  * Shared Octokit client instance for GitHub API access
@@ -14,7 +14,7 @@ const { getGitHubToken } = require('./github-token')
  */
 
 // Get authentication token from environment
-const token = getGitHubToken()
+const token = getGitHubApiToken()
 
 // Configure Octokit options
 const octokitOptions = {

package/cli-utils/self-managed-docs-branch.js

@@ -1,6 +1,6 @@
 const yaml = require('js-yaml');
 const { spawnSync } = require('child_process');
-const { getGitHubToken } = require('./github-token');
+const { getGitHubApiToken } = require('./github-token');
 
 const ANTORA_URL = 'https://raw.githubusercontent.com/redpanda-data/docs/main/antora.yml'
 
@@ -23,7 +23,7 @@ const REJECTED_HINT = ' A GitHub token was sent but rejected, so it may be expir
  */
 async function fetchRemoteAntoraVersion(deps = {}) {
   const fetchImpl = deps.fetchImpl || fetch
-  const ghToken = 'token' in deps ? deps.token : getGitHubToken()
+  const ghToken = 'token' in deps ? deps.token : getGitHubApiToken()
 
   let resp = await fetchImpl(ANTORA_URL, ghToken ? { headers: { Authorization: `Bearer ${ghToken}` } } : undefined)
   const hint = ghToken ? REJECTED_HINT : TOKEN_HINT