@redpanda-data/docs-extensions-and-macros 5.2.5 → 5.3.1

package/tools/rpk-docs/rpk-docs-handler.js

@@ -1,13 +1,15 @@
 'use strict'
 
 const { spawnSync } = require('child_process')
+const crypto = require('crypto')
 const path = require('path')
 const fs = require('fs')
 const os = require('os')
 const semver = require('semver')
 const { findRepoRoot } = require('../../cli-utils/doc-tools-utils')
-const { generateRpkDocs, applyOverridesToTree, resolveReferences } = require('./generate-rpk-docs')
-const { generateRpkDiff, printDiffReport, generateWhatsNewSection } = require('./report-delta')
+const { generateRpkDocs, applyOverridesToTree, resolveReferences, shouldExcludeCommand, shouldUsePartialDir } = require('./generate-rpk-docs')
+const { detectLinuxOnlyFromSource, warnIfDetectionLooksBroken } = require('./detect-platform-commands')
+const { generateRpkDiff, printDiffReport, generateWhatsNewSection, flattenToMap } = require('./report-delta')
 const { loadAndValidateOverrides, ValidationResult } = require('./validate-overrides')
 const { validateDirectory, formatResults } = require('./validate-output')
 
@@ -16,6 +18,37 @@ const { validateDirectory, formatResults } = require('./validate-output')
  */
 const KNOWN_PLUGINS = ['ai', 'check', 'connect', 'k8s', 'oxla']
 
+/**
+ * Plugins whose docs can be refreshed individually with --plugin.
+ * oxla is excluded: it is a "Coming Soon" stub with no installable binary.
+ */
+const REFRESHABLE_PLUGINS = ['ai', 'check', 'connect', 'k8s']
+
+/**
+ * Per-plugin install flags that pin a version (rpk <plugin> install <flag> <version>).
+ * k8s uses the generic flag name; the others embed the plugin name.
+ */
+const PLUGIN_INSTALL_VERSION_FLAGS = {
+  ai: '--ai-version',
+  check: '--check-version',
+  connect: '--connect-version',
+  k8s: '--plugin-version'
+}
+
+/**
+ * Manifest slugs at https://rpk-plugins.redpanda.com/<slug>/manifest.json
+ * where the slug differs from the rpk command name.
+ */
+const PLUGIN_MANIFEST_SLUGS = { ai: 'rpai' }
+
+const PLUGIN_MANIFEST_HOST = 'https://rpk-plugins.redpanda.com'
+
+/**
+ * Subcommands compiled into rpk itself for managed plugins. A plugin node
+ * whose children are only these never actually installed.
+ */
+const PLUGIN_SHIM_SUBCOMMANDS = new Set(['install', 'uninstall', 'upgrade'])
+
 /**
  * Parse Go version from 'go version' output
  * @param {string} versionOutput - Output from 'go version' command
@@ -347,9 +380,12 @@ function fetchRpkTreeFromSource(sourcePath) {
  * Builds rpk binary, installs plugins, then runs --print-tree for complete command coverage.
  * Falls back to native Go build if Docker is unavailable.
  * @param {string} sourcePath - Path to rpk Go source directory (e.g., ~/redpanda/src/go/rpk)
- * @returns {Object} Parsed JSON tree
+ * @returns {Object} { tree, failedPlugins } — the parsed JSON tree plus the
+ *   names of managed plugins whose install failed this run. Callers pass
+ *   failedPlugins to generateRpkDocs as protectedPlugins so those plugins'
+ *   existing pages and nav entries are preserved instead of treated as stale.
  */
