feat(rpk-docs): refresh a single plugin's docs with --plugin

[JakeSCahill]

Summary

rpk plugins release on their own cadence, independent of rpk itself: connect ships ~weekly from redpanda-data/connect, rpk ai several times a week from cloudv2's adp/v* tags, rpk k8s per operator release, and rpk check from redpanda-data/redpanda-check. Their docs currently refresh only when a Redpanda release triggers a full rpk regeneration.

This adds a --plugin mode so a single plugin's docs can be regenerated on the plugin's own release schedule:

doc-tools generate rpk-docs --plugin connect --plugin-version 4.102.0 --from-json docs-data/rpk-v26.1.12.json

How it works (splice-and-rerender)

1. Acquire an rpk binary matching the snapshot's rpk_version — official release download for published tags, build-from-source fallback for RC snapshots (RC releases are drafts, so their assets are not publicly downloadable). --rpk-bin skips both for local runs.
2. Install only the target plugin in an isolated HOME (pinned via the plugin's version flag when --plugin-version is given), run rpk --print-tree, and extract the plugin's top-level node.
3. Reapply platform markers from the snapshot's recorded linux_only_commands, splice the node into the snapshot (replace-only), record the version in plugin_versions, and save.
4. Re-render the full tree with normal --from-json semantics. Only the plugin's pages change in git, and stale-file cleanup, the nav rebuild, and override validation all see a complete tree.

Also fixed along the way

• plugin_versions plumbing (snapshot field → page context → "introduced in {plugin} version X" template) existed end-to-end but was never populated. --plugin records the refreshed version, the from-source path now records manifest versions for plugins that actually installed, and --from-json passes recorded versions through instead of hardcoding {}.
• rpk's install version validation caps each version segment at two digits (^v?\d{1,2}\.\d{1,2}\.\d{1,2} in pkg/cli/connect/install.go), so pins like connect 4.102.0 are rejected. The installer falls back to latest and records the manifest-resolved version. Upstream bug worth filing against rpk.

Validation (against real docs snapshots)

• --plugin connect on main's rpk-v26.1.12.json: only the snapshot, nav, and rpk-connect/ pages change; platform markers preserved; second run changes only generated_at.
• --plugin k8s --plugin-version 26.2.1-beta.3 on beta's rpk-v26.2.1-rc2.json: exercises the source-build fallback and the pre-GA pin, and restores the 5 rpk k8s multicluster pages that the rc2 regen deleted (redpanda-data/docs#1831).
• --plugin k8s against main's snapshot: clean skip with exit 0 (no k8s command in rpk 26.1).
• 298 jest tests pass, including new coverage for the splice and shim-detection logic.

Consumer side: redpanda-data/docs gains an update-rpk-plugin-docs workflow that calls this mode, with senders in each plugin's release workflow.

Test it locally

Everything runs against the real committed snapshots in the docs repo — no Docker, no Redpanda build. You need Node 20+, this branch, and a checkout of redpanda-data/docs on main.

# 1. This branch
git clone https://github.com/redpanda-data/docs-extensions-and-macros
cd docs-extensions-and-macros
git checkout feat/rpk-plugin-docs
npm install
DOC_TOOLS=$PWD/bin/doc-tools.js

# 2. From a clean docs-repo checkout (main):
cd /path/to/docs

A. Release diff → What's-new + PR summary (the change-detection overhaul, ~1 min):

node $DOC_TOOLS generate rpk-docs \
  --from-json docs-data/rpk-v26.2.1-rc2.json \
  --diff v26.1.12 \
  --update-whats-new \
  --summary-file /tmp/pr-summary.md

Then look at:

• The console diff report: Deprecated commands: 1 — rpk redpanda admin with the rpk cluster migration message (the old pipeline reported these as 12 removals).
• /tmp/pr-summary.md: the change table now includes changed flag defaults / descriptions, each with itemized lists.
• git diff modules/get-started/pages/release-notes/redpanda.adoc: a // AUTOGEN-RPK-CHANGES … START/END block appended inside the existing hand-written == Redpanda CLI (rpk) section, which is left untouched. Re-run the command — the block is replaced, not duplicated.

B. Single-plugin refresh (the --plugin mode, ~1–2 min, downloads a released rpk binary + the plugin):

git checkout -- . && git clean -fd modules docs-data
node $DOC_TOOLS generate rpk-docs \
  --plugin ai \
  --from-json docs-data/rpk-v26.2.1-rc2.json \
  --update-whats-new

Use the newest snapshot on the branch (what the workflow auto-selects). Running against an older snapshot regenerates pages for an rpk line the branch has moved past. Expect one-time modifications across all rpk pages on the first 5.3.0 run (the :description:-in-tag template change), Preserving rpk-check/ … rpk-k8s/ log lines (shim-only plugins in the rc2 snapshot are protected, not deleted), and exactly two deletions: the stale rpk-ai-llm.adoc/rpk-ai-mcp-create.adoc partials that redpanda-data/docs#1849 also removes.

Then look at:

• git status: only the snapshot, rpk-ai partials, nav, overrides, and the release-notes page change — nothing else.
• The snapshot's plugin_versions now records the installed ai version, and new plugin commands got introducedInVersion stamped with the plugin version in docs-data/rpk-overrides.json.
• The release-notes page gained a == rpk plugins section with an === ai plugin <version> block (plain command names, no xrefs — ai renders as partials).

C. Unit tests: npm test in this repo (797 tests; the rpk-docs suites are npx jest __tests__/tools/rpk-docs/).

Reset the docs repo with git checkout -- . && git clean -fd modules docs-data when done.

Related Jira

• DOC-2355 (rp-connect-docs#132): users asked for a reference listing the Connect CLI's commands, arguments, and options. The plugin flag extraction here (cobra + urfave/cli parsers) makes those options documentable for the first time, and the rpk-plugin-stubs reconciler can publish the reference on the RPCN site via page-family single-source stubs (workflows drafted, pending the RPCN team's placement decision).
• DOC-1090: groundwork for the deprecations redesign — rpk command deprecations are now detected automatically from source, reported in What's-new and PR summaries with migration messages, and page deprecation banners are auto-annotated in overrides.

Related PRs (rpk docs automation train)

PR	Role	Depends on
#225	Generator: --plugin mode, change detection, deprecations, What's-new merge, flag extraction, stub reconciler (publishes doc-tools 5.3.0)	—
redpanda-data/docs#1834	Receiver workflow for plugin-release dispatches	#225
redpanda-data/docs#1844	Release workflow: auto What's-new diff base + pre-GA plugin pins	#225
redpanda-data/docs#1849	Removes two stale rpk ai partials	merge before #1852/adp-docs#165 activate
redpanda-data/docs#1852	Sender: docs main → adp-docs stub sync dispatch	#225, adp-docs#165
redpanda-data/adp-docs#165	Receiver: reconciles rpk ai stubs and nav	#225, docs#1852
Senders (merged/open)	redpanda-data/connect#4636, redpanda-operator#1703 (merged), redpanda-check#10, cloudv2#28552	docs#1834

Merge order: #225 → dependency bumps on docs main and beta → #1834 + #1844 (+ #1849) → #1852 + adp-docs#165 → remaining senders. Jira: DOC-2355, DOC-1090.

[netlify]

✅ Deploy Preview for docs-extensions-and-macros ready!

Name	Link
🔨 Latest commit	610e2d9
🔍 Latest deploy log	https://app.netlify.com/projects/docs-extensions-and-macros/deploys/6a6c79d759e3f80008f4466b
😎 Deploy Preview	https://deploy-preview-225--docs-extensions-and-macros.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 97085774-bcc4-4f02-a5bd-d85923ab30ac

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds plugin-scoped rpk documentation refreshes from committed snapshots. The handler can acquire or build an rpk binary, install a selected plugin, extract and splice its command subtree, track plugin versions, update snapshots, and generate plugin-specific summaries. The CLI exposes plugin, version, and binary-path options and validates snapshot usage. Tests cover subtree detection, replacement, immutability, errors, and plugin mappings. The package version is updated to 5.3.0.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant handleRpkDocsGeneration
  participant acquireRpkBinary
  participant fetchPluginSubtree
  participant Snapshot
  CLI->>handleRpkDocsGeneration: provide plugin refresh options
  handleRpkDocsGeneration->>acquireRpkBinary: acquire or build rpk
  handleRpkDocsGeneration->>fetchPluginSubtree: install plugin and extract commands
  fetchPluginSubtree-->>handleRpkDocsGeneration: refreshed subtree and version
  handleRpkDocsGeneration->>Snapshot: splice subtree and save versioned JSON
  handleRpkDocsGeneration-->>CLI: return plugin diff and summary

Loading

Possibly related PRs

• redpanda-data/docs-extensions-and-macros#203: Both changes extend plugin handling in the rpk documentation generation workflow.

Suggested reviewers: feediver1

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly names the main change: adding --plugin support to refresh a single rpk plugin's docs.
Description check	✅ Passed	The description directly explains the new single-plugin docs refresh mode and its implementation details.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/rpk-plugin-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (4)

__tests__/tools/rpk-docs/plugin-refresh.test.js (2)

81-85: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Assert the exact plugin-to-flag mapping.

The regex confirms only flag-shaped values; it would still pass if every plugin used the wrong flag. Assert the expected mapping explicitly: ai: --ai-version, check: --check-version, connect: --connect-version, and k8s: --plugin-version.

Proposed test adjustment

-      for (const plugin of REFRESHABLE_PLUGINS) {
-        expect(PLUGIN_INSTALL_VERSION_FLAGS[plugin]).toMatch(/^--[a-z-]+$/)
-      }
+      expect(PLUGIN_INSTALL_VERSION_FLAGS).toEqual({
+        ai: '--ai-version',
+        check: '--check-version',
+        connect: '--connect-version',
+        k8s: '--plugin-version'
+      })

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@__tests__/tools/rpk-docs/plugin-refresh.test.js` around lines 81 - 85, Update
the “every refreshable plugin has a version pin flag” test to assert the exact
PLUGIN_INSTALL_VERSION_FLAGS mapping for ai, check, connect, and k8s:
--ai-version, --check-version, --connect-version, and --plugin-version
respectively, while preserving the existing coverage that each refreshable
plugin has a flag.

---

69-73: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert complete input immutability.

This test checks only one nested field. Capture the full tree before calling splicePluginNode and compare the entire input afterward so mutations to sibling nodes, arrays, or top-level fields cannot pass unnoticed.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@__tests__/tools/rpk-docs/plugin-refresh.test.js` around lines 69 - 73, Update
the “does not mutate the input tree” test around splicePluginNode to deep-clone
or otherwise snapshot the complete baseTree before invocation, then assert the
entire tree is unchanged afterward. Replace the single nested description check
while preserving the existing splicePluginNode inputs and behavior under test.

tools/rpk-docs/rpk-docs-handler.js (2)

1290-1302: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Isolated HOME (and the binary work dir) is never cleaned up.

tmpHome holds a full plugin install (connect is hundreds of MB) and, like workDir in acquireRpkBinary, is left behind after every run. A try/finally with fs.rmSync(tmpHome, { recursive: true, force: true }) around the install + --print-tree would keep repeated CI runs from accumulating temp state.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tools/rpk-docs/rpk-docs-handler.js` around lines 1290 - 1302, Update
fetchPluginSubtree to wrap the plugin installation and --print-tree workflow in
a try/finally, removing tmpHome with fs.rmSync(tmpHome, { recursive: true,
force: true }) in the finally block. Also ensure the binary work directory
managed by acquireRpkBinary is cleaned up through the same guaranteed cleanup
path.

---

1553-1567: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Snapshot is overwritten before rendering succeeds.

saveVersionedJson runs ahead of generateRpkDocs, so a rendering failure leaves the committed snapshot advanced to the new plugin version while the generated pages still reflect the old subtree. Moving this write to after a successful generateRpkDocs keeps snapshot and docs in step.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tools/rpk-docs/rpk-docs-handler.js` around lines 1553 - 1567, Move the
saveVersionedJson call in the plugin refresh flow to after generateRpkDocs
completes successfully. Keep the jsonData updates for the enhanced tree and
plugin_versions associated with the refreshed snapshot, but only persist them
once rendering succeeds so failed generation does not advance the committed
baseline.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tools/rpk-docs/rpk-docs-handler.js`:
- Around line 1507-1514: Update the snapshot-saving logic for augmentatedData to
persist tree.linux_only_commands alongside raw_tree/tree, plugin_versions, and
deprecated_commands. Ensure from-json inputs restore this field so
addPlatformMarkersFromSource in the refreshed subtree path retains Linux-only
platform markers.

---

Nitpick comments:
In `@__tests__/tools/rpk-docs/plugin-refresh.test.js`:
- Around line 81-85: Update the “every refreshable plugin has a version pin
flag” test to assert the exact PLUGIN_INSTALL_VERSION_FLAGS mapping for ai,
check, connect, and k8s: --ai-version, --check-version, --connect-version, and
--plugin-version respectively, while preserving the existing coverage that each
refreshable plugin has a flag.
- Around line 69-73: Update the “does not mutate the input tree” test around
splicePluginNode to deep-clone or otherwise snapshot the complete baseTree
before invocation, then assert the entire tree is unchanged afterward. Replace
the single nested description check while preserving the existing
splicePluginNode inputs and behavior under test.

In `@tools/rpk-docs/rpk-docs-handler.js`:
- Around line 1290-1302: Update fetchPluginSubtree to wrap the plugin
installation and --print-tree workflow in a try/finally, removing tmpHome with
fs.rmSync(tmpHome, { recursive: true, force: true }) in the finally block. Also
ensure the binary work directory managed by acquireRpkBinary is cleaned up
through the same guaranteed cleanup path.
- Around line 1553-1567: Move the saveVersionedJson call in the plugin refresh
flow to after generateRpkDocs completes successfully. Keep the jsonData updates
for the enhanced tree and plugin_versions associated with the refreshed
snapshot, but only persist them once rendering succeeds so failed generation
does not advance the committed baseline.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dd2c6f1e-a0cb-439e-a616-6c9847aa9419

📥 Commits

Reviewing files that changed from the base of the PR and between 4ee4074 and ab3f102.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (5)

• CLI_REFERENCE.adoc
• __tests__/tools/rpk-docs/plugin-refresh.test.js
• bin/doc-tools.js
• package.json
• tools/rpk-docs/rpk-docs-handler.js

[JakeSCahill]

Added introduced-in stamping (cd21b9c): new commands found during a --plugin refresh now get introducedInVersion set to the plugin's version, so pages render "This command was introduced in <plugin> version X." The full-regen path is fixed the same way — plugin-subtree commands were previously stamped with the rpk version, which would have rendered a Redpanda version masquerading as a plugin version now that pluginName is populated.

Verified against main's real snapshot: an ai refresh stamped 30 new commands with 0.2.31 and the rendered partials carry the note. Existing introducedInVersion values are never overwritten.

One granularity caveat: the diff baseline is the previous snapshot state, not per-release history — if several plugin releases pass between doc regenerations, a command is stamped with the version at which the docs first captured it. Once the release-triggered senders are live, that converges to one-release accuracy.

[JakeSCahill]

Three more commits landed from the change-detection review (af8a754, d09c554, 2fba250):

Phase 1 — reporting correctness: the PR summary read a nonexistent summary field (changedDescriptions), never rendered flag default changes, and reported 'no changes' when only defaults or descriptions changed. Flag type/required/description changes were computed by the differ and discarded. All categories now render with itemized collapsible lists, and the console report labels removals as removals instead of deprecations.

Phase 2 — real deprecation detection: deprecated_commands was write-only. The differ now diffs the deprecation maps between snapshots, reclassifies hidden-deprecated subtree removals as deprecations (rolled up into one entry per family with subcommands listed), and renders them in the console report, What's-new, and PR summaries. Visible deprecated commands are auto-annotated in the overrides so pages get deprecation banners.

Phase 3 — mergeable What's-new: the one-shot == Redpanda CLI guard is replaced with version-scoped AUTOGEN-RPK-CHANGES marker blocks: same-version re-runs replace their own block, later versions (successive RCs, plugin releases) append inside the existing section, and hand-written prose is never touched. Plugin refreshes now write plugin-labeled What's-new blocks. Entries link only to commands that render as pages (rpk ai partials no longer get broken xrefs) and use first-line descriptions.

All phases verified end-to-end against the real v26.1.12→v26.2.1 diff and the real release-notes page: the rpk redpanda admin family reports as one deprecation with the rpk cluster migration message (previously 12 fake removals), a real default change (rpk container start --console-image) surfaces, and the hand-written 26.2 CLI section accumulates v26.2.1 and ai-plugin blocks without being clobbered. 322 tests.

[micheleRP]

Reviewed and tested locally: full suite passes on this branch (804/804, incl. the 329 rpk-docs tests), and I reproduced both "Test it locally" scenarios against a clean docs main checkout — the deprecation roll-up (1 deprecation for rpk redpanda admin with 11 subcommands, vs 12 phantom removals before), the itemized default changes, the marker-block What's-new merge (idempotent on re-run, hand-written content untouched), and the --plugin ai refresh (isolated HOME, checksum-verified binary download, plugin_versions recorded, platform markers preserved). The splice-and-rerender design is solid. Two issues in the generated What's-new output, one suggestion:

1. Broken xrefs for command-group roots. commandPathToXref('rpk check') returns rpk-check.adoc, but command groups render to rpk-check/rpk-check.adoc (verified: the top-level file doesn't exist). The v26.2.1 GA What's-new will publish broken xrefs for the rpk check and rpk k8s roots. Since the tree is in hand at render time, 2-part commands with children can be routed to <dashified>/<dashified>.adoc.

2. makeLinkablePredicate misses the cloudSecretDir routing. It checks the overrides-based routing (shouldExcludeCommand/shouldUsePartialDir) but not the hardcoded rpk cloud/rpk security secret → partials path in generate-rpk-docs.js. Result (verified in my Test A run): the What's-new contains xref:reference:rpk/rpk-cloud/rpk-cloud-auth-list.adoc and friends — pages that don't exist in this repo (that content is single-sourced into cloud-docs stubs). Cloud-routed commands need to be treated as non-linkable too.

3. (Suggestion) Sentence-boundary capping for What's-new bullets. The first-line-only description logic cuts wrapped cobra help mid-sentence on the published release-notes page, e.g. rpk ai llm-provider diff — "Prints, per manifest, whether apply would" and rpk ai policy create — "the allow/deny gate that". Capping at a sentence boundary (the shortDescription/capToTwoSentences helpers already exist) would read much better.

One CodeRabbit triage note: its "persist linux_only_commands when saving the snapshot" finding is a false positive — the field is persisted on raw_tree itself (103 entries in the committed 26.1.12 snapshot, including the rpk ai commands), and my --plugin ai test preserved all page-platforms markers.

Heads-up that also affects the consumers: the command.hbs :description: change means the first regeneration with 5.3.0 touches every rpk page (~370 files in my runs) — see my comment on redpanda-data/docs#1834 about expectations for the first automated PR.

[JakeSCahill]

Ran a full ground-truth review of the generated output: production generation of v26.2.1 (diff v26.1.12) on a pristine docs clone, compared against --help dumps for all 348 commands from the same rpk binary and plugin installs, using an independent checker rather than the generator's own parsers. Also parsed all 364 generated files with Asciidoctor and built the full Antora site.

Fixes pushed from what the review found (98a1e65..a1c0da8):

• Dangling example fragments: upstream help strings ending mid-example rendered as "for example,." Now stripped, and stray spaces before closing parens are cleaned.
• Duplicate rendered headings now warn at generation time (the one real case, rpk container status, is an overrides bug fixed in redpanda-data/docs#1860).
• The nav rebuild dropped the root rpk.adoc entry, which made Antora report the page as unlisted. The nav now round-trips byte-identical to main.
• What's-new summaries no longer glue a periodless summary line to the paragraph after it.
• Baseline gap guard: the v26.1.12 snapshot predates plugin flag extraction, so every extracted ai/connect flag (208 of them) was labeled 'New in ' even for long-standing flags. Flag additions in a plugin group whose baseline has no flag data are now reported as documentation backfill, not new flags. Verified against the real snapshots: exactly the 23 genuine core flag additions survive, zero plugin mislabels, zero core misfires.
• from-json --diff runs now stamp introducedInVersion before rendering, so a single run produces labeled pages (previously labels appeared only on the next regeneration).
• Unindented $ command examples with sample output (rpk cluster brokers decommission-status) and colon-introduced code samples (Cedar policies on rpk ai policy create) are now captured as verbatim code blocks instead of being mangled into prose with injected backticks and fake headings. Column-aligned definition layouts still go to the table converter. Summaries strip captured blocks. textTransformations rules gain an opt-in applyToCode flag so the rpai→rpk ai rewrite reaches command examples while admonition rules never touch verbatim content.

Final state: 856 tests green, 0 critical findings from the mechanical checker, 364/364 files parse clean under Asciidoctor, full Antora build has zero errors or warnings attributable to the generated content, and the What's-new block was independently verified faithful to the snapshot diff (53/53 new commands, 23/23 new flags, all xrefs resolve).

The review also surfaced pre-existing content issues in hand-maintained docs (not from this PR): redpanda-data/docs#1860 and redpanda-data/docs#1861 fix the unambiguous ones.

[JakeSCahill]

Follow-up commits from completing the content-review fixes (338ba80):

• The examples pipeline now transforms content line by line, so caption-oriented rules can never rewrite quoted strings inside example commands (a rule was corrupting '{"quotas":...}' to '{quotas:...}'). Rules flagged applyToCode still reach command lines.
• Structured example captions use ensurePeriod instead of an unconditional trailing period (was rendering "brokers 1 and 2..").
• New PR-summary section, "Curated descriptions replacing source help": lists every description override that replaces substantially longer source help (counting appendToDescription). This is the guard against silent curated-content drift. On current docs main it flagged the ~30 stale overrides now fixed in redpanda-data/docs#1862, and after that PR it lists only the six intentionally curated commands.

860 tests green. The full content-restoration companion is redpanda-data/docs#1862.

[JakeSCahill]

@micheleRP thanks — all three landed in the commits since your review:

1. Group-root xrefs: generateWhatsNewSection now routes two-part commands that have subcommands to <group>/<group>.adoc via a hasSubcommands predicate built from the live tree (report-delta.js:584-593). Independently verified during the full ground-truth review: all 61 xrefs in the generated v26.2.1 What's-new block resolve, including the rpk check and rpk k8s roots.

2. Cloud-routed commands unlinkable: makeLinkablePredicate carries the hardcoded rpk cloud / rpk security secret partials routing (rpk-docs-handler.js:1071-1073). In the verified block, rpk cloud auth list and rpk security secret list render as plain code, no xref.

3. Sentence-boundary capping: firstSentence now joins the hard-wrapped lines of the first paragraph before cutting at a sentence terminator (and cuts at the paragraph break when a cobra summary line has no period). Your two examples verbatim: rpk ai llm-provider diff renders "Prints, per manifest, whether apply would create, update, or delete the resource, without applying it." and rpk ai policy create renders the full sentence through "...may call a tool." Unit tests cover both shapes.

Since your review the branch also picked up the ground-truth review fixes (861+ tests now): flag-description truncation at wrapped -- continuations, the nav root-page drop, the plugin-flag "New in" mislabeling guard, verbatim capture of help code samples, and the curated-description coverage report. The summary comment from 2026-07-31 on this PR lists them with the verification state. Heads-up ack: the ~370-file first-regeneration churn expectation is noted in redpanda-data/docs#1834 and the re-dispatch plan folds #226/#229 in first so there is only one churn wave.

[micheleRP]

Re-tested after your updates. Both blocking items are fixed, verified against real output rather than by reading the diff. Approving, with one follow-up below that is not a blocker.

Truncation: the dash guard is gone, replaced with an indentation comparison against the recorded flag column, and parseUrfaveFlags got the same treatment. The grep that returned 20 truncated rows yesterday now returns 0, and the rows that lost meaning read completely, with the flag tokens backticked:

--enabled ... (true when set; pass `--enabled=false` to disable).
--bedrock-config.region ... (alias: `--region`).
--bedrock-config.assume-role.role-arn ... (alias: `--role-arn`).

Duplicate Flags: solved by letting a curated override win with a warning, which I did not expect but works. rpk connect run renders 1 == Flags section, no page in the tree has more than one, and the warning fires clearly on a connect refresh naming the 13 skipped flags.

Also fixed: the PR summary now carries an ### Override Validation section reporting the 4 stale override paths, so they reach a reviewer instead of scrolling past in the log. The override-vs-source-help comparison table is a nice addition.

Tests are up from 361/836 to 387/862, all green. I re-parsed all 344 regenerated files with Asciidoctor: clean, no unterminated blocks.

Follow-up, not blocking: the container fallback cannot work on macOS

The new fallback builds in a container and then runs the binary on the host:

Native build failed (Go version mismatch: installed 1.24.4, required >= 1.26.4); building in a container...
Installing plugin: rpk ai install
Error: Failed to install plugin 'ai':
no output

docker run ... golang:<ver> go build -o /out/rpk produces a Linux binary (I confirmed the image reports GOOS=linux GOARCH=arm64) which is then executed on a Darwin arm64 host, so it cannot run and the plugin install reports no output. CI is unaffected, since a Linux runner with setup-go at stable satisfies the go.mod floor and would use the native build anyway. But the comment says old local Go is "common on laptops", and on macOS laptops this path fails, so it does not deliver what it is there for. It is also a less useful failure than before: the old behavior was a clear actionable Go-version error, this prints no output twice with the underlying exec error swallowed.

Two ways out: pass -e GOOS=darwin -e GOARCH=arm64 so the container cross-compiles for the host, or keep the binary in the container and exec into it for the plugin install and tree dump, the way fetchRpkTreeFromLinuxSource already does on the --ref path. Either way, surfacing the real exec error would help.

--rpk-bin remains a clean workaround, and it is what I used for all the plugin-refresh testing here.

Two docs-repo follow-ups, not changes to this PR

• With the curated override winning, rpk connect run publishes 7 flags and skips 13, so --secrets, --redpanda-license, --disable-telemetry, --telemetry-deployment-type, --telemetry-tenant-id, and --rpc-plugins stay undocumented. Dropping that Flags override from docs-data/rpk-overrides.json adopts the extracted table, which is now the more complete one.
• Of the 4 stale override paths the new report surfaces, rpk ai llm and rpk ai llm check are dead now that redpanda-data/docs#1849 merged, so they can go.