Correct rpk ai usage across AI Gateway and MCP pages#12
Merged
Conversation
Updates ADP docs to match what rpk shipped in PRs #30273, #30327, and #30360. The pages were written ahead of the rpk-side merge and made several claims that don't match the actual command surface — most importantly that rpk ai owns auth and profile subtrees (it doesn't; in plugin mode both subtrees are suppressed and auth is owned by rpk cloud login). - Drop "rpk ai plugin" framing; treat rpk ai as a first-class command - Replace rpk ai auth/profile content with rpk cloud login + rpk profile use - Fix install command: rpk plugin install ai -> rpk ai install - Add Environment variables subsection on connect-agent (RPAI_TOKEN, RPAI_ENDPOINT, --rpai-endpoint, plugin-mode flag rename) - SDK examples now use OIDC client-credentials only; rpk ai is the data-access tool, not a token source for application code - Fix OAuth provider CLI example with verified flags (--auth-endpoint, --token-endpoint, --display-name); drop nonexistent --auth-config flag from MCP create - Add TODO(rpk-ai) markers for future verification (alias removal, auth/profile suppression, --auth-config future flag) Verified against cloudv2/apps/rpai/internal/cmd source on 2026-05-05. Co-Authored-By: Claude Opus 4.7 (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
commented
May 5, 2026
micheleRP
commented
May 5, 2026
micheleRP
commented
May 5, 2026
Style review caught a few items that needed fixing across the same set
of pages.
Newly introduced (fixed):
- Reword 7 sentences that started with the inline code `rpk ai`. Style
guide forbids starting sentences with code; moved the command
mid-sentence (e.g. "The `rpk ai` command honors..." or "Use `rpk ai`
for...").
Pre-existing (also fixed since the pages were already in the diff):
- connect-agent.adoc: "You'll construct" -> "You construct" (present
tense per style guide).
- connect-agent.adoc: drop bold from leading phrases in "Best practices"
bullets; bold is for UI elements, not emphasis.
- overview.adoc: "via Google AI Studio" -> "through Google AI Studio"
(terminology list bans `via`).
- create-server.adoc: rewrite "There is no hand-written form code per
type" as "No per-type hand-written form code is required" (style
guide bans "There is/are" constructions).
- oauth-providers.adoc: NOTE wording "should be able to bind" -> "need
to bind" (terminology list bans `should`).
- oauth-providers.adoc: shorten verbose H2 ("Manage external identity
providers for user-delegated MCP authentication" -> "Browse OAuth
providers") + add a clearer lead-in before the columns table.
- oauth-providers.adoc: remove trailing whitespace.
- test-tools.adoc: future tense "it will work" -> "it works".
- All 5 files: add module prefixes (`mcp:`, `ai-gateway:`) to bare
same-module xrefs per Antora conventions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Configure the managed flow section listed 5 deep-dive pages but the catalog has grown to 9 (Zendesk, Workday, Ironclad, and Ramp also have deep-dives now). Rather than duplicate the list, point readers at the catalog page, which is already organised by category and includes the deep-dive links inline next to each type's description. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Local build was emitting 16 xref-resolution errors across 6 pages plus one partial. None were caused by recent commits; they were stale references left over from the `cloud-docs:ai-agents` -> `redpanda-adp` component migration plus a few cross-component xrefs that lost their component prefix. Local-component fixes: - ai-agents:observability/concepts.adoc -> observability:concepts.adoc (transcripts.adoc, ingest-custom-traces.adoc, partial) - ai-agents:observability/transcripts.adoc -> observability:transcripts.adoc - ai-agents:agents/monitor-agents.adoc -> agents:monitor.adoc - governance:guardrails.adoc -> governance:guardrails/index.adoc (the page moved into a subdirectory) - integrations/index.adoc -> integrations:index.adoc (was bare; needed the same-component module prefix) - agent-trace-hierarchy / mcp-server-trace-hierarchy anchors renamed to ...-transcript-hierarchy to match the actual section headings on observability/concepts.adoc; link labels updated accordingly. Cross-component fixes (verified the targets exist): - manage:rpk/rpk-install.adoc -> redpanda-cloud:manage:rpk/rpk-install.adoc - develop:connect/components/inputs/otlp_*.adoc -> redpanda-connect:components:inputs/otlp_*.adoc Build verification: `npm run build` now reports 0 xref errors. The remaining warnings are pre-existing template-attribute placeholders (unrelated). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Updates ADP docs to match what rpk shipped in PRs #30273, #30327, and #30360. The pages were written ahead of the rpk-side merge and made several claims that don't match the actual command surface — most importantly that
rpk aiownsauthandprofilesubtrees (it doesn't: in plugin mode both subtrees are suppressed by design, and auth is owned byrpk cloud login).rpk aias a first-class command (mirrors how we describerpk connect).rpk ai auth login/rpk ai auth token/rpk ai profile create|usewith the actual flow (rpk cloud login+rpk profile use/rpk cloud cluster use); the AI Gateway URL is cached on the rpk cloud profile per #30327.rpk plugin install ai→rpk ai install.connect-agent.adocdocumentingRPAI_TOKEN,RPAI_ENDPOINT,--rpai-endpoint, and the plugin-mode flag rename.rpk aiis the data-access tool, not a token source for application code.--auth-endpoint,--token-endpoint,--display-name); drop the nonexistent--auth-configrow from MCP create.TODO(rpk-ai)markers for follow-ups (alias removal, auth/profile-suppression behavior,--auth-configflag if it lands later).Source-verified against
cloudv2/apps/rpai/internal/cmdon 2026-05-05.Preview pages
Test plan
npm run buildpasses locally (no new warnings introduced)--auth-configrow removed; CLI trailer)gen-rpkand confirm the auto-generated/reference/rpk/rpk-ai/pages land; update the xref pointers from these ADP pages.grep -rn \"TODO(rpk-ai)\" modules/matches the planned set (3 markers).🤖 Generated with Claude Code