docs(rpk-ai): regenerate rpk ai reference against stable plugin v0.2.17#110
docs(rpk-ai): regenerate rpk ai reference against stable plugin v0.2.17#110Feediver1 wants to merge 3 commits into
Conversation
The rpk-ai reference covered 40 commands; the current rpai plugin exposes 34
more (agent a2a/apply/create/credential/delete/diff/get/start/stop/transcript/
update, llm check, oauth-client dcr + dcr iat, oauth-client revoke-tokens,
run claude/codex). Per the ADP writer these are beta and should be documented
under the beta badge.
- Add the 34 pages, generated from the current rpk-docs generator (rpk dev +
ai plugin via `--print-tree`), each carrying `:page-beta: true` so they
render with the beta badge like the existing rpk-ai pages.
- Rebuild the rpk-ai nav block in modules/ROOT/nav.adoc from the authoritative
command tree (74 entries, correct nesting incl. hyphenated commands like
`oauth-client` and deep paths like `oauth-client dcr iat mint`).
Verified: every nav entry maps to a page and every page has a nav entry;
no orphans/missing; pipe-bearing flag enums are escaped (`{vbar}`).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for redpanda-agentic-data-plane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
making sure this doesn't merge as is
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
The command set here is real and the nav nesting is correct, but there's a generation problem affecting all 34 pages, so I'd hold this rather than merge as-is.
1. Global flags are wrong on every page. The pages show rpk core's root flags (--config, -X/--config-opt, --ignore-profile, --profile, -v/--verbose) and have no per-command flags section. The real rpai plugin commands take the plugin's own flags — -o/--format (env RPAI_FORMAT), --no-color, -c/--rpai-config, -s/--rpai-endpoint, -p/--rpai-profile, --token — as the existing pages show (e.g. rpk-ai-agent-list.adoc). They were built from the rpk dev branch via --print-tree without the plugin's per-command flags, so each page fell back to rpk's root global_flags.
2. Structural divergence from the existing 40. Existing pages use == Flags (bold headers) with no single-source/Linux-note/autogenerated scaffolding; these use == Global flags (plain headers) plus that scaffolding — old-generator vs new-generator output. Mixing them makes the reference inconsistent.
3. Parent pages weren't regenerated. rpk-ai-agent.adoc, rpk-ai-oauth-client.adoc, rpk-ai-llm.adoc, and rpk-ai.adoc have no Subcommands tables, so they don't list the new children.
4. Examples render broken on the a2a pages (comment lines split into empty code blocks, some commands sit outside any block, # comments render literally).
Root cause: these commands (a2a, run claude/codex, dcr, oauth-client revoke-tokens, the agent tree) aren't in the released plugin (v0.1.10) — only on dev. The generator installs the released plugin, so it can't produce these correctly until a plugin release (≥ v0.1.11) ships them and help renders rpk ai instead of rpai (tracked in cloudv2#26990).
Automation context — redpanda-data/docs#1733 (@JakeSCahill). That PR wires the shared rpk-docs generator + override system into the docs repo, and it deliberately excludes rpk ai as "coming soon." adp-docs has no equivalent workflow or rpk-overrides.json yet, so this subtree is fully hand-maintained here. The durable fix isn't hand-adding 34 pages — it's generating the rpk-ai subtree through that same tool once the plugin release lands, with the PR #85-style customizations (rpai→rpk ai, dropping "coming soon") living in an rpk-overrides.json rather than by hand.
Suggestion: hold until the plugin release, and coordinate with @JakeSCahill on standing up an rpk-ai-scoped generation path for adp-docs (mirroring #1733 but scoped to rpk ai instead of excluding it). Separately, publishing these as beta pre-release is a product/maturity call — can the ADP writer confirm that's intended before we ship them?
|
please do not merge yet. there are some upcoming breaking changes for profile management. i think it will be ready by mo/tu next week |
|
changes are merged |
|
@birdayz — following up on the breaking changes you flagged here. Status for the record: we're holding this regen until the When you get a chance: any rough idea when the next stable |
Full regeneration of the rpk ai command family from plugin-mode --help output (rpk v26.1.12 container, rpai plugin v0.2.17): - 94 pages total: adds auth (login/logout/status/token), env (add/delete/list/rename/show/use), run (claude/codex), apply/diff subcommands on every resource group, llm check, and the full agent a2a/credential/transcript trees - oauth renamed to oauth-provider (upstream rename); old page names kept as page-aliases so existing links redirect - nav.adoc rpk ai block regenerated to match the new tree - cli:index.adoc command table updated for oauth-provider - profile command is gone from the top level (replaced by env), matching the prose docs from PR #112 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
micheleRP
changed the title
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
@Feediver1 this has the new automation so we can merge this now!
3 participants
Why
The rpk-ai reference documented the command set of plugin v0.1.10 (40 pages), but the CLI has moved on. The regen was held until the
profiletoenvrename (cloudv2 #27510) shipped in a stable plugin release; that landed, and stable v0.2.17 is now the source of truth. Target page family: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/What
Full regeneration of the family against plugin v0.2.17 in plugin mode (rpk v26.1.12 container +
rpk ai install), replacing the earlier dev-branch generation on this PR that captured the wrong flags:auth(login/logout/status/token),env(add/delete/list/rename/show/use),run(claude/codex), the fullagenttree (a2a+card/send/task,apply,credential,diff,transcript, and friends),llm check,oauth-client dcr+revoke-tokens, andapply/diffon every resource group.oauthrenamed tooauth-provider(upstream rename;oauthremains a CLI alias). The six old page names are kept aspage-aliasesso existing links redirect.profileis gone from the top level, replaced byenv, matching the prose docs from docs: add Use the ADP CLI section with GitOps how-to #112.--rpai-config,--rpai-profile, and so on), with{vbar}escaping and therpk aiusage convention from docs: rpk ai reference cleanup for beta (remove "coming soon", rpai -> rpk ai) #85.cli:index.adoccommand table updated foroauth-provider.Verification
mainexcept genuine v0.2.17 help-text changes (verified withdiffon unchanged commands, for examplellm create).rpk-ai-oauth*URLs redirect via the aliases.connectionpages still read "coming soon" because v0.2.17 genuinely ships them that way.Preview pages
🤖 Generated with Claude Code