fix(DOC-1675): document --overprovisioned flag and improve rpk redpanda start prose

[mfernest]

Summary

Resolves DOC-1675.

Adds documentation for --overprovisioned and tightens the prose in the manual-edit zone of rpk redpanda start.

This PR was originally opened by @mfernest, who is no longer with the team. @Feediver1 is taking it over to land the remaining work after @micheleRP's review.

What changed

• --overprovisioned is exposed in the dev-container bundled-flags list as an xref to rpk redpanda mode#development-mode, with a one-line inline gloss. The flag is a Seastar passthrough, not in rpk --help, so it does not belong in the auto-generated == Flags table; it would be dropped on the next rpk doc regeneration.
• Manual-zone prose (heading, lead paragraph, command lead-in, "After Redpanda starts" sentence) updated to active voice, sentence-case heading, and consistent capitalization.
• Auto-generated == Usage + == Flags zone is unchanged vs main. Earlier commits in this PR's history edited that zone; the final commit (5218dd5e) reverted those edits per @micheleRP's review, since regeneration would silently overwrite them.

Net change vs main is ~14 lines, all in the manual zone above the first auto-generated heading.

Review history

@micheleRP's 2026-03-24 review (CHANGES_REQUESTED) asked for:

• Restore the auto-gen flags table; don't manually edit it — done in 5218dd5e
• Document --overprovisioned via xref instead of a manual flag-table row — done in a3fe122f, refined in bf694d11 to anchor at #development-mode and add the inline gloss
• Style nit on the "modify cluster properties" sentence — applied

Earlier approvals from @kbatuigas and @r-vasquez predate the post-review restructure (commits 4–6). Re-requesting @micheleRP's review.

Preview pages

• rpk redpanda start — manual-zone prose, --overprovisioned xref + inline gloss
• rpk redpanda mode (xref target) — anchor reader lands on

Test plan

• Netlify preview renders without errors
• --overprovisioned link from rpk redpanda start lands on the Development mode section of rpk redpanda mode
• No regressions in the auto-generated flags table (no diff vs main)

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

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

📝 Walkthrough

Walkthrough

Documentation updates to the rpk redpanda start command reference page. Changes include grammar corrections, capitalization improvements, and phrasing refinements across multiple sections. A new --overprovisioned flag is added with its description, which disables thread affinity for fairer CPU distribution. Existing flag descriptions are reworded for clarity, including updates to --check, --tune, --config, and --set flags. The document maintains functional accuracy while improving readability and consistency.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

• r-vasquez
• micheleRP
• kbatuigas

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: adding documentation for the --overprovisioned flag and improving prose quality in the rpk redpanda start documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The PR description comprehensively addresses all required template sections with detailed context, clear change summary, preview links, and test plan.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/doc-1675-overprovisioned-flag

---

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 and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc (1)

101-102: Consider linking --overprovisioned to the mode reference for deeper context.

Optional docs polish: append an xref to the rpk redpanda mode page so readers can immediately see the full implications of this flag (for example, dev-mode side effects beyond CPU pinning).

✍️ Suggested doc tweak

-|--overprovisioned |- |Disables thread affinity (CPU pinning) to allow fairer CPU distribution among all processes. Do not use in production environments. Set automatically by `--mode dev-container`.
+|--overprovisioned |- |Disables thread affinity (CPU pinning) to allow fairer CPU distribution among all processes. Do not use in production environments. Set automatically by `--mode dev-container`. For details, see xref:reference:rpk/rpk-redpanda/rpk-redpanda-mode.adoc[].

