docs(rpk-ai): add 34 beta rpk-ai command pages (under beta badge) + nav#110
docs(rpk-ai): add 34 beta rpk-ai command pages (under beta badge) + nav#110Feediver1 wants to merge 1 commit 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 |
3 participants
Why
The rpk-ai reference documented 40 commands, but the current
rpaiplugin exposes 34 more. Per the ADP writer, these are beta and should appear in the docs under the beta badge (same as the existing rpk-ai pages). Target page family: https://docs.redpanda.com/agentic-data-plane/reference/rpk/rpk-ai/rpk-ai/New commands added:
agent:a2a(+card,send,task+cancel/get/watch),apply,create,credential(+create/delete/list),delete,diff,get,start,stop,transcript(+get/list),updatellm checkoauth-client:dcr(+get,update,iat+list/mint/revoke),revoke-tokensrun(+claude,codex)What
modules/reference/pages/rpk/rpk-ai/, generated by the current rpk-docs generator (rpkdev+aiplugin viarpk --print-tree). Each carries:page-beta: trueso it renders with the beta badge, consistent with the existing rpk-ai pages.modules/ROOT/nav.adocfrom the authoritative command tree — 74 entries with correct nesting, including hyphenated command names (oauth-client) and deep paths (oauth-client dcr iat mint).Verification
{vbar}) — no "dropping cells" table errors (consistent with fix(rpk-ai): escape pipes in --format flag tables (fix 'dropping cells' table errors) #109).nav.adoc: 126 → 160 lines (+34).🤖 Generated with Claude Code