docs: clean up stale rpk command overrides

[micheleRP]

Summary

Cleanup of docs-data/rpk-overrides.json. Four entries pointed at command paths that no longer exist, so they silently did nothing and surfaced as validation errors on every generator run. One more override duplicated content the generator already produces, giving a page two conflicting Flags tables.

Override validation now reports zero errors, down from four.

Stale command paths

Entry	Action	Why
rpk ai llm check	Migrated to rpk ai llm-provider check	Renamed command. The curated wording ("the configured LLM provider") is clearer than the source's "the upstream"
rpk ai llm	Deleted	The provider-type list was already stale, missing openai-compatible, and is the kind of enumeration that drifts
rpk cluster storage restore-start	Deleted	Now rpk cluster storage restore start. The source description is more complete, covering --wait/-w, --cluster-uuid-override, and a link to the whole-cluster-restore docs. The page already carries an alias from the old name
rpk connect studio sync-schema	Deleted	rpk connect studio is gone from the command tree, with no equivalent and no pages in this repo

Duplicate Flags table

rpk connect run carried both a supported flags: map and a legacy content section hardcoding a full Flags table, so the page rendered two == Flags sections with conflicting content. The hardcoded table was also stale: --secrets, --redpanda-license, --disable-telemetry, --telemetry-deployment-type, --telemetry-tenant-id, and --rpc-plugins were missing from the published page.

Its curated descriptions moved into the flags: map, so the page keeps the polished wording and picks up the six missing flags. This also restores Usage ahead of Flags, since the removed section was positioned after_description.

Verification

Ran the generator against the committed v26.2.1-rc2 snapshot with a live plugin binary for flag extraction:

• rpk connect run: one == Flags section with 13 rows (was 7), all descriptions sentence-capitalized, curated wording intact for log.level, set, and resources, Usage back ahead of Flags
• rpk ai llm-provider check renders the migrated description
• rpk cluster storage restore start renders the fuller source description
• Override validation: zero errors, previously four unknown command paths
• All regenerated files parse cleanly under Asciidoctor

Note on scope

An earlier revision of this PR also fixed the duplicate == Example heading on rpk container status. That change is covered by #1860, which makes the identical override edit and additionally fixes the rendered page, so it has been dropped here to avoid a conflict. This PR no longer touches that override.

No .adoc files change in this PR, so there is nothing to preview. The generated pages update the next time the rpk docs automation runs.