Based on learnings, AsciiDoc links with empty brackets are preferred in this repository.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc` around
lines 101 - 102, Add an AsciiDoc cross-reference from the --overprovisioned
entry to the rpk redpanda mode reference so readers can jump to full mode
details: locate the table cell containing the --overprovisioned description and
append an xref to the "rpk redpanda mode" page using the repository-preferred
empty-bracket syntax; ensure the link text is not added (use the empty brackets
style) and that the xref points to the correct page ID/title for the rpk
redpanda mode documentation.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc`:
- Around line 101-102: Add an AsciiDoc cross-reference from the
--overprovisioned entry to the rpk redpanda mode reference so readers can jump
to full mode details: locate the table cell containing the --overprovisioned
description and append an xref to the "rpk redpanda mode" page using the
repository-preferred empty-bracket syntax; ensure the link text is not added
(use the empty brackets style) and that the xref points to the correct page
ID/title for the rpk redpanda mode documentation.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ff6ed3f0-19d6-4a2d-be58-b253220450ca

📥 Commits

Reviewing files that changed from the base of the PR and between 49e7aa6 and 7699ad9.

📒 Files selected for processing (1)

• modules/reference/pages/rpk/rpk-redpanda/rpk-redpanda-start.adoc

[mfernest]

@kbatuigas — this adds the missing --overprovisioned flag to the rpk redpanda start reference and cleans up some prose. Do you think this needs an SME review, or is it straightforward enough to approve as-is?

[micheleRP]

Review Summary

The core issue (DOC-1675)

DOC-1675 reports that --overprovisioned is mentioned but not described in the flags table. This PR manually adds it and improves prose throughout the page.

How rpk reference docs work

The flags table in this file (the == Usage and == Flags sections) is auto-generated by our doc-tools rpk automation:

1. gen-rpk-ascii.py starts Redpanda in Docker, runs rpk <command> -h recursively, and generates .adoc files
2. Output goes to autogenerated/<tag>/rpk/*.adoc
3. The generator deletes and recreates each file entirely — there is no override mechanism for rpk docs (unlike property-overrides.json for properties)
4. The generated files are then reviewed and copied into modules/reference/pages/rpk/

Impact on this PR

The file has two zones with different behavior:

Zone	What's there	Overwritten on regen?
Manual prose (lines 1–43: title, "Set up a mode" section)	Hand-written	No
Flags table (lines 45–154: == Usage + == Flags)	From rpk --help	Yes — completely

The --overprovisioned flag already exists in rpk --help, so regenerating rpk docs with npx doc-tools generate rpk-docs --tag <version> would automatically add it to the flags table — with the description from the binary.

The prose improvements to existing flag descriptions (--check, --tune, --timeout, --config, --config-opt) will also be reverted to whatever rpk --help outputs on the next regeneration.

Recommendation

Rather than manually editing the auto-generated flags table, the right approach for DOC-1675 is to regenerate the rpk docs from a Redpanda version that includes the --overprovisioned flag. This will:

• Add the missing --overprovisioned row automatically
• Keep the flags table in sync with the actual CLI help text
• Avoid the manual edits being silently overwritten later

The manual prose improvements (lines 8–43 — heading fix, intro rewrite, capitalization) are safe and won't be overwritten. Those changes are good and could be kept in a smaller PR if desired.

Style notes (minor)

The prose changes are well-written. Two small suggestions if they're kept:

• "Set automatically by --mode dev-container" → "Set automatically when using --mode dev-container" for more natural phrasing
• "After Redpanda starts, modify the cluster properties by running:" — consider "After Redpanda starts, you can modify cluster properties by running:" since reference pages describe capabilities, not instructions

[micheleRP]

@mfernest please see Claude's review

[Feediver1]

@micheleRP — taking this over from @mfernest (no longer with the team). All three items from your 2026-03-24 review are addressed:

1. Auto-gen flags table restored to main's state in 5218dd5e — no manual edits remain in the == Usage / == Flags zone.
2. --overprovisioned via xref, not a manual row — a3fe122f removed the row; bf694d11 (just now) refines the xref to anchor on #development-mode and adds a one-line inline gloss so the bundled-flags bullet is self-describing.
3. Style nit on "modify cluster properties" — applied.

Net diff vs main is ~14 lines, all in the manual zone above the auto-generated headings. Re-requesting your review when you have a minute. If the inline gloss feels redundant given the xref already lands on the explanation, happy to drop it back to a bare xref.

[micheleRP]

thanks, yes: I think that first overprovisioned link is unnecessary, but looks good!