-function fetchRpkTreeFromLinuxSource(sourcePath) {
+function fetchRpkTreeFromLinuxSource(sourcePath, pluginPins = {}) {
   // Resolve to absolute path
   const absoluteSourcePath = path.resolve(sourcePath)
 
@@ -455,18 +491,46 @@ function fetchRpkTreeFromLinuxSource(sourcePath) {
   try {
     // Step 1: Build rpk binary
     console.log('Building rpk binary...')
-    const buildResult = spawnSync('docker', [
-      'exec', containerId,
-      'go', 'build', '-o', '/tmp/rpk', './cmd/rpk'
-    ], {
-      encoding: 'utf8',
-      timeout: 300000 // 5 minutes for build
-    })
+    // Module downloads from proxy.golang.org fail transiently (stream
+    // INTERNAL_ERROR), especially on a cold module cache. Retry: the second
+    // attempt reuses whatever the first already downloaded.
+    let buildResult
+    let binaryExists = false
+    for (let attempt = 1; attempt <= 4; attempt++) {
+      buildResult = spawnSync('docker', [
+        'exec', containerId,
+        'go', 'build', '-o', '/tmp/rpk', './cmd/rpk'
+      ], {
+        encoding: 'utf8',
+        timeout: 300000 // 5 minutes per attempt
+      })
+
+      if (buildResult.status === 0) {
+        // Trust but verify: docker exec has been observed returning zero for
+        // a build that produced nothing, and everything downstream execs
+        // /tmp/rpk. Treat a phantom success as a failed attempt.
+        const binCheck = spawnSync('docker', [
+          'exec', containerId, 'test', '-x', '/tmp/rpk'
+        ], { encoding: 'utf8', timeout: 15000 })
+        if (binCheck.status === 0) {
+          binaryExists = true
+          break
+        }
+        if (attempt < 4) {
+          console.warn(`  Build attempt ${attempt} reported success but produced no binary; retrying...`)
+          continue
+        }
+      } else if (attempt < 4) {
+        const firstError = (buildResult.stderr || buildResult.signal || 'unknown error')
+          .toString().trim().split('\n').slice(-1)[0]
+        console.warn(`  Build attempt ${attempt} failed (${firstError}); retrying...`)
+      }
+    }
 
-    if (buildResult.status !== 0) {
+    if (!binaryExists) {
       const stderr = buildResult.stderr || ''
       throw new Error(
-        `Failed to build rpk in Linux container: ${stderr}\n` +
+        `Failed to build rpk in Linux container: ${stderr || 'build produced no binary'}\n` +
         'Common causes:\n' +
         '  1. Source code is out of date - run: git pull origin dev\n' +
         '  2. Go module issues - the container will download dependencies automatically\n' +
@@ -477,15 +541,31 @@ function fetchRpkTreeFromLinuxSource(sourcePath) {
 
     // Step 2: Install plugins
     console.log('Installing plugins for complete command coverage...')
+    const failedPlugins = []
     for (const plugin of KNOWN_PLUGINS) {
-      console.log(`  Installing plugin: ${plugin}...`)
-      const installResult = spawnSync('docker', [
-        'exec', containerId,
-        '/tmp/rpk', plugin, 'install'
-      ], {
-        encoding: 'utf8',
-        timeout: 120000
-      })
+      // A pin installs a specific version instead of the manifest's latest.
+      // This is how pre-GA plugins (no version promoted to latest) get into a
+      // full regeneration at all — without a pin their install resolves
+      // nothing and their commands are absent from the tree.
+      const pin = pluginPins[plugin]
+      const versionFlag = PLUGIN_INSTALL_VERSION_FLAGS[plugin]
+      const runInstall = (pinned) => {
+        const args = ['exec', containerId, '/tmp/rpk', plugin, 'install']
+        if (pinned && pin && versionFlag) {
+          args.push(versionFlag, pin)
+        }
+        return spawnSync('docker', args, { encoding: 'utf8', timeout: 120000 })
+      }
+
+      console.log(`  Installing plugin: ${plugin}${pin ? ` (pinned to ${pin})` : ''}...`)
+      let installResult = runInstall(true)
+      if (installResult.status !== 0 && pin) {
+        const output = `${installResult.stderr || ''}${installResult.stdout || ''}`
+        if (output.includes('unknown flag') || output.includes('is not valid')) {
+          console.warn(`    rpk rejected the version pin for ${plugin}; retrying without the pin (installs latest)`)
+          installResult = runInstall(false)
+        }
+      }
 
       if (installResult.status === 0) {
         console.log(`    ✓ ${plugin} installed`)
@@ -498,13 +578,14 @@ function fetchRpkTreeFromLinuxSource(sourcePath) {
           console.log(`    - ${plugin} is not an installable plugin`)
         } else {
           // A failed install is non-fatal: generation continues, but this
-          // plugin's commands will be absent from the tree. Expected for `k8s`
-          // during the 26.2 beta window — `rpk k8s install` finds no `latest`
-          // release because the plugin publisher's stableVersionRe only promotes
-          // pure X.Y.Z versions, so k8s commands only appear at GA. A pre-GA
-          // regen that omits `rpk k8s` pages is this, not a generator bug.
+          // plugin's commands will be absent from the tree. Expected for
+          // beta-only plugins with no version pin — `rpk <plugin> install`
+          // finds no `latest` release because the plugin publisher's
+          // stableVersionRe only promotes pure X.Y.Z versions, so their
+          // commands only appear at GA unless the run pins a version.
           // See redpanda-data/docs#1801.
           console.warn(`    ✗ Failed to install ${plugin}: ${stderr || stdout}`)
+          failedPlugins.push(plugin)
         }
       }
     }
@@ -536,8 +617,9 @@ function fetchRpkTreeFromLinuxSource(sourcePath) {
       )
     }
 
+    let tree
     try {
-      return JSON.parse(result.stdout)
+      tree = JSON.parse(result.stdout)
     } catch (err) {
       throw new Error(
         `Failed to parse rpk tree JSON from Linux source build: ${err.message}\n` +
@@ -545,6 +627,26 @@ function fetchRpkTreeFromLinuxSource(sourcePath) {
         'This may indicate a version mismatch or corrupted source.'
       )
     }
+
+    // Step 4: Fill in flags for plugin subtrees. Their commands come from
+    // --help-autocomplete, which carries no flag data, so without this every
+    // plugin command page renders an empty flags section.
+    console.log('Extracting flags from plugin command help output...')
+    for (const plugin of KNOWN_PLUGINS) {
+      const node = (tree.commands || []).find(c => c.name === plugin)
+      if (!node || !pluginNodeHasRealCommands(node)) continue
+      const enriched = enrichPluginTreeWithFlags(node, (argPath) => {
+        const helpResult = spawnSync('docker', [
+          'exec', containerId, '/tmp/rpk', ...argPath, '--help'
+        ], { encoding: 'utf8', timeout: 30000 })
+        return helpResult.status === 0 ? helpResult.stdout : null
+      })
+      if (enriched > 0) {
+        console.log(`  ${plugin}: extracted flags for ${enriched} command(s)`)
+      }
+    }
+
+    return { tree, failedPlugins }
   } finally {
     // Clean up container
     console.log('Cleaning up build container...')
@@ -555,105 +657,6 @@ function fetchRpkTreeFromLinuxSource(sourcePath) {
   }
 }
 
-/**
- * Scan Go source files for Linux-only build tags
- * Looks for //go:build linux or // +build linux
- * @param {string} sourcePath - Path to rpk Go source directory
- * @returns {Set<string>} Set of Linux-only command paths (e.g., 'rpk redpanda tune')
- */
-function detectLinuxOnlyFromSource(sourcePath) {
-  const linuxOnlyCommands = new Set()
-
-  // Map of source directory patterns to command paths
-  // rpk commands are typically in pkg/cli/cmd/<command>/<subcommand>/
-  const scanDirectory = (dir, prefix = '') => {
-    if (!fs.existsSync(dir)) return
-
-    const entries = fs.readdirSync(dir, { withFileTypes: true })
-
-    for (const entry of entries) {
-      const fullPath = path.join(dir, entry.name)
-
-      if (entry.isDirectory()) {
-        // Recurse into subdirectories
-        const newPrefix = prefix ? `${prefix} ${entry.name}` : entry.name
-        scanDirectory(fullPath, newPrefix)
-      } else if (entry.name.endsWith('.go') && !entry.name.endsWith('_test.go')) {
-        // Check Go files for build tags
-        try {
-          const content = fs.readFileSync(fullPath, 'utf8')
-          const firstLines = content.split('\n').slice(0, 20).join('\n')
-
-          // Check for Linux build constraints
-          const hasLinuxTag = /\/\/go:build\s+.*linux/.test(firstLines) ||
-                             /\/\/\s*\+build\s+.*linux/.test(firstLines)
-
-          if (hasLinuxTag) {
-            // Try to determine command path from file location
-            const commandPath = inferCommandPath(sourcePath, fullPath, entry.name)
-            if (commandPath) {
-              linuxOnlyCommands.add(commandPath)
-            }
-          }
-        } catch (err) {
-          // Skip files we can't read
-        }
-      }
-    }
-  }
-
-  // Scan the cmd/rpk directory for command implementations
-  const cmdDir = path.join(sourcePath, 'pkg', 'cli', 'cmd')
-  if (fs.existsSync(cmdDir)) {
-    scanDirectory(cmdDir, 'rpk')
-  }
-
-  // Also check the older structure
-  const oldCmdDir = path.join(sourcePath, 'cmd', 'rpk')
-  if (fs.existsSync(oldCmdDir)) {
-    scanDirectory(oldCmdDir, 'rpk')
-  }
-
-  return linuxOnlyCommands
-}
-
-/**
- * Infer command path from Go source file location
- * @param {string} sourcePath - Root source path
- * @param {string} filePath - Full path to Go file
- * @param {string} fileName - Name of the Go file
- * @returns {string|null} Command path or null
- */
-function inferCommandPath(sourcePath, filePath, fileName) {
-  // Get relative path from source root
-  const relativePath = filePath.replace(sourcePath, '').replace(/^\//, '')
-
-  // Common patterns:
-  // pkg/cli/cmd/redpanda/tune.go -> rpk redpanda tune
-  // pkg/cli/cmd/redpanda/start.go -> rpk redpanda start
-  // cmd/rpk/iotune/iotune.go -> rpk iotune
-
-  // Remove common prefixes and file extension
-  let parts = relativePath
-    .replace(/^pkg\/cli\/cmd\//, '')
-    .replace(/^cmd\/rpk\//, '')
-    .replace(/\.go$/, '')
-    .split('/')
-
-  // If file name matches directory name, use directory only
-  // e.g., iotune/iotune.go -> iotune
-  if (parts.length > 1 && parts[parts.length - 1] === parts[parts.length - 2]) {
-    parts = parts.slice(0, -1)
-  }
-
-  // Filter out common non-command directories
-  parts = parts.filter(p => !['internal', 'common', 'config', 'cmd'].includes(p))
-
-  if (parts.length === 0) return null
-
-  return 'rpk ' + parts.join(' ')
-}
-
 /**
  * Add platform markers to command tree based on source analysis
  * @param {Object} tree - Command tree from rpk --print-tree
@@ -668,11 +671,18 @@ function addPlatformMarkersFromSource(tree, linuxOnlyCommands) {
            [...linuxOnlyCommands].some(loc => cmdPath.startsWith(loc + ' '))
   }
 
+  // Collect every tree path actually marked Linux-only so the persisted
+  // linux_only_commands list is fully expanded (each descendant listed),
+  // matching what dynamic Linux-vs-Darwin tree comparison produces.
+  const markedPaths = new Set()
+
   const markCommands = (commands, parentPath = 'rpk') => {
     if (!commands) return commands
     return commands.map(cmd => {
       const fullPath = `${parentPath} ${cmd.name}`
-      const platforms = isLinuxOnly(fullPath)
+      const linuxOnly = isLinuxOnly(fullPath)
+      if (linuxOnly) markedPaths.add(fullPath)
+      const platforms = linuxOnly
         ? [PLATFORMS.LINUX]
         : [PLATFORMS.LINUX, PLATFORMS.DARWIN]
       return {
@@ -691,11 +701,15 @@ function addPlatformMarkersFromSource(tree, linuxOnlyCommands) {
     }
   }
 
+  const markedCommands = markCommands(tree.commands)
+
   return {
     ...tree,
     platforms: [PLATFORMS.LINUX, PLATFORMS.DARWIN],
-    linux_only_commands: [...linuxOnlyCommands],
-    commands: markCommands(tree.commands)
+    // Union of detected paths and marked tree paths: keeps detected roots
+    // even when the tree was built on a platform where they don't exist
+    linux_only_commands: [...new Set([...linuxOnlyCommands, ...markedPaths])].sort(),
+    commands: markedCommands
   }
 }
 
@@ -773,7 +787,58 @@ function loadOverrides(overridesPath, commandTree = null, options = {}) {
     )
   }
 
-  return overrides
+  return { overrides, validation }
+}
+
+/**
+ * Merge deprecation metadata for commands still present in the tree into the
+ * overrides file, so their pages render deprecation banners without manual
+ * curation. Hidden deprecated commands are excluded: they are absent from
+ * --print-tree, have no pages, and would only produce unknown-path warnings.
+ * Commands whose overrides already carry a `deprecated` value are left alone.
+ * @param {Object} deprecatedCommands - Map from scan-deprecated-commands.js
+ * @param {Object} tree - Current command tree
+ * @param {string} overridesPath - Path to overrides JSON file
+ */
+function mergeVisibleDeprecationsIntoOverrides(deprecatedCommands, tree, overridesPath) {
+  const entries = Object.entries(deprecatedCommands || {})
+  if (entries.length === 0 || !overridesPath || !fs.existsSync(overridesPath)) {
+    return
+  }
+
+  const treePaths = new Set(flattenToMap(tree).keys())
+
+  let overrides
+  try {
+    overrides = JSON.parse(fs.readFileSync(overridesPath, 'utf8'))
+  } catch (err) {
+    console.warn(`Warning: Could not parse overrides file for deprecation merge: ${err.message}`)
+    return
+  }
+  if (!overrides.commands) {
+    overrides.commands = {}
+  }
+
+  let annotated = 0
+  for (const [cmdPath, info] of entries) {
+    if (!treePaths.has(cmdPath)) continue
+    const existing = overrides.commands[cmdPath] || {}
+    if (existing.deprecated !== undefined) continue
+    overrides.commands[cmdPath] = {
+      ...existing,
+      deprecated: true,
+      ...(info.deprecatedMessage && !existing.deprecatedMessage
+        ? { deprecatedMessage: info.deprecatedMessage } : {}),
+      ...(info.replacement && !existing.replacement
+        ? { replacement: info.replacement } : {})
+    }
+    annotated++
+  }
+
+  if (annotated > 0) {
+    fs.writeFileSync(overridesPath, JSON.stringify(overrides, null, 2), 'utf8')
+    console.log(`Annotated ${annotated} visible deprecated command(s) in ${overridesPath}`)
+  }
 }
 
 /**
@@ -824,8 +889,12 @@ function loadVersionedJson(version, dataDir) {
  * @param {Object} diffData - Diff data with new commands and flags
  * @param {string} overridesPath - Path to overrides JSON file
  * @param {string} version - Version to set as introducedInVersion
+ * @param {Object} [pluginVersions] - Plugin versions keyed by rpk command
+ *   name. Commands under a plugin subtree are stamped with the plugin's own
+ *   version (the page note renders "introduced in <plugin> version X"), not
+ *   the rpk version, because plugins release on their own cadence.
  */
-function updateOverridesWithIntroducedVersions(diffData, overridesPath, version) {
+function updateOverridesWithIntroducedVersions(diffData, overridesPath, version, pluginVersions = {}) {
   const hasNewCommands = diffData.details.newCommands && diffData.details.newCommands.length > 0
   const hasNewFlags = diffData.details.newFlags && diffData.details.newFlags.length > 0
 
@@ -833,6 +902,12 @@ function updateOverridesWithIntroducedVersions(diffData, overridesPath, version)
     return
   }
 
+  // "rpk connect lint" -> pluginVersions.connect, else the rpk version
+  const versionFor = (cmdPath) => {
+    const topLevel = cmdPath.split(' ')[1]
+    return pluginVersions[topLevel] || version
+  }
+
   let overrides = {}
   if (fs.existsSync(overridesPath)) {
     try {
@@ -859,7 +934,7 @@ function updateOverridesWithIntroducedVersions(diffData, overridesPath, version)
       }
       // Only set if not already set (preserve manual overrides)
       if (!overrides.commands[cmdPath].introducedInVersion) {
-        overrides.commands[cmdPath].introducedInVersion = version
+        overrides.commands[cmdPath].introducedInVersion = versionFor(cmdPath)
         commandsUpdated++
       }
     }
@@ -883,7 +958,7 @@ function updateOverridesWithIntroducedVersions(diffData, overridesPath, version)
 
       // Only set if not already set (preserve manual overrides)
       if (!overrides.commands[cmdPath].flags[flagName].introducedInVersion) {
-        overrides.commands[cmdPath].flags[flagName].introducedInVersion = version
+        overrides.commands[cmdPath].flags[flagName].introducedInVersion = versionFor(cmdPath)
         flagsUpdated++
       }
     }
@@ -970,8 +1045,80 @@ function countCommands(node) {
  * @param {string} whatsNewPath - Path to what's-new.adoc file
  * @param {string} version - Version string for display
  */
-function updateWhatsNewFile(diffData, whatsNewPath, version) {
-  const whatsNewContent = generateWhatsNewSection(diffData, { version })
+/**
+ * Build a predicate that reports whether a command path renders as a
+ * linkable page (not excluded and not routed to partials by the overrides).
+ * @param {Object|null} overridesData - Loaded overrides
+ * @returns {Function} (commandPath) => boolean
+ */
+/**
+ * Build a predicate that reports whether a command path has subcommands,
+ * which determines its page location (groups render into their own dir).
+ * @param {Object} tree - Full command tree
+ * @returns {Function} (commandPath) => boolean
+ */
+function makeSubcommandPredicate(tree) {
+  const commandMap = flattenToMap(tree)
+  return (commandPath) => {
+    const node = commandMap.get(commandPath)
+    return Boolean(node && (node.commands || []).length > 0)
+  }
+}
+
+function makeLinkablePredicate(overridesData) {
+  const resolved = overridesData ? resolveReferences(overridesData, overridesData) : null
+  return (commandPath) => {
+    // rpk cloud and rpk security secret render to partials (single-sourced
+    // into cloud docs), so this repo has no linkable pages for them
+    if (commandPath.startsWith('rpk cloud') || commandPath.startsWith('rpk security secret')) {
+      return false
+    }
+    if (!resolved) return true
+    return !shouldExcludeCommand(resolved, commandPath) &&
+      !shouldUsePartialDir(resolved, commandPath)
+  }
+}
+
+// Command subtrees whose changes never belong in the Self-Managed What's
+// new. rpk ai's documentation home is adp-docs, and the ADP release notes
+// already cover its CLI changes per release. The plugin-release receiver
+// workflow excludes ai from --update-whats-new for exactly this reason; the
+// full-regeneration path must agree, or a full run floods the Self-Managed
+// release notes with rpk ai entries (a rename release alone produces 21 new
+// plus 21 removed bullets).
+const WHATS_NEW_EXCLUDED_SUBTREES = ['rpk ai']
+
+/**
+ * Return a copy of diffData without entries under the excluded subtrees.
+ * Only the published What's-new block filters; diff reports and PR
+ * summaries keep the full picture.
+ * @param {Object} diffData - Diff from generateRpkDiff
+ * @param {string[]} [excluded] - Command-path prefixes to drop
+ * @returns {Object} Filtered copy
+ */
+function filterDiffForWhatsNew(diffData, excluded = WHATS_NEW_EXCLUDED_SUBTREES) {
+  const outside = (cmdPath) => !excluded.some(prefix =>
+    cmdPath === prefix || (typeof cmdPath === 'string' && cmdPath.startsWith(prefix + ' ')))
+  const details = diffData.details || {}
+  const filteredDetails = { ...details }
+  for (const key of ['newCommands', 'newlyDeprecatedCommands', 'removedCommands', 'descriptionChanges']) {
+    if (Array.isArray(details[key])) filteredDetails[key] = details[key].filter(e => outside(e.path))
+  }
+  for (const key of ['newFlags', 'removedFlags', 'changedDefaults', 'changedFlagTypes', 'changedFlagRequirements', 'changedFlagDescriptions']) {
+    if (Array.isArray(details[key])) filteredDetails[key] = details[key].filter(e => outside(e.commandPath))
+  }
+  return { ...diffData, details: filteredDetails }
+}
+
+function updateWhatsNewFile(diffData, whatsNewPath, version, options = {}) {
+  // Each block opens with a "=== <version>" heading so accumulated blocks
+  // (successive RCs, multiple plugin releases) never collide on section ids
+  const sectionHeading = options.sectionHeading || '== Redpanda CLI'
+  const whatsNewContent = generateWhatsNewSection(diffData, {
+    version,
+    blockLabel: version,
+    ...options
+  })
 
   if (!whatsNewContent) {
     console.log('No Redpanda CLI changes to add to what\'s new')
@@ -987,9 +1134,39 @@ function updateWhatsNewFile(diffData, whatsNewPath, version) {
 
   const existingContent = fs.readFileSync(whatsNewPath, 'utf8')
 
-  // Check if Redpanda CLI section already exists
-  if (existingContent.includes('== Redpanda CLI')) {
-    console.log('Redpanda CLI section already exists in what\'s-new file')
+  // Version-scoped marker block: re-runs for the same version replace their
+  // own block, and later versions (for example, successive RCs in a beta
+  // cycle, or plugin releases) append their own blocks inside the existing
+  // Redpanda CLI section instead of being dropped. Writers can edit or
+  // remove blocks freely; the automation only ever touches content between
+  // its own markers for the same version label.
+  const startMarker = `// AUTOGEN-RPK-CHANGES ${version} START`
+  const endMarker = `// AUTOGEN-RPK-CHANGES ${version} END`
+  const sectionBody = whatsNewContent.replace(/^== [^\n]*\n+/, '')
+  const block = `${startMarker}\n${sectionBody.trimEnd()}\n${endMarker}`
+  const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+  if (existingContent.includes(startMarker)) {
+    // Replace this version's existing block (idempotent re-runs)
+    const blockRe = new RegExp(`${escapeRe(startMarker)}[\\s\\S]*?${escapeRe(endMarker)}`)
+    const updatedContent = existingContent.replace(blockRe, block)
+    fs.writeFileSync(whatsNewPath, updatedContent, 'utf8')
+    console.log(`Refreshed existing ${version} block in what's-new file: ${whatsNewPath}`)
+    return
+  }
+
+  const headingMatch = existingContent.match(new RegExp(`^${escapeRe(sectionHeading)}[^\\n]*$`, 'm'))
+  if (headingMatch) {
+    // Append this version's block at the end of the existing section, just
+    // before the next level-2 heading (or end of file)
+    const sectionStart = headingMatch.index + headingMatch[0].length
+    const rest = existingContent.slice(sectionStart)
+    const nextHeading = rest.search(/\n== /)
+    const insertAt = nextHeading === -1 ? existingContent.length : sectionStart + nextHeading
+    const before = existingContent.slice(0, insertAt).replace(/\s*$/, '\n\n')
+    const after = existingContent.slice(insertAt).replace(/^\n*/, '\n')
+    fs.writeFileSync(whatsNewPath, `${before}${block}${after}`, 'utf8')
+    console.log(`Appended ${version} block to the "${sectionHeading}" section in: ${whatsNewPath}`)
     return
   }
 
@@ -1011,19 +1188,583 @@ function updateWhatsNewFile(diffData, whatsNewPath, version) {
     }
   }
 
+  const fullSection = `${sectionHeading}\n\n${block}\n`
+
   let updatedContent
   if (insertIndex > 0) {
     // Insert before the matched section
     updatedContent = existingContent.slice(0, insertIndex) +
-      whatsNewContent + '\n' +
+      fullSection + '\n' +
       existingContent.slice(insertIndex)
   } else {
     // Append at the end
-    updatedContent = existingContent + '\n' + whatsNewContent
+    updatedContent = existingContent.replace(/\s*$/, '\n\n') + fullSection
   }
 
   fs.writeFileSync(whatsNewPath, updatedContent, 'utf8')
-  console.log(`Updated what's-new file: ${whatsNewPath}`)
+  console.log(`Created "${sectionHeading}" section in what's-new file: ${whatsNewPath}`)
+}
+
+/**
+ * Build an rpk binary natively from Go source.
+ * @param {string} sourcePath - Path to rpk Go source directory (src/go/rpk)
+ * @param {string} outPath - Where to write the binary
+ * @returns {string} Path to the built binary
+ */
+function buildRpkBinary(sourcePath, outPath) {
+  const goCheck = spawnSync('go', ['version'], { encoding: 'utf8', timeout: 5000 })
+  if (goCheck.status !== 0) {
+    throw new Error(
+      'Go is required to build rpk from source but was not found.\n' +
+      'Install Go from https://go.dev/ and ensure it\'s in your PATH.'
+    )
+  }
+
+  const installedGoVersion = parseGoVersion(goCheck.stdout)
+  const requiredGoVersion = getRequiredGoVersion(sourcePath)
+  if (installedGoVersion && requiredGoVersion &&
+      !checkGoVersionSufficient(installedGoVersion, requiredGoVersion)) {
+    throw new Error(
+      `Go version mismatch: installed ${installedGoVersion}, required >= ${requiredGoVersion}\n` +
+      `The rpk source (go.mod) requires Go ${requiredGoVersion} or newer.`
+    )
+  }
+
+  console.log(`Building rpk from source at ${sourcePath}...`)
+  const buildResult = spawnSync('go', ['build', '-o', outPath, './cmd/rpk'], {
+    cwd: sourcePath,
+    encoding: 'utf8',
+    timeout: 300000
+  })
+
+  if (buildResult.status !== 0) {
+    throw new Error(`Failed to build rpk from source: ${buildResult.stderr}`)
+  }
+
+  return outPath
+}
+
+/**
+ * Download an official rpk release binary for the current platform.
+ * @param {string} tag - Release tag (e.g., v26.1.12)
+ * @param {string} destDir - Directory to download and extract into
+ * @returns {string|null} Path to the extracted binary, or null if the
+ *   release asset is unavailable (caller falls back to a source build)
+ */
+function downloadRpkRelease(tag, destDir) {
+  const osName = { darwin: 'darwin', linux: 'linux', win32: 'windows' }[process.platform]
+  const archName = { arm64: 'arm64', x64: 'amd64' }[process.arch]
+  if (!osName || !archName) {
+    console.warn(`No rpk release asset for platform ${process.platform}/${process.arch}`)
+    return null
+  }
+
+  const assetName = `rpk-${osName}-${archName}.zip`
+  const baseUrl = `https://github.com/redpanda-data/redpanda/releases/download/${tag}`
+  const zipPath = path.join(destDir, assetName)
+
+  console.log(`Downloading ${assetName} for ${tag}...`)
+  const curlResult = spawnSync('curl', [
+    '-fL', '--retry', '5', '--retry-all-errors',
+    '--connect-timeout', '30', '--max-time', '300',
+    '-o', zipPath, `${baseUrl}/${assetName}`
+  ], { encoding: 'utf8', timeout: 360000 })
+
+  if (curlResult.status !== 0) {
+    console.warn(`Could not download rpk release for ${tag} (draft or missing release asset)`)
+    return null
+  }
+
+  // Verify against the release checksum file when it exists
+  const checksumAsset = `rpk_${tag.replace(/^v/, '')}_checksums.txt`
+  const checksumPath = path.join(destDir, checksumAsset)
+  const checksumResult = spawnSync('curl', [
+    '-fsSL', '--retry', '3', '--connect-timeout', '30', '--max-time', '60',
+    '-o', checksumPath, `${baseUrl}/${checksumAsset}`
+  ], { encoding: 'utf8', timeout: 90000 })
+
+  if (checksumResult.status === 0) {
+    const expectedLine = fs.readFileSync(checksumPath, 'utf8')
+      .split('\n')
+      .find(line => line.trim().endsWith(assetName))
+    if (expectedLine) {
+      const expected = expectedLine.trim().split(/\s+/)[0]
+      const actual = crypto.createHash('sha256').update(fs.readFileSync(zipPath)).digest('hex')
+      if (expected !== actual) {
+        throw new Error(
+          `Checksum mismatch for ${assetName} (${tag}):\n` +
+          `  expected ${expected}\n  actual   ${actual}`
+        )
+      }
+      console.log('Checksum verified')
+    }
+  } else {
+    console.warn('No checksum file published for this release; skipping verification')
+  }
+
+  const unzipResult = spawnSync('unzip', ['-o', zipPath, '-d', destDir], {
+    encoding: 'utf8',
+    timeout: 60000
+  })
+  if (unzipResult.status !== 0) {
+    throw new Error(`Failed to extract ${assetName}: ${unzipResult.stderr}`)
+  }
+
+  const binPath = path.join(destDir, 'rpk')
+  if (!fs.existsSync(binPath)) {
+    throw new Error(`Extracted archive did not contain an rpk binary: ${zipPath}`)
+  }
+  fs.chmodSync(binPath, 0o755)
+  return binPath
+}
+
+/**
+ * Get an rpk binary matching the given version.
+ * Prefers the official release download (published stable releases only;
+ * RC releases are drafts, so their assets are not publicly downloadable).
+ * Falls back to building from source at the tag.
+ * @param {string} rpkVersion - Version tag from the snapshot (e.g., v26.1.12, v26.2.1-rc2)
+ * @param {Object} [options]
+ * @param {string} [options.rpkBin] - Existing binary to use, skipping download/build
+ * @returns {string} Path to an rpk binary
+ */
+function acquireRpkBinary(rpkVersion, options = {}) {
+  const { rpkBin } = options
+
+  if (rpkBin) {
+    const binPath = path.resolve(rpkBin)
+    if (!fs.existsSync(binPath)) {
+      throw new Error(`rpk binary not found: ${binPath}`)
+    }
+    console.log(`Using provided rpk binary: ${binPath}`)
+    return binPath
+  }
+
+  const tag = rpkVersion.startsWith('v') ? rpkVersion : `v${rpkVersion}`
+  const workDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rpk-bin-'))
+
+  // Only published (non-draft) releases have downloadable assets
+  if (/^v\d+\.\d+\.\d+$/.test(tag)) {
+    const downloaded = downloadRpkRelease(tag, workDir)
+    if (downloaded) {
+      return downloaded
+    }
+    console.log('Falling back to building rpk from source...')
+  } else {
+    console.log(`No published release binary for ${tag}; building from source...`)
+  }
+
+  if (!/^v\d+\.\d+\.\d+(-rc\d+)?$/.test(tag) && tag !== 'vdev') {
+    throw new Error(
+      `Cannot acquire an rpk binary for version '${rpkVersion}'.\n` +
+      'The snapshot\'s rpk_version is not a release tag. ' +
+      'Pass --rpk-bin <path> to use a local rpk binary instead.'
+    )
+  }
+
+  const sourceRef = tag === 'vdev' ? 'dev' : tag
+  const sourcePath = prepareSourceFromRef(sourceRef, null)
+  try {
+    return buildRpkBinary(sourcePath, path.join(workDir, 'rpk'))
+  } catch (nativeErr) {
+    // Local Go older than go.mod requires is common on laptops; the --ref
+    // path already tolerates this by building in a container, so do the same
+    // here when Docker is available
+    const dockerCheck = spawnSync('docker', ['info'], { encoding: 'utf8', timeout: 10000 })
+    if (dockerCheck.status !== 0) {
+      throw new Error(
+        `${nativeErr.message}\n` +
+        'Docker is not available for a container build either. ' +
+        'Update Go, start Docker, or pass --rpk-bin <path> to use an existing rpk binary.'
+      )
+    }
+    console.warn(`Native build failed (${nativeErr.message.split('\n')[0]}); building in a container...`)
+    const goVersion = getRequiredGoVersion(sourcePath)
+    const goImage = goVersion ? `golang:${goVersion}` : 'golang:1'
+    // Cross-compile for the HOST platform: the container reports
+    // GOOS=linux, and a linux binary dies silently when executed on the
+    // macOS host that needs it for plugin installs (review finding on the
+    // 5.3.0 train). rpk builds with CGO disabled, so cross-compilation
+    // from the linux container is safe.
+    // Only macOS and Linux hosts are supported: mapping anything else to
+    // linux would hand a Windows host an unrunnable binary, the exact bug
+    // class the cross-compile fixes (review finding on #238).
+    if (process.platform !== 'darwin' && process.platform !== 'linux') {
+      throw new Error(
+        `${nativeErr.message}\n` +
+        `Container fallback does not support host platform "${process.platform}". ` +
+        'Update Go, or pass --rpk-bin <path> to use an existing rpk binary.'
+      )
+    }
+    const hostGoos = process.platform === 'darwin' ? 'darwin' : 'linux'
+    const hostGoarch = process.arch === 'arm64' ? 'arm64' : 'amd64'
+    const buildResult = spawnSync('docker', [
+      'run', '--rm',
+      '-e', `GOOS=${hostGoos}`,
+      '-e', `GOARCH=${hostGoarch}`,
+      '-e', 'CGO_ENABLED=0',
+      '-v', `${path.resolve(sourcePath)}:/rpk-source:ro`,
+      '-v', `${workDir}:/out`,
+      '-w', '/rpk-source',
+      goImage,
+      'go', 'build', '-o', '/out/rpk', './cmd/rpk'
+    ], { encoding: 'utf8', timeout: 600000 })
+    const binPath = path.join(workDir, 'rpk')
+    if (buildResult.status !== 0 || !fs.existsSync(binPath)) {
+      throw new Error(`Container build failed: ${buildResult.stderr || 'no binary produced'}`)
+    }
+    return binPath
+  }
+}
+
+/**
+ * Look up the latest published version of a plugin from its manifest.
+ * @param {string} plugin - rpk command name (ai, connect, k8s, check)
+ * @returns {string|null} Latest version, or null if unavailable
+ */
+function fetchLatestPluginVersion(plugin) {
+  const slug = PLUGIN_MANIFEST_SLUGS[plugin] || plugin
+  const result = spawnSync('curl', [
+    '-fsSL', '--retry', '3', '--connect-timeout', '15', '--max-time', '30',
+    `${PLUGIN_MANIFEST_HOST}/${slug}/manifest.json`
+  ], { encoding: 'utf8', timeout: 60000 })
+
+  if (result.status !== 0) {
+    console.warn(`Could not fetch plugin manifest for ${plugin} (slug: ${slug})`)
+    return null
+  }
+
+  try {
+    const manifest = JSON.parse(result.stdout)
+    const latest = (manifest.archives || []).find(a => a.is_latest)
+    return latest ? latest.version : null
+  } catch (err) {
+    console.warn(`Could not parse plugin manifest for ${plugin}: ${err.message}`)
+    return null
+  }
+}
+
+/**
+ * Check whether a plugin node contains real plugin commands, as opposed to
+ * only the install/uninstall/upgrade shim compiled into rpk itself.
+ * @param {Object} node - Top-level command node for the plugin
+ * @returns {boolean}
+ */
+function pluginNodeHasRealCommands(node) {
+  return (node.commands || []).some(c => !PLUGIN_SHIM_SUBCOMMANDS.has(c.name))
+}
+
+/**
+ * Replace a plugin's top-level node in a command tree.
+ * Replace-only: throws if the plugin is not already present, so a refresh
+ * can never introduce a command that the snapshot's rpk version lacks.
+ * @param {Object} tree - Full command tree (root node)
+ * @param {string} plugin - rpk command name
+ * @param {Object} freshNode - Replacement node
+ * @returns {Object} New tree with the node replaced
+ */
+function splicePluginNode(tree, plugin, freshNode) {
+  const commands = tree.commands || []
+  if (!commands.some(c => c.name === plugin)) {
+    throw new Error(`Cannot splice plugin '${plugin}': not present in the base tree`)
+  }
+  return {
+    ...tree,
+    commands: commands.map(c => (c.name === plugin ? freshNode : c))
+  }
+}
+
+/**
+ * Carry a snapshot's recorded Linux-only command list onto a working tree.
+ * The list comes from scanning Go build tags in the rpk source, which
+ * from-json runs (including --plugin refreshes) never see, so it can only be
+ * inherited from the existing snapshot. Without it the refreshed snapshot
+ * would lose its platform markers for every future from-json run.
+ * @param {Object} tree - Working command tree (root node)
+ * @param {Object} [fallbackTree] - Tree to inherit linux_only_commands from
+ *   when the working tree does not carry the field itself
+ * @returns {Object} Tree that carries linux_only_commands when available
+ */
+function preserveLinuxOnlyCommands(tree, fallbackTree) {
+  if (!tree || tree.linux_only_commands) return tree
+  const inherited = fallbackTree && fallbackTree.linux_only_commands
+  if (!inherited) return tree
+  return { ...tree, linux_only_commands: [...inherited] }
+}
+
+/**
+ * Parse the local "Flags:" section of cobra --help output into flag objects
+ * matching the shape rpk --print-tree emits for compiled-in commands.
+ * The "Global Flags:" section is ignored: rpk-core globals are documented by
+ * the shared global-flags table, and plugin-global flags are captured from
+ * the plugin root command's own Flags section.
+ * @param {string} helpText - Output of `rpk <command> --help`
+ * @returns {Array<Object>} Flags: { name, shorthand?, type, description, default? }
+ */
+function parseCobraFlags(helpText) {
+  const lines = (helpText || '').split('\n')
+  const start = lines.findIndex(l => /^Flags:\s*$/.test(l))
+  if (start === -1) return []
+
+  const flags = []
+  let flagIndent = null
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i]
+    if (/^\S/.test(line)) break // next section (Global Flags:, Use "...", ...)
+    if (line.trim() === '') break
+
+    const m = line.match(/^\s+(?:-(\w),\s+)?--([\w.-]+)(?:\s+(\S+))?\s{2,}(.*)$/)
+    if (m) {
+      const [, shorthand, name, valueType, desc] = m
+      if (name === 'help') continue
+      flagIndent = line.search(/\S/)
+      const flag = {
+        name,
+        type: valueType || 'bool',
+        description: desc.trim()
+      }
+      if (shorthand) flag.shorthand = shorthand
+      const def = flag.description.match(/\s*\(default (.+)\)$/)
+      if (def) {
+        flag.default = def[1]
+        flag.description = flag.description.slice(0, def.index).trim()
+      }
+      flags.push(flag)
+    } else if (flags.length > 0 && flagIndent !== null && line.search(/\S/) > flagIndent) {
+      // Wrapped description continuation: any line indented deeper than the
+      // flag column that did not parse as a flag. Continuations can begin
+      // with flag-looking tokens ("(alias: --x-ref)" wraps to "--x-ref)"),
+      // so no dash guard — a genuine flag line always matches the regex
+      // above first.
+      const last = flags[flags.length - 1]
+      last.description = `${last.description} ${line.trim()}`.trim()
+      const def = last.description.match(/\s*\(default (.+)\)$/)
+      if (def) {
+        last.default = def[1]
+        last.description = last.description.slice(0, def.index).trim()
+      }
+    }
+  }
+  return flags
+}
+
+/**
+ * Parse the OPTIONS section of urfave/cli --help output (Redpanda Connect)
+ * into the same flag shape as parseCobraFlags. Entries look like:
+ *   --log.level value                     override the configured log level
+ *   --set value, -s value [ --set value, -s value ]   set a field ...
+ *   --chilled                             continue ... (default: false)
+ * The GLOBAL OPTIONS section is skipped, matching the cobra handling.
+ * @param {string} helpText - Output of `rpk <command> --help`
+ * @returns {Array<Object>} Flags: { name, shorthand?, type, description, default? }
+ */
+function parseUrfaveFlags(helpText) {
+  const lines = (helpText || '').split('\n')
+  const start = lines.findIndex(l => /^OPTIONS:\s*$/.test(l))
+  if (start === -1) return []
+
+  const flags = []
+  let urfaveIndent = null
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i]
+    if (/^\S/.test(line)) break // next section (GLOBAL OPTIONS:, ...)
+    if (line.trim() === '') break
+
+    const m = line.match(/^\s{2,}(--\S[^\s]*(?:[^ ]| (?!\s))*)\s{2,}(.*)$/)
+    if (m) {
+      const [, spec, desc] = m
+      const nameMatch = spec.match(/^--([\w.-]+)/)
+      if (!nameMatch) continue
+      const name = nameMatch[1]
+      if (name === 'help') continue
+      urfaveIndent = line.search(/\S/)
+
+      const flag = { name, description: desc.trim() }
+      const shorthandMatch = spec.match(/,\s+-(\w)\b/)
+      if (shorthandMatch) flag.shorthand = shorthandMatch[1]
+
+      const repeatable = spec.includes('[ --')
+      const hasValue = new RegExp(`^--${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s+\\S`).test(spec)
+      flag.type = repeatable ? 'strings' : (hasValue ? 'string' : 'bool')
+
+      const def = flag.description.match(/\s*\(default:\s*(.+?)\)$/)
+      if (def) {
+        flag.default = def[1]
+        flag.description = flag.description.slice(0, def.index).trim()
+      }
+      flags.push(flag)
+    } else if (flags.length > 0 && urfaveIndent !== null && line.search(/\S/) > urfaveIndent) {
+      // Continuation lines may begin with flag-looking tokens; see the
+      // cobra parser above for why there is no dash guard
+      const last = flags[flags.length - 1]
+      last.description = `${last.description} ${line.trim()}`.trim()
+      const def = last.description.match(/\s*\(default:\s*(.+?)\)$/)
+      if (def) {
+        last.default = def[1]
+        last.description = last.description.slice(0, def.index).trim()
+      }
+    }
+  }
+  return flags
+}
+
+/**
+ * Parse flags from --help output regardless of CLI framework: cobra prints a
+ * "Flags:" section (rpk ai, k8s, check), urfave/cli prints "OPTIONS:"
+ * (Redpanda Connect).
+ * @param {string} helpText
+ * @returns {Array<Object>}
+ */
+function parseHelpFlags(helpText) {
+  if (/^Flags:\s*$/m.test(helpText || '')) return parseCobraFlags(helpText)
+  if (/^OPTIONS:\s*$/m.test(helpText || '')) return parseUrfaveFlags(helpText)
+  return []
+}
+
+/**
+ * Fill in flags for plugin subtree commands by running `--help` per command.
+ * Plugin subcommand nodes come from the plugin's --help-autocomplete output,
+ * which carries no flag information, so without this every plugin command
+ * page renders with an empty flags section. Nodes that already have flags
+ * (the install/uninstall/upgrade shim compiled into rpk) are left alone.
+ * Help failures are non-fatal: the affected command keeps an empty list.
+ * @param {Object} node - The plugin's top-level command node (mutated)
+ * @param {Function} execHelp - (argPath: string[]) => string|null, returns
+ *   the help text for `rpk <argPath...> --help`
+ * @returns {number} Number of commands enriched
+ */
+function enrichPluginTreeWithFlags(node, execHelp) {
+  let enriched = 0
+  const walk = (cmd, argPath) => {
+    if (!cmd.flags || cmd.flags.length === 0) {
+      const helpText = execHelp(argPath)
+      if (helpText) {
+        const flags = parseHelpFlags(helpText)
+        if (flags.length > 0) {
+          cmd.flags = flags
+          enriched++
+        }
+      }
+    }
+    for (const child of cmd.commands || []) {
+      walk(child, [...argPath, child.name])
+    }
+  }
+  walk(node, [node.name])
+  return enriched
+}
+
+/**
+ * Install a single plugin and capture its fresh command subtree.
+ * Runs with an isolated HOME so the install never touches the caller's
+ * rpk plugin state, and the caller's installed plugins never leak in.
+ * @param {Object} params
+ * @param {string} params.plugin - rpk command name (ai, connect, k8s, check)
+ * @param {string} [params.pluginVersion] - Version to pin; defaults to latest
+ * @param {string} params.rpkBinPath - rpk binary to run
+ * @returns {Object} { node, version } - Fresh plugin node and the version recorded
+ */
+function fetchPluginSubtree({ plugin, pluginVersion, rpkBinPath }) {
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'rpk-plugin-home-'))
+  const env = { ...process.env, HOME: tmpHome }
+
+  const runInstall = (pinned) => {
+    const args = [plugin, 'install']
+    const versionFlag = PLUGIN_INSTALL_VERSION_FLAGS[plugin]
+    if (pinned && pluginVersion && versionFlag) {
+      args.push(versionFlag, pluginVersion)
+    }
+    console.log(`Installing plugin: rpk ${args.join(' ')}`)
+    return spawnSync(rpkBinPath, args, { encoding: 'utf8', env, timeout: 300000 })
+  }
+
+  let pinApplied = Boolean(pluginVersion)
+  let installResult = runInstall(true)
+  if (installResult.status !== 0 && pluginVersion) {
+    const output = `${installResult.stderr || ''}${installResult.stdout || ''}`
+    // 'unknown flag': this rpk predates the pin flag.
+    // 'is not valid': rpk's version validation rejected the pin (its regex
+    // caps each segment at two digits, so connect versions like 4.102.0
+    // fail). In both cases installing latest is the right recovery: the
+    // dispatch fires right after a release, when latest IS the release.
+    if (output.includes('unknown flag') || output.includes('is not valid')) {
+      console.warn(
+        `rpk rejected the version pin for '${plugin}' ` +
+        `(${output.trim().split('\n')[0]}); retrying without the pin (installs latest)`
+      )
+      pinApplied = false
+      installResult = runInstall(false)
+    }
+  }
+  if (installResult.status !== 0) {
+    throw new Error(
+      `Failed to install plugin '${plugin}':\n` +
+      `${installResult.stderr || installResult.stdout || 'no output'}`
+    )
+  }
+
+  const treeResult = spawnSync(rpkBinPath, ['--print-tree'], {
+    encoding: 'utf8',
+    env,
+    timeout: 120000,
+    maxBuffer: 50 * 1024 * 1024
+  })
+  if (treeResult.status !== 0) {
+    const stderr = treeResult.stderr || ''
+    if (stderr.includes('unknown flag')) {
+      throw new Error(
+        'This rpk binary does not support --print-tree (requires rpk >= v26.2.0).\n' +
+        'Pass --rpk-bin with a newer binary.'
+      )
+    }
+    throw new Error(`Failed to run rpk --print-tree: ${stderr}`)
+  }
+
+  const freshTree = JSON.parse(treeResult.stdout)
+  const node = (freshTree.commands || []).find(c => c.name === plugin)
+  if (!node) {
+    throw new Error(`Plugin '${plugin}' not found in rpk command tree after install`)
+  }
+  if (!pluginNodeHasRealCommands(node)) {
+    throw new Error(
+      `Plugin '${plugin}' installed but exposed no commands beyond the ` +
+      'install/uninstall/upgrade shim.\n' +
+      'The install likely resolved nothing. For pre-GA plugins (no promoted ' +
+      'latest version in the manifest), a version pin is required: ' +
+      `--plugin-version <version>`
+    )
+  }
+
+  // Fill in per-command flags: autocomplete trees carry none, but the plugin
+  // binary is installed, so each command's --help documents them
+  console.log(`Extracting flags from ${plugin} command help output...`)
+  const enriched = enrichPluginTreeWithFlags(node, (argPath) => {
+    const helpResult = spawnSync(rpkBinPath, [...argPath, '--help'], {
+      encoding: 'utf8',
+      env,
+      timeout: 30000
+    })
+    return helpResult.status === 0 ? helpResult.stdout : null
+  })
+  console.log(`  Extracted flags for ${enriched} command(s)`)
+
+  // When the pin was applied, record it. When we fell back to latest (or no
+  // pin was given), record what the manifest says latest is: that is what
+  // actually installed.
+  const version = pinApplied ? pluginVersion : fetchLatestPluginVersion(plugin)
+  if (!version) {
+    console.warn(
+      `Could not determine the installed version of '${plugin}'; ` +
+      'plugin_versions will not be updated for this run'
+    )
+  } else if (pluginVersion && version !== pluginVersion) {
+    console.warn(
+      `Requested ${plugin} ${pluginVersion} but installed latest (${version}) ` +
+      'because rpk rejected the version pin'
+    )
+  }
+
+  return { node, version }
 }
 
 /**
@@ -1042,6 +1783,10 @@ async function handleRpkDocsGeneration(options = {}) {
     overrides: overridesPath,
     fromSource, // Path to local rpk Go source directory
     fromJson, // Path to existing versioned JSON file to regenerate from
+    plugin, // Refresh a single plugin's subtree (requires fromJson)
+    pluginVersion, // Version to pin for the plugin install (defaults to latest)
+    pluginPins = {}, // Per-plugin version pins for full generation (pre-GA plugins)
+    rpkBin, // Existing rpk binary to use for the plugin refresh
     ref, // Git ref (branch or tag) to document
     sourceRef, // Alias for ref
     diff: diffVersion,
@@ -1058,6 +1803,15 @@ async function handleRpkDocsGeneration(options = {}) {
   // Normalize ref/sourceRef
   const effectiveRef = ref || sourceRef
 
+  for (const pinnedPlugin of Object.keys(pluginPins)) {
+    if (!REFRESHABLE_PLUGINS.includes(pinnedPlugin)) {
+      console.warn(
+        `Warning: --plugin-pin for unknown plugin '${pinnedPlugin}' ` +
+        `(known plugins: ${REFRESHABLE_PLUGINS.join(', ')}); the pin will have no effect`
+      )
+    }
+  }
+
   const repoRoot = findRepoRoot()
   const dataDir = customDataDir || path.join(repoRoot, 'docs-data')
   const defaultOutputDir = path.join(repoRoot, 'modules', 'reference', 'pages', 'rpk')
@@ -1094,6 +1848,10 @@ async function handleRpkDocsGeneration(options = {}) {
   let tree
   let rpkVersion
   let sourcePath
+  // Managed plugins whose install failed this run. Passed to generateRpkDocs
+  // as explicit protectedPlugins (merged there with auto-detection) so a
+  // failed install never deletes or rewrites that plugin's existing docs.
+  let failedPlugins = []
 
   try {
     // Fast path: regenerate from existing JSON file
@@ -1105,6 +1863,10 @@ async function handleRpkDocsGeneration(options = {}) {
       console.log(`Loading command tree from ${jsonPath}`)
       const jsonData = JSON.parse(fs.readFileSync(jsonPath, 'utf8'))
       tree = jsonData.raw_tree || jsonData.tree
+      // Inherit the Linux-only command list from whichever stored tree
+      // carries it: it cannot be re-detected without the rpk source, and
+      // both rendering and the re-saved snapshot below depend on it.
+      tree = preserveLinuxOnlyCommands(tree, jsonData.tree || jsonData.raw_tree)
       rpkVersion = jsonData.rpk_version || 'local'
 
       if (!tree) {
@@ -1113,16 +1875,158 @@ async function handleRpkDocsGeneration(options = {}) {
 
       console.log(`Loaded tree with rpk version: ${rpkVersion}`)
 
+      // Refresh a single plugin's subtree in the snapshot before rendering.
+      // Plugins release on their own cadence, so their commands can change
+      // without a new rpk release. Splice the fresh subtree into the full
+      // tree and re-render everything: only the plugin's pages actually
+      // change, and stale-file cleanup, nav rebuild, and override
+      // validation all see a complete tree.
+      let pluginVersions = jsonData.plugin_versions || {}
+      let pluginDiffData = null
+      if (plugin) {
+        if (!REFRESHABLE_PLUGINS.includes(plugin)) {
+          throw new Error(
+            `Unknown plugin '${plugin}'. Supported plugins: ${REFRESHABLE_PLUGINS.join(', ')}\n` +
+            'Use the rpk command name (for example "ai"), not the manifest slug ("rpai").'
+          )
+        }
+
+        const oldNode = (tree.commands || []).find(c => c.name === plugin)
+        if (!oldNode) {
+          console.log(
+            `rpk ${rpkVersion} has no '${plugin}' command; nothing to update. ` +
+            'This is expected when the plugin only exists in a newer rpk line.'
+          )
+          return {
+            success: true,
+            skipped: true,
+            reason: `plugin '${plugin}' not present in rpk ${rpkVersion}`,
+            rpkVersion
+          }
+        }
+
+        const rpkBinPath = acquireRpkBinary(rpkVersion, { rpkBin })
+        const { node: rawNode, version: resolvedVersion } = fetchPluginSubtree({
+          plugin,
+          pluginVersion,
+          rpkBinPath
+        })
+
+        // Reapply platform markers: the fresh subtree comes from a plain
+        // --print-tree run, but every command in the snapshot's tree carries
+        // a platforms field. Reuse the snapshot's recorded Linux-only list.
+        const linuxOnly = new Set(tree.linux_only_commands || [])
+        const freshNode = addPlatformMarkersFromSource(
+          { commands: [rawNode] },
+          linuxOnly
+        ).commands[0]
+
+        // Plugin-scoped diff for the PR summary: compare only the plugin's
+        // subtree, old snapshot state vs fresh install
+        pluginDiffData = generateRpkDiff(
+          { ...tree, commands: [oldNode] },
+          { ...tree, commands: [freshNode] },
+          {
+            oldVersion: pluginVersions[plugin] || 'previous snapshot',
+            newVersion: resolvedVersion || 'latest'
+          }
+        )
+        printDiffReport(pluginDiffData)
+
+        tree = splicePluginNode(tree, plugin, freshNode)
+        if (resolvedVersion) {
+          pluginVersions = { ...pluginVersions, [plugin]: resolvedVersion }
+        }
+        console.log(
+          `Spliced fresh '${plugin}' subtree` +
+          (resolvedVersion ? ` (version ${resolvedVersion})` : '') +
+          ` into snapshot for rpk ${rpkVersion}`
+        )
+
+        // Stamp new plugin commands and flags with the plugin's own version
+        // so pages render "This command was introduced in <plugin> version X".
+        // Runs before the overrides load below, so the stamps apply to this
+        // run's rendering, not just the next one.
+        if (resolvedVersion) {
+          updateOverridesWithIntroducedVersions(
+            pluginDiffData,
+            overridesPath || path.join(dataDir, 'rpk-overrides.json'),
+            resolvedVersion,
+            { [plugin]: resolvedVersion }
+          )
+        }
+
+        if (diffVersion) {
+          console.warn('Note: --diff is ignored in --plugin mode (the summary uses a plugin-scoped diff)')
+        }
+
+        // Plugin releases land in What's new too when requested: their
+        // changes never arrive through a Redpanda release diff. Entries
+        // render without xrefs because plugin subtrees may render as
+        // partials with no linkable pages.
+        if (whatsNewPath) {
+          if (WHATS_NEW_EXCLUDED_SUBTREES.includes(`rpk ${plugin}`)) {
+            console.log(`Skipping What's new for rpk ${plugin}: its documentation home covers CLI changes in its own release notes`)
+          } else {
+            const label = resolvedVersion
+              ? `${plugin} plugin ${resolvedVersion}`
+              : `${plugin} plugin`
+            updateWhatsNewFile(pluginDiffData, whatsNewPath, label, { xrefs: false, sectionHeading: '== rpk plugins' })
+          }
+        }
+      }
+
       // Skip to documentation generation (after the source building steps)
       // Load and validate overrides
       const defaultOverridesPath = path.join(dataDir, 'rpk-overrides.json')
       const effectiveOverridesPath = overridesPath || defaultOverridesPath
-      const overridesData = loadOverrides(effectiveOverridesPath, tree, { strict: false })
+
+      // Stamp new commands and flags with introducedInVersion BEFORE the
+      // overrides load so this run's pages render the labels. Without this,
+      // a --from-json --diff run emits unlabeled pages and the labels only
+      // appear on the next regeneration (the from-source path stamps before
+      // rendering already).
+      if (diffVersion && !plugin) {
+        const oldDataForStamp = loadVersionedJson(diffVersion, dataDir)
+        if (oldDataForStamp) {
+          const stampDiff = generateRpkDiff(oldDataForStamp.raw_tree || oldDataForStamp.tree, tree, {
+            oldVersion: diffVersion,
+            newVersion: rpkVersion,
+            oldDeprecatedCommands: oldDataForStamp.deprecated_commands || {},
+            newDeprecatedCommands: jsonData.deprecated_commands || {}
+          })
+          if (stampDiff.details.newCommands.length > 0 || stampDiff.details.newFlags.length > 0) {
+            updateOverridesWithIntroducedVersions(stampDiff, effectiveOverridesPath, rpkVersion, pluginVersions)
+          }
+        }
+      }
+
+      const { overrides: overridesData, validation: overrideValidation } = loadOverrides(effectiveOverridesPath, tree, { strict: false }) || {}
 
       if (overridesData) {
         console.log(`Loaded overrides from ${effectiveOverridesPath}`)
       }
 
+      // Persist the merged snapshot so the refreshed plugin subtree and its
+      // recorded version become the new baseline (mirrors the from-source
+      // path's augmentedData structure)
+      if (plugin) {
+        // The Linux-only list can't be re-detected during a plugin refresh
+        // (it comes from Go build-tag scanning of the rpk source), so make
+        // sure the saved snapshot's trees still carry it before persisting.
+        tree = preserveLinuxOnlyCommands(tree, jsonData.raw_tree || jsonData.tree)
+        let enhancedTree = tree
+        if (overridesData) {
+          const resolvedOverrides = resolveReferences(overridesData, overridesData)
+          enhancedTree = applyOverridesToTree(tree, resolvedOverrides, '')
+        }
+        jsonData.raw_tree = tree
+        jsonData.tree = enhancedTree
+        jsonData.plugin_versions = pluginVersions
+        jsonData.generated_at = new Date().toISOString()
+        saveVersionedJson(jsonData, rpkVersion, dataDir)
+      }
+
       // Generate AsciiDoc documentation
       console.log(`\nGenerating AsciiDoc files to ${finalOutputDir}...`)
 
@@ -1132,10 +2036,11 @@ async function handleRpkDocsGeneration(options = {}) {
         outputDir: finalOutputDir,
         cloudSecretDir: finalCloudSecretDir,
         rpkVersion,
-        pluginVersions: {},
+        pluginVersions,
         draftMissing,
         preservationsDir: preserveFrom,
-        navFile
+        navFile,
+        protectedPlugins: failedPlugins
       })
 
       console.log(`\nGeneration complete!`)
@@ -1154,16 +2059,19 @@ async function handleRpkDocsGeneration(options = {}) {
         showInfo
       })
 
-      // Generate diff if requested
+      // Generate diff if requested (rpk-version diff; not used in --plugin
+      // mode, which produces its own plugin-scoped diff)
       let diffData = null
-      if (diffVersion) {
+      if (diffVersion && !plugin) {
         const oldData = loadVersionedJson(diffVersion, dataDir)
         if (oldData) {
           // Use raw_tree for diffing (falls back to tree for backward compatibility)
           const oldTree = oldData.raw_tree || oldData.tree
           diffData = generateRpkDiff(oldTree, tree, {
             oldVersion: diffVersion,
-            newVersion: rpkVersion
+            newVersion: rpkVersion,
+            oldDeprecatedCommands: oldData.deprecated_commands || {},
+            newDeprecatedCommands: jsonData.deprecated_commands || {}
           })
 
           // Save diff
@@ -1177,7 +2085,7 @@ async function handleRpkDocsGeneration(options = {}) {
 
           // Update what's-new file if requested
           if (whatsNewPath) {
-            updateWhatsNewFile(diffData, whatsNewPath, rpkVersion)
+            updateWhatsNewFile(filterDiffForWhatsNew(diffData), whatsNewPath, rpkVersion, { linkable: makeLinkablePredicate(overridesData), hasSubcommands: makeSubcommandPredicate(tree) })
           }
         } else {
           console.warn(`Warning: Could not load previous version ${diffVersion} for diff`)
@@ -1187,11 +2095,15 @@ async function handleRpkDocsGeneration(options = {}) {
       // Generate PR summary
       const prSummary = generatePRSummary({
         rpkVersion,
+        plugin,
+        pluginVersion: plugin ? pluginVersions[plugin] : undefined,
         commandCount: result.commandCount,
         filesGenerated: result.filesGenerated,
         filesSkipped: result.filesSkipped,
-        diffData,
+        diffData: plugin ? pluginDiffData : diffData,
         validationResult,
+        overrideValidation,
+        descriptionCoverage: computeDescriptionCoverage(tree, overridesData),
         outputDir: finalOutputDir
       })
 
@@ -1211,12 +2123,21 @@ async function handleRpkDocsGeneration(options = {}) {
         filesSkipped: result.filesSkipped,
         outputDir: finalOutputDir,
         rpkVersion,
-        diffData,
+        plugin,
+        pluginVersion: plugin ? pluginVersions[plugin] : undefined,
+        diffData: plugin ? pluginDiffData : diffData,
         validationResult,
         prSummary
       }
     }
 
+    if (plugin) {
+      throw new Error(
+        '--plugin requires --from-json <snapshot>.\n' +
+        'A plugin refresh splices the fresh subtree into an existing committed snapshot.'
+      )
+    }
+
     // Step 1: Get source code
     if (effectiveRef) {
       // Clone/checkout from ref
@@ -1264,10 +2185,17 @@ async function handleRpkDocsGeneration(options = {}) {
     rpkVersion = effectiveRef || 'local'
 
     // Step 2: Detect Linux-only commands
-    // Try dynamic detection first (compare Linux vs Darwin builds)
-    // Fall back to static lists for plugins and known commands
+    // Static detection (build-constraint analysis) works on any platform,
+    // including Linux CI runners. Dynamic detection (comparing Linux vs
+    // Darwin builds) supplements it below when the host can run both.
     console.log('\nAnalyzing source for Linux-only commands...')
     let linuxOnlyCommands = detectLinuxOnlyFromSource(sourcePath)
+    if (linuxOnlyCommands.size > 0) {
+      console.log(`Static detection found ${linuxOnlyCommands.size} Linux-only command path(s):`)
+      for (const cmd of [...linuxOnlyCommands].sort()) {
+        console.log(`  - ${cmd}`)
+      }
+    }
 
     // Step 3: Build rpk and get command tree
     // Use Docker if available (for running rpk plugins in Linux)
@@ -1277,33 +2205,56 @@ async function handleRpkDocsGeneration(options = {}) {
     const canBuildNative = goCheck.status === 0
     const canBuildLinux = dockerCheck.status === 0
 
-    // Dynamic detection: if we can build on both platforms, compare the trees
-    if (canBuildLinux && canBuildNative && os.platform() !== 'linux') {
+    // Dynamic detection: if we can build on both platforms, compare the trees.
+    // Only possible on non-Linux hosts: a Linux runner can cross-compile a
+    // darwin rpk but cannot execute it to get its command tree, so Linux CI
+    // relies on the static detection above.
+    // RPK_DOCS_SKIP_DYNAMIC_DETECTION=1 forces the static-only path (useful
+    // for testing what a Linux CI runner would produce).
+    const skipDynamicDetection = ['1', 'true'].includes(
+      String(process.env.RPK_DOCS_SKIP_DYNAMIC_DETECTION || '').toLowerCase()
+    )
+    if (skipDynamicDetection) {
+      console.log('\nDynamic platform detection disabled via RPK_DOCS_SKIP_DYNAMIC_DETECTION')
+    }
+    if (canBuildLinux && canBuildNative && os.platform() !== 'linux' && !skipDynamicDetection) {
       console.log('\nBuilding rpk on both Linux and Darwin for dynamic platform detection...')
 
       try {
         // Build on Linux (in container) - has all commands
         console.log('Building rpk in Linux container...')
-        const linuxTree = fetchRpkTreeFromLinuxSource(sourcePath)
-
-        // Build natively (on Darwin) - missing Linux-only commands
-        console.log('Building rpk natively for comparison...')
-        const darwinTree = fetchRpkTreeFromSource(sourcePath)
-
-        // Compare trees to find Linux-only commands
-        const dynamicLinuxOnly = detectLinuxOnlyByComparison(linuxTree, darwinTree)
-        if (dynamicLinuxOnly.size > 0) {
-          console.log(`Dynamic detection found ${dynamicLinuxOnly.size} Linux-only command(s):`)
-          for (const cmd of dynamicLinuxOnly) {
-            console.log(`  - ${cmd}`)
-            linuxOnlyCommands.add(cmd)
+        const { tree: linuxTree, failedPlugins: linuxFailedPlugins } = fetchRpkTreeFromLinuxSource(sourcePath, pluginPins)
+
+        // Build natively (on Darwin) for comparison. The Linux tree is
+        // authoritative, so a comparison-build failure (for example, local
+        // Go older than go.mod requires) only skips dynamic platform
+        // detection - it must not discard the Linux tree.
+        let darwinTree = null
+        try {
+          console.log('Building rpk natively for comparison...')
+          darwinTree = fetchRpkTreeFromSource(sourcePath)
+        } catch (nativeErr) {
+          console.warn(`⚠ Native comparison build failed: ${nativeErr.message}`)
+          console.log('Skipping dynamic platform detection; using source scanning only.')
+        }
+
+        if (darwinTree) {
+          // Compare trees to find Linux-only commands
+          const dynamicLinuxOnly = detectLinuxOnlyByComparison(linuxTree, darwinTree)
+          if (dynamicLinuxOnly.size > 0) {
+            console.log(`Dynamic detection found ${dynamicLinuxOnly.size} Linux-only command(s):`)
+            for (const cmd of dynamicLinuxOnly) {
+              console.log(`  - ${cmd}`)
+              linuxOnlyCommands.add(cmd)
+            }
           }
         }
 
         // Use the Linux tree (has all commands)
         tree = linuxTree
+        failedPlugins = linuxFailedPlugins
       } catch (dockerErr) {
-        // Docker build failed (e.g., Go version mismatch) - fall back to native build
+        // Docker build failed - fall back to native build
         console.warn(`\n⚠ Docker build failed: ${dockerErr.message}`)
         console.log('Falling back to native Go build...')
         console.log('Note: Linux-only commands will be detected via source scanning only.\n')
@@ -1312,7 +2263,7 @@ async function handleRpkDocsGeneration(options = {}) {
     } else if (canBuildLinux) {
       console.log('\nBuilding rpk in Linux container...')
       try {
-        tree = fetchRpkTreeFromLinuxSource(sourcePath)
+        ({ tree, failedPlugins } = fetchRpkTreeFromLinuxSource(sourcePath, pluginPins))
       } catch (dockerErr) {
         if (canBuildNative) {
           console.warn(`\n⚠ Docker build failed: ${dockerErr.message}`)
@@ -1332,6 +2283,12 @@ async function handleRpkDocsGeneration(options = {}) {
       )
     }
 
+    // Tripwire: an empty combined detection result while the source tree
+    // demonstrably contains Linux-gated files means the scan is broken and
+    // Linux-only pages are about to be published as cross-platform
+    // (see redpanda-data/docs#1831).
+    warnIfDetectionLooksBroken(sourcePath, linuxOnlyCommands)
+
     // Step 4: Add platform markers based on detection
     // This includes both source scanning results and static fallback lists
     tree = addPlatformMarkersFromSource(tree, linuxOnlyCommands)
@@ -1343,8 +2300,23 @@ async function handleRpkDocsGeneration(options = {}) {
     const plugins = detectPlugins(tree)
     console.log(`Detected plugins: ${plugins.join(', ') || 'none'}`)
 
-    // Note: Plugin versions not available when building from source
+    // Record the version of each plugin that actually installed during the
+    // build (`rpk <plugin> install` resolves the manifest's latest, so the
+    // manifest lookup reflects what the tree contains). Shim-only plugins
+    // (failed installs) are skipped: their subtree carries no plugin commands.
     const pluginVersions = {}
+    for (const pluginName of REFRESHABLE_PLUGINS) {
+      const node = (tree.commands || []).find(c => c.name === pluginName)
+      if (node && pluginNodeHasRealCommands(node)) {
+        const installedVersion = pluginPins[pluginName] || fetchLatestPluginVersion(pluginName)
+        if (installedVersion) {
+          pluginVersions[pluginName] = installedVersion
+        }
+      }
+    }
+    if (Object.keys(pluginVersions).length > 0) {
+      console.log(`Plugin versions: ${JSON.stringify(pluginVersions)}`)
+    }
 
     // Step 5: Scan source for deprecated/hidden commands
     let deprecatedCommands = {}
@@ -1365,7 +2337,13 @@ async function handleRpkDocsGeneration(options = {}) {
     // Load and validate overrides
     const defaultOverridesPath = path.join(dataDir, 'rpk-overrides.json')
     const effectiveOverridesPath = overridesPath || defaultOverridesPath
-    const overridesData = loadOverrides(effectiveOverridesPath, tree, { strict: false })
+
+    // Annotate deprecated commands that are still visible in the tree so
+    // their pages render deprecation banners without manual curation. Runs
+    // before the overrides load so the annotations apply to this run.
+    mergeVisibleDeprecationsIntoOverrides(deprecatedCommands, tree, effectiveOverridesPath)
+
+    const { overrides: overridesData, validation: overrideValidation } = loadOverrides(effectiveOverridesPath, tree, { strict: false }) || {}
 
     if (overridesData) {
       console.log(`Loaded overrides from ${effectiveOverridesPath}`)
@@ -1403,7 +2381,9 @@ async function handleRpkDocsGeneration(options = {}) {
         const oldTree = oldData.raw_tree || oldData.tree
         diffData = generateRpkDiff(oldTree, tree, {
           oldVersion: diffVersion,
-          newVersion: rpkVersion
+          newVersion: rpkVersion,
+          oldDeprecatedCommands: oldData.deprecated_commands || {},
+          newDeprecatedCommands: deprecatedCommands
         })
 
         // Save diff
@@ -1415,14 +2395,17 @@ async function handleRpkDocsGeneration(options = {}) {
         // Print diff report
         printDiffReport(diffData)
 
-        // Update overrides with introducedInVersion for new commands
-        if (diffData.details.newCommands.length > 0 && effectiveOverridesPath) {
-          updateOverridesWithIntroducedVersions(diffData, effectiveOverridesPath, rpkVersion)
+        // Update overrides with introducedInVersion for new commands. Plugin
+        // commands get the plugin's own version (plugins release on their own
+        // cadence, so the rpk version would be wrong and the page note would
+        // render "introduced in <plugin> version <rpk version>").
+        if ((diffData.details.newCommands.length > 0 || diffData.details.newFlags.length > 0) && effectiveOverridesPath) {
+          updateOverridesWithIntroducedVersions(diffData, effectiveOverridesPath, rpkVersion, pluginVersions)
         }
 
         // Update what's-new file if requested
         if (whatsNewPath) {
-          updateWhatsNewFile(diffData, whatsNewPath, rpkVersion)
+          updateWhatsNewFile(filterDiffForWhatsNew(diffData), whatsNewPath, rpkVersion, { linkable: makeLinkablePredicate(overridesData), hasSubcommands: makeSubcommandPredicate(tree) })
         }
       } else {
         console.warn(`Warning: Could not load previous version ${diffVersion} for diff`)
@@ -1441,7 +2424,8 @@ async function handleRpkDocsGeneration(options = {}) {
       pluginVersions,
       draftMissing,
       preservationsDir: preserveFrom,
-      navFile
+      navFile,
+      protectedPlugins: failedPlugins
     })
 
     console.log(`\nGeneration complete!`)
@@ -1463,11 +2447,13 @@ async function handleRpkDocsGeneration(options = {}) {
     // Generate PR summary
     const prSummary = generatePRSummary({
       rpkVersion,
+      overrideValidation,
       commandCount: result.commandCount,
       filesGenerated: result.filesGenerated,
       filesSkipped: result.filesSkipped,
       diffData,
       validationResult,
+      descriptionCoverage: computeDescriptionCoverage(tree, overridesData),
       outputDir: finalOutputDir
     })
 
@@ -1506,26 +2492,75 @@ async function handleRpkDocsGeneration(options = {}) {
  * @param {Object} options - Summary options
  * @returns {string} Markdown formatted summary
  */
+/**
+ * Find description overrides that replace substantially longer source help.
+ * Curation is legitimate, but silent replacement is how stale or wrong
+ * content survives regeneration, so every regen PR lists what is hidden.
+ * @param {Object} tree - Raw command tree
+ * @param {Object} overridesData - Parsed overrides
+ * @returns {Array<{commandPath: string, overrideChars: number, sourceChars: number}>}
+ */
+function computeDescriptionCoverage(tree, overridesData) {
+  if (!tree || !overridesData?.commands) return []
+  const commandMap = flattenToMap(tree)
+  const results = []
+  for (const [cmdPath, override] of Object.entries(overridesData.commands)) {
+    if (typeof override?.description !== 'string') continue
+    const cmd = commandMap.get(cmdPath)
+    if (!cmd || typeof cmd.description !== 'string') continue
+    const sourceChars = cmd.description.trim().length
+    // appendToDescription content still reaches the page, so count it
+    const appended = typeof override.appendToDescription === 'string' ? override.appendToDescription.trim().length : 0
+    const overrideChars = override.description.trim().length + appended
+    if (sourceChars - overrideChars > 500) {
+      results.push({ commandPath: cmdPath, overrideChars, sourceChars })
+    }
+  }
+  return results.sort((a, b) => (b.sourceChars - b.overrideChars) - (a.sourceChars - a.overrideChars))
+}
+
 function generatePRSummary(options) {
   const {
     rpkVersion,
+    plugin,
+    pluginVersion,
     commandCount,
     filesGenerated,
     filesSkipped = 0,
     diffData,
     validationResult,
+    overrideValidation,
+    descriptionCoverage,
     outputDir
   } = options
 
   const lines = []
 
   // Header
-  lines.push('## rpk Documentation Generation Summary')
-  lines.push('')
+  if (plugin) {
+    lines.push(`## rpk ${plugin} Plugin Documentation Update`)
+    lines.push('')
+    if (pluginVersion) {
+      lines.push(`**Plugin version:** ${pluginVersion}`)
+    }
+    lines.push(`**Base rpk snapshot:** ${rpkVersion}`)
+    lines.push('')
+    lines.push(
+      `The \`rpk ${plugin}\` subtree was refreshed in the snapshot, then the ` +
+      'full rpk reference was re-rendered from it as a converge. Pages outside ' +
+      `\`rpk ${plugin}\` can carry template-level or consistency updates, and ` +
+      'stale generated files are cleaned up, so the change list may be wider ' +
+      'than the plugin itself.'
+    )
+    lines.push('')
+  } else {
+    lines.push('## rpk Documentation Generation Summary')
+    lines.push('')
 
-  // Version info
-  lines.push(`**Version:** ${rpkVersion}`)
-  lines.push('')
+    // Version info
+    lines.push(`**Version:** ${rpkVersion}`)
+    lines.push('')
+  }
 
   // Generation stats
   lines.push('### Generation Statistics')
@@ -1544,52 +2579,118 @@ function generatePRSummary(options) {
     lines.push('### Changes from Previous Version')
     lines.push('')
 
-    const { newCommands, removedCommands, newFlags, removedFlags, changedDescriptions } = diffData.summary
-
-    if (newCommands === 0 && removedCommands === 0 && newFlags === 0 && removedFlags === 0) {
-      lines.push('No command or flag changes detected.')
+    const {
+      newCommands,
+      removedCommands,
+      newFlags,
+      removedFlags,
+      changedDefaults = 0,
+      changedFlagTypes = 0,
+      changedFlagRequirements = 0,
+      changedFlagDescriptions = 0,
+      descriptionChanges = 0,
+      newlyDeprecatedCommands = 0
+    } = diffData.summary
+
+    const totalChanges = newCommands + removedCommands + newFlags + removedFlags +
+      changedDefaults + changedFlagTypes + changedFlagRequirements +
+      changedFlagDescriptions + descriptionChanges + newlyDeprecatedCommands
+
+    if (totalChanges === 0) {
+      lines.push('No command, flag, or default changes detected.')
     } else {
       lines.push(`| Change Type | Count |`)
       lines.push(`|-------------|-------|`)
       if (newCommands > 0) lines.push(`| New commands | ${newCommands} |`)
+      if (newlyDeprecatedCommands > 0) lines.push(`| Deprecated commands | ${newlyDeprecatedCommands} |`)
       if (removedCommands > 0) lines.push(`| Removed commands | ${removedCommands} |`)
       if (newFlags > 0) lines.push(`| New flags | ${newFlags} |`)
       if (removedFlags > 0) lines.push(`| Removed flags | ${removedFlags} |`)
-      if (changedDescriptions > 0) lines.push(`| Changed descriptions | ${changedDescriptions} |`)
+      if (changedDefaults > 0) lines.push(`| Changed flag defaults | ${changedDefaults} |`)
+      if (changedFlagTypes > 0) lines.push(`| Changed flag types | ${changedFlagTypes} |`)
+      if (changedFlagRequirements > 0) lines.push(`| Changed flag requirements | ${changedFlagRequirements} |`)
+      if (changedFlagDescriptions > 0) lines.push(`| Changed flag descriptions | ${changedFlagDescriptions} |`)
+      if (descriptionChanges > 0) lines.push(`| Changed command descriptions | ${descriptionChanges} |`)
+      if (diffData.summary?.flagDataBackfilled > 0) lines.push(`| Flag docs backfilled (not new flags) | ${diffData.summary.flagDataBackfilled} commands |`)
     }
     lines.push('')
 
-    // List new commands
-    if (diffData.details?.newCommands?.length > 0) {
+    // Collapsible list helper: itemized up to a cap, with an overflow note
+    const pushDetailsList = (title, items, renderItem) => {
+      if (!items || items.length === 0) return
       lines.push('<details>')
-      lines.push('<summary>New Commands</summary>')
+      lines.push(`<summary>${title}</summary>`)
       lines.push('')
-      for (const cmd of diffData.details.newCommands.slice(0, 20)) {
-        lines.push(`- \`${cmd.path}\``)
+      for (const item of items.slice(0, 30)) {
+        lines.push(renderItem(item))
       }
-      if (diffData.details.newCommands.length > 20) {
-        lines.push(`- ... and ${diffData.details.newCommands.length - 20} more`)
+      if (items.length > 30) {
+        lines.push(`- ... and ${items.length - 30} more (see the diff JSON in docs-data/)`)
       }
       lines.push('')
       lines.push('</details>')
       lines.push('')
     }
 
-    // List removed commands
-    if (diffData.details?.removedCommands?.length > 0) {
-      lines.push('<details>')
-      lines.push('<summary>Removed Commands</summary>')
-      lines.push('')
-      for (const cmd of diffData.details.removedCommands.slice(0, 20)) {
-        lines.push(`- \`${cmd.path}\``)
-      }
-      if (diffData.details.removedCommands.length > 20) {
-        lines.push(`- ... and ${diffData.details.removedCommands.length - 20} more`)
-      }
-      lines.push('')
-      lines.push('</details>')
-      lines.push('')
+    const formatValue = (value) => {
+      if (value === undefined) return 'unset'
+      if (value === null) return 'null'
+      if (typeof value === 'object') return JSON.stringify(value)
+      return String(value)
+    }
+
+    pushDetailsList('New Commands', diffData.details?.newCommands,
+      cmd => `- \`${cmd.path}\``)
+    pushDetailsList('Deprecated Commands', diffData.details?.newlyDeprecatedCommands,
+      cmd => `- \`${cmd.path}\`${cmd.message ? ` — ${cmd.message}` : ''}${cmd.hidden ? ' _(hidden from help output)_' : ''}`)
+    pushDetailsList('Removed Commands', diffData.details?.removedCommands,
+      cmd => `- \`${cmd.path}\``)
+    pushDetailsList('New Flags', diffData.details?.newFlags,
+      flag => `- \`${flag.commandPath}\`: \`--${flag.flagName}\` (${flag.type})`)
+    pushDetailsList('Removed Flags', diffData.details?.removedFlags,
+      flag => `- \`${flag.commandPath}\`: \`--${flag.flagName}\``)
+    pushDetailsList('Changed Flag Defaults', diffData.details?.changedDefaults,
+      change => `- \`${change.commandPath}\`: \`--${change.flagName}\` default \`${formatValue(change.oldDefault)}\` → \`${formatValue(change.newDefault)}\``)
+    pushDetailsList('Changed Flag Types', diffData.details?.changedFlagTypes,
+      change => `- \`${change.commandPath}\`: \`--${change.flagName}\` type \`${change.oldType}\` → \`${change.newType}\``)
+    pushDetailsList('Changed Flag Requirements', diffData.details?.changedFlagRequirements,
+      change => `- \`${change.commandPath}\`: \`--${change.flagName}\` required \`${change.oldRequired}\` → \`${change.newRequired}\``)
+    pushDetailsList('Changed Command Descriptions', diffData.details?.descriptionChanges,
+      change => `- \`${change.path}\``)
+  }
+
+  // Override validation: entries referencing commands the tree lacks do
+  // nothing silently, so surface them where they become actionable
+  if (overrideValidation && overrideValidation.errors && overrideValidation.errors.length > 0) {
+    lines.push('### Override Validation')
+    lines.push('')
+    lines.push(`⚠ ${overrideValidation.errors.length} override entr${overrideValidation.errors.length === 1 ? 'y' : 'ies'} did not apply (unknown command paths — stale entries in the overrides file):`)
+    lines.push('')
+    for (const err of overrideValidation.errors.slice(0, 10)) {
+      lines.push(`- ${typeof err === 'string' ? err : err.message || JSON.stringify(err)}`)
+    }
+    if (overrideValidation.errors.length > 10) {
+      lines.push(`- ... and ${overrideValidation.errors.length - 10} more`)
+    }
+    lines.push('')
+  }
+
+  // Description overrides that hide most of the source help. Curation is
+  // fine, but this is where stale content hides, so keep it reviewable.
+  if (descriptionCoverage && descriptionCoverage.length > 0) {
+    lines.push('### Curated descriptions replacing source help')
+    lines.push('')
+    lines.push('These overrides replace substantially longer help text from the rpk source. Confirm the curated version still carries every operational detail (or intentionally omits it):')
+    lines.push('')
+    lines.push('| Command | Override | Source help |')
+    lines.push('|---------|----------|-------------|')
+    for (const entry of descriptionCoverage.slice(0, 15)) {
+      lines.push(`| \`${entry.commandPath}\` | ${entry.overrideChars} chars | ${entry.sourceChars} chars |`)
+    }
+    if (descriptionCoverage.length > 15) {
+      lines.push(`| ... and ${descriptionCoverage.length - 15} more | | |`)
     }
+    lines.push('')
   }
 
   // Validation results
@@ -1686,6 +2787,23 @@ module.exports = {
   handleRpkDocsGeneration,
   fetchRpkTreeFromSource,
   fetchRpkTreeFromLinuxSource,
+  acquireRpkBinary,
+  buildRpkBinary,
+  downloadRpkRelease,
+  fetchPluginSubtree,
+  parseCobraFlags,
+  parseUrfaveFlags,
+  parseHelpFlags,
+  mergeVisibleDeprecationsIntoOverrides,
+  makeLinkablePredicate,
+  enrichPluginTreeWithFlags,
+  fetchLatestPluginVersion,
+  pluginNodeHasRealCommands,
+  splicePluginNode,
+  preserveLinuxOnlyCommands,
+  REFRESHABLE_PLUGINS,
+  PLUGIN_INSTALL_VERSION_FLAGS,
+  PLUGIN_MANIFEST_SLUGS,
   getRequiredGoVersion,
   prepareSourceFromRef,
   detectLinuxOnlyFromSource,
@@ -1701,6 +2819,9 @@ module.exports = {
   getPlatformDescription,
   getCurrentPlatform,
   updateOverridesWithIntroducedVersions,
+  filterDiffForWhatsNew,
+  computeDescriptionCoverage,
+  updateWhatsNewFile,
   KNOWN_PLUGINS,
   extractCommandPaths,
   detectLinuxOnlyByComparison,