Host-platform container builds and unsatisfiable env-gating validation

[JakeSCahill]

Three non-blocking review findings from the 5.3.0 train review by @micheleRP, fixed with tests:

1. macOS container fallback built an unrunnable binary. acquireRpkBinary's Go-too-old fallback built inside golang:<ver> with the container's implicit GOOS=linux, and the darwin host then executed a linux binary — plugin installs died with no output. The container build now cross-compiles for the host platform (GOOS/GOARCH from process.platform/process.arch, CGO_ENABLED=0 — rpk is CGO-free). Linux CI is unaffected. --rpk-bin remains the offline escape hatch.

2. cloudOnly + selfHostedOnly on the same command or flag silently deleted the row from every build. The pair emits ifdef::env-cloud wrapped in ifndef::env-cloud, which no build satisfies. validate-overrides.js now reports it as an error at both command and flag level (feat(rpk-docs): gate subcommand table rows by cloud availability #229 review suggestion).

3. rpk ai no longer reaches the Self-Managed What's new on any path (follow-up on redpanda-data/docs#1844). The plugin-release receiver already excluded ai from --update-whats-new because rpk ai's docs home is adp-docs, but full regenerations still wrote the whole tree into the block — against the rc2 snapshot the result was dominated by rpk ai rename churn (21 new + 21 removed bullets). The generator now owns the rule: filterDiffForWhatsNew drops the rpk ai subtree from every category on both full-generation paths, and a --plugin ai refresh skips the What's-new write with a log line. Diff reports and PR summaries keep the full picture. Verified against the real v26.2.1-rc2 snapshot: zero rpk ai mentions, 42 Self-Managed bullets remain, rpk check/rpk k8s intact.

Full suite 904/904 green. No version bump: merged before #228 so its 5.3.1 publish carries all three, in place before the v26.2.1 re-dispatch (the run that would have carried the polluted What's-new block).

Related PRs (rpk docs automation train)

Follow-ups to #225, #229, and redpanda-data/docs#1844.

[coderabbitai]

Warning

Review limit reached

@JakeSCahill, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 38 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 9555f45a-bde2-47c0-94e1-c870399937d8

📥 Commits

Reviewing files that changed from the base of the PR and between 38cdb10 and 97a9063.

📒 Files selected for processing (4)

• __tests__/tools/rpk-docs/validate-overrides.test.js
• __tests__/tools/rpk-docs/whats-new-merge.test.js
• tools/rpk-docs/rpk-docs-handler.js
• tools/rpk-docs/validate-overrides.js

---

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.}

[netlify]

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

Name	Link
🔨 Latest commit	97a9063
🔍 Latest deploy log	https://app.netlify.com/projects/docs-extensions-and-macros/deploys/6a6cc14e9303130008d72ebd
😎 Deploy Preview	https://deploy-preview-238--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.

[micheleRP]

Both findings are correctly fixed and I verified each by running it rather than reading the diff. Approving, with two coordination notes.

Verification

Fix	Result
Container fallback	The exact scenario that failed on my machine yesterday now succeeds: Native build failed (Go version mismatch: installed 1.24.4, required >= 1.26.4); building in a container... then Installing plugin: rpk ai install, Extracted flags for 52 command(s), Spliced fresh 'ai' subtree (version 0.2.32), exit 0
GOARCH mapping	Correct, and easy to get wrong: process.arch === 'arm64' ? 'arm64' : 'amd64' maps x64 to amd64 instead of passing Node's name straight through
Mutual exclusion	Both levels caught, with precise contexts: commands["rpk cluster health"] and commands["rpk topic analyze"].flags.batches
What's-new filter	Zero rpk ai entries in the published block, block down from 113 lines to 59, and the now-empty Removed commands section is dropped rather than rendered empty
Filter completeness	Covers all 10 detail keys report-delta.js actually produces, so nothing under-filters
Reviewer visibility	The PR summary still shows the full picture (48 new and 21 removed commands). Only the published page is filtered, which matches the comment's stated intent
Tests	904 passing, up from 862. CI 16 green, 0 failures