[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

Run ID: f3ba64ea-d21b-4585-bd46-d74d81b77ea3

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

Updated docs-data/rpk-overrides.json. The rpk connect run override now documents the chilled, watcher, env-file, and templates flags directly. The rpk ai llm check override is renamed to rpk ai llm-provider check. Obsolete overrides for rpk ai llm, rpk cluster storage restore-start, and rpk connect studio sync-schema were removed.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• redpanda-data/docs#1733: Both PRs modify docs-data/rpk-overrides.json.
• redpanda-data/docs#1858: Both PRs update overrides for the rpk ai llm to rpk ai llm-provider rename.

Suggested reviewers: kbatuigas

🚥 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 and concisely describes the cleanup of stale rpk command overrides.
Description check	✅ Passed	The description thoroughly explains the changes, validation, and scope, but omits the template's Jira ticket, review deadline, and Checks section.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch michele/rpk-overrides-cleanup

---

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

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	e152257
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a6ee8f095ceae0008aa4dd6
😎 Deploy Preview	https://deploy-preview-1865--redpanda-docs-preview.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]

Actionable comments posted: 1

🤖 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 `@docs-data/rpk-overrides.json`:
- Around line 1089-1102: Restore the generated Usage section in the
rpk-connect-run documentation generation flow, preserving it while removing the
hand-written Flags table. Regenerate the downstream page and ensure the
generated == Usage section appears between the description and == Flags.

🪄 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

Run ID: c2d14521-1eb9-4129-8a66-dd14bd6440d9

📥 Commits

Reviewing files that changed from the base of the PR and between 4cd493e and bb7bec9.

📒 Files selected for processing (1)

• docs-data/rpk-overrides.json

[JakeSCahill]

This supersedes two of my open cleanups, reconciled as follows:

• docs: drop the hand-written rpk connect run flags table #1859 closed in favor of this — your version is strictly better (it keeps per-flag description overrides for four flags mine dropped).
• docs: migrate stale rpk ai llm overrides to the renamed command #1858 overlap, one content difference: this PR deletes rpk ai llm's appendToDescription outright, but that note ("Supported provider types: openai, anthropic, google, bedrock") is real content that belongs on the renamed command. docs: migrate stale rpk ai llm overrides to the renamed command #1858 migrates it to rpk ai llm-provider and adds openai-compatible (verified against the current plugin help). Two options: cherry-pick that one hunk into this PR and I close docs: migrate stale rpk ai llm overrides to the renamed command #1858 too, or merge this as-is and docs: migrate stale rpk ai llm overrides to the renamed command #1858 rebases down to just the migration hunk. Happy either way — say the word and I'll push the hunk here.

[JakeSCahill]

Reviewed with ground-truth checks against the committed snapshot, the binary help, and the open regen PRs. The cleanup itself is right — every removal checks out — but there is one sequencing hazard worth deciding deliberately, plus two coordination notes.

Verified correct

• rpk ai llm deletion: your drift argument holds and I withdrew my migration suggestion — the provider-type enumeration now lives in the source help itself (rpk ai llm-provider's description says "Supported provider types: openai, anthropic, google, bedrock" and create's description names the config groups including openai-compatible), so extraction delivers it without any override. Closing my #1858 in favor of this. One upstream nit worth passing to ADP: the parent command's list omits openai-compatible while create's includes it — their drift now, not ours.
• rpk ai llm check → llm-provider check migration: correct, and agreed the curated wording is clearer.
• restore-start and studio sync-schema deletions: both paths verified gone from the tree. One question: does rpk cluster storage restore start's own help cover the --wait polling behavior the deleted text described? If not, that sentence may be worth carrying to the new path.

Sequencing hazard: the connect run Flags drop

Dropping the curated Flags section is the right end state (the extracted table has 18 flags vs the curated 7), but no committed snapshot carries extracted connect flags yet: rpk-v26.2.1-rc2.json has zero flags on rpk connect run (extraction shipped in 5.3.0, after that snapshot), and #1845 was generated pre-extraction. If this merges before a 5.3.x regeneration lands, any interim regen from the current snapshot renders rpk connect run with no flag documentation at all — and once #1863's overrides-change re-render workflow merges, this PR's own merge would trigger exactly that regen. Suggestion: hold this until the v26.2.1 re-dispatch PR (which will carry the extracted flags) merges, or land the two together.

Coordination notes

1. The rpk container status hunk is byte-identical to #1860's — convergent fixes, which is reassuring. #1860 additionally fixes the currently published page (this PR leaves the double heading live until regen) and carries the applyToCode transformation rule the next regen needs. Identical hunks merge cleanly in either order, but consider dropping the hunk here and letting #1860 own it, so the change has one home.
2. The four new per-flag descriptions restate the binary help that extraction will supply — which is the same drift pattern this cleanup removes elsewhere. If the intent is phrasing control, keeping them is fine (they're consistent with the existing log.level/set/resources precedent); if not, dropping them lets extraction own those descriptions, including the (default: false) notes the help carries and these replacements drop.

[JakeSCahill]

Rebased onto main post-#1868 (clean, all four cleanups intact) per your follow-up note. Sequencing reminder from my review still applies to the connect run Flags drop: no committed snapshot carries extracted connect flags yet, so ideally this merges with or after the next full regeneration.

[micheleRP]

Sequencing requirement found while testing this against the rest of the queue, on my own PR. It does not change the diff, but it does change when this can safely merge.

Removing the hand-written Flags table here is correct: #225 made the extracted table authoritative, and the hand-written one was stale (7 flags against the command's 13, missing --secrets, --redpanda-license, --disable-telemetry, the two telemetry flags, and --rpc-plugins). What I missed is that the hand-written table was also doing a second job as an unconditional fallback.

The committed snapshot has rpk connect run with 0 flags, because connect flag data only exists via live extraction. So a --from-json regeneration with this merged renders the page with no Flags section at all, not a stale one. Verified with the published 5.3.1 against main plus this PR, #1838, and #1860:

Flags sections: 0, rows: 0

That matters because #1863 re-renders from the committed snapshot on any overrides change, so merging this while that workflow is live would strip the table via an auto-PR.

The fix is ordering, not a code change. Once an extraction run persists connect flags into the snapshot, from-json is safe:

--plugin connect --rpk-bin   ->  snapshot connect run flags: 13
then --from-json             ->  Flags sections: 1, rows: 13

So this should merge after the v26.2.1 re-dispatch, and the check before merging is that committed docs-data/rpk-v26.2.1-rc2.json has 13 flags on rpk connect run. I have written up the same requirement on #1863, and suggested a generator warning on a nonzero-to-zero flag-count transition so this class is caught in future rather than discovered on a page.

Merge order for the four PRs touching this file, all pairwise-tested: #1838, #1860, and this are mutually clean in any order; only #1862 conflicts, with both #1838 and this, in either direction, so it wants rebasing last.

[micheleRP]

The sequencing requirement above has been independently re-verified in a fresh pass and holds. One correction to the check as I originally wrote it: #1863 resolves the newest snapshot (tilde-normalized sort), so after the v26.2.1 re-dispatch the file to verify is the new rpk-v26.2.1.json once the re-dispatch auto-PR merges — not the rc2 file, and not merely after the dispatch fires. Once whichever snapshot that sort selects shows 13 flags on rpk connect run, this PR is safe to merge in any order relative to #1838 and #1860 (all three are mutually clean; only #1862 needs a rebase afterwards).

[JakeSCahill]

Approving: my earlier review verified every removal against ground truth, and the sequencing hazard I flagged (connect run's Flags table vanishing on a from-json rerender) is now handled by your merge-order plan — this merges after the re-dispatch auto-PR lands the extracted connect flags in the snapshot, and before #1863. Your two refinements (gate on the auto-PR merging, and the newest-snapshot sort selecting rpk-v26.2.1.json post-re-dispatch) are exactly right.