Suggestions

1. The body describes two changes but this ships three. The What's-new exclusion is the most user-visible change here, since it alters what reaches the Self-Managed release notes, and a reviewer going by the body would not know to look for it. Worth describing so the behavior change is on the record.

2. Merge sequencing against #228. With #225, #226, and #229 merged, main is at 5.3.0. This PR has no bump and rides #228's 5.3.1, so if #228 merges first these fixes sit in main unpublished until some later bump. Either merge this before #228 or give it its own bump.

3. A Windows host silently gets a Linux binary. process.platform === 'darwin' ? 'darwin' : 'linux' maps win32 to linux, which reproduces the original bug class. Minor, since the toolchain is macOS and Linux, but throwing for unsupported platforms would be clearer than a wrong default.

4. Contradictory overrides are reported but still ship. Validation errors are non-fatal, so that run still emits the unsatisfiable row and it vanishes from both builds, which is the thing the error warns about. Consistent with the existing design, and #225's Override Validation section now surfaces it in the generated PR body, so this is probably fine as-is. Flagging only so the choice is deliberate.

Adjacent, not this PR

• rpk container status renders two == Example headings (lines 32 and 37 of the generated page). Its override contributes a curated Example section at position: end while the generator emits one as well. Same collision class as rpk connect run's Flags, but the curated-section-wins logic from #225 is scoped to titles matching Flags, so Example only trips the duplicate-heading warning. Either a rpk-overrides.json fix in the docs repo or a generalization of that rule, whichever you prefer.
• The run still reports the 4 stale override paths. redpanda-data/docs#1865 removes those.

What works well

• The cross-compile fix is the right shape, and CGO_ENABLED=0 with the note that rpk is CGO-free is the detail that makes it safe.
• Linux CI is genuinely unaffected: a Linux host still resolves to GOOS=linux, so it is a no-op there.
• The plugin path also skips What's-new for excluded subtrees, so the two entry points now agree instead of contradicting each other.
• filterDiffForWhatsNew returns a copy, and the test asserts the input is untouched, so diff reports and PR summaries keep full fidelity while only the published block is filtered.
• The rpk aim case in the tests is exactly the edge a prefix filter gets wrong.

[JakeSCahill]

Thanks for the run-it-first verification — all four suggestions actioned or answered:

1. Body: you were right, and the cause is instructive — my earlier gh pr edit silently failed on a GraphQL projectCards deprecation error, so the body never got the third change. Re-applied via the REST API before merging; the What's-new exclusion is now on the record in the description.
2. Sequencing: merged this before fix(property-extractor): resolve member calls on inline constants in defaults #228, so 5.3.1 carries all three fixes.
3. win32: Reject unsupported host platforms in the container build fallback #239 adds the throw-for-unsupported-platforms guard with --rpk-bin named in the error — also bump-less and intended to land before fix(property-extractor): resolve member calls on inline constants in defaults #228.
4. Non-fatal validation: deliberate, confirming your read — overrides validation stays advisory so a stale entry never blocks a release regen, and the unsatisfiable-pair error now rides the Override Validation section of every generated PR body where a human decides. If it recurs in practice we can promote it to fatal.

Adjacent items:

• rpk container status double Example: already fixed in redpanda-data/docs#1860 (override merged into a single section plus the same fix applied to the published page) — that PR just needs a review. Generalizing curated-section-wins beyond Flags felt riskier than fixing the one data bug, and the duplicate-heading warning now catches any future instance of the class at generation time.
• docs#1865: thanks — one overlap to reconcile: my docs#1858 covers the two rpk ai llm paths of the four, and it migrates the curated appendToDescription content to rpk ai llm-provider rather than deleting it. I'll reconcile the two on the docs side so we keep the content migration and your other two cleanups.