Add rpk reference pages for rpk ai and rpk cloud commands

modules/ROOT/nav.adoc

@@ -3,6 +3,7 @@
 ** xref:get-started:byoc-prereqs.adoc[Prerequisites]
 ** xref:get-started:byoc-quickstart.adoc[Quickstart]
 ** xref:get-started:first-agent.adoc[Build your first agent]
+** xref:get-started:rpk-install.adoc[Install or update rpk]
 ** xref:get-started:invite-team.adoc[Invite your team]
 * xref:agents:index.adoc[Agents]
 ** xref:agents:overview.adoc[Overview]
@@ -80,6 +81,17 @@
 ** xref:integrations:copilot.adoc[GitHub Copilot]
 ** xref:integrations:remote-mcp-clients.adoc[Remote MCP clients (Claude Desktop, ChatGPT, Gemini)]
 * xref:reference:index.adoc[Reference]
-** xref:reference:glossary.adoc[Glossary]
 ** xref:reference:api.adoc[API reference]
-** xref:reference:pipeline-examples.adoc[Pipeline examples]
+** xref:reference:rpk/index.adoc[rpk Commands]
+*** xref:reference:rpk/rpk-ai/rpk-ai.adoc[rpk ai]
+**** xref:reference:rpk/rpk-ai/rpk-ai-install.adoc[]
+**** xref:reference:rpk/rpk-ai/rpk-ai-upgrade.adoc[]
+**** xref:reference:rpk/rpk-ai/rpk-ai-uninstall.adoc[]
+*** xref:reference:rpk/rpk-cloud/rpk-cloud.adoc[rpk cloud]
+**** xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[]
+**** xref:reference:rpk/rpk-cloud/rpk-cloud-logout.adoc[]
+**** xref:reference:rpk/rpk-cloud/rpk-cloud-cluster.adoc[]
+***** xref:reference:rpk/rpk-cloud/rpk-cloud-cluster-select.adoc[]
+*** xref:reference:rpk/rpk-profile/rpk-profile.adoc[rpk profile]
+*** xref:reference:rpk/rpk-x-options.adoc[rpk -X]
+* xref:reference:glossary.adoc[Glossary]

modules/agents/pages/byoa-register.adoc

@@ -3,7 +3,7 @@
 :page-topic-type: how-to
 :personas: agent_developer, platform_admin
 :learning-objective-1: Distinguish a BYOA (Bring Your Own Agent) from a Redpanda-managed agent and decide when each fits
-:learning-objective-2: Identify the A2A endpoint contract a BYOA agent must expose (well-known agent card and the `/.well-known/agent-card.json` discovery URL)
+:learning-objective-2: pass:q[Identify the A2A endpoint contract a BYOA agent must expose (well-known agent card and the `/.well-known/agent-card.json` discovery URL)]
 :learning-objective-3: Identify the service-account auth model BYOA agents use to authenticate inbound calls and emit telemetry
 
 // TODO: this page describes BYOA registration as a model. The BYOA variant of `AgentCreate.agent_type` is not yet defined in the public proto (`AgentRegistryService.CreateAgent` itself is in place), and there is no UI surface yet. Re-anchor on the BYOA-arm proto definition (`SelfManagedAgentInput` or equivalent) once it lands in `proto/public/cloud/redpanda/api/adp/v1alpha1/agent.proto`. Add the click-by-click steps and CLI examples once the surface exists. Confirm with team-ai before drafting the step-by-step flow.

modules/agents/pages/tutorials/transaction-dispute-resolution.adoc

@@ -34,7 +34,7 @@ When a customer calls saying "I see a $247.83 charge from 'ACME CORP' but I neve
 
 * A xref:redpanda-cloud:get-started:cluster-types/byoc/index.adoc[BYOC cluster].
 * xref:ai-gateway:gateway-quickstart.adoc[AI Gateway configured] with at least one LLM provider enabled (this tutorial uses OpenAI GPT-5.2 or Claude Sonnet 4.5 for reasoning).
-* The xref:redpanda-cloud:manage:rpk/rpk-install.adoc[Redpanda CLI (`rpk`)] installed (for testing the pipeline with sample data).
+* The xref:get-started:rpk-install.adoc[Redpanda CLI (`rpk`)] installed (for testing the pipeline with sample data).
 * Completed xref:tutorials/customer-support-agent.adoc[] (foundational multi-tool concepts).
 
 == Create MCP tools for each domain

modules/ai-gateway/pages/connect-agent.adoc

@@ -4,10 +4,10 @@
 :personas: app_developer
 :page-aliases: redpanda-cloud:ai-agents:ai-gateway/builders/connect-your-agent.adoc
 :learning-objective-1: Construct the proxy URL for an LLM provider you have configured
-:learning-objective-2: Authenticate to AI Gateway with `rpk` for local development or with OIDC client credentials for CI and programmatic clients
+:learning-objective-2: pass:q[Authenticate to AI Gateway with `rpk` for local development or with OIDC client credentials for CI and programmatic clients]
 :learning-objective-3: Send requests through the proxy URL with the SDK of your choice
 
-This guide shows how to connect your glossterm:AI agent[] or application to AI Gateway. You construct the proxy URL for a provider you have already created, authenticate (with `rpk cloud login` for local development or with OIDC client credentials for CI and application code), and send your first request with the SDK of your choice.
+This guide shows how to connect your glossterm:AI agent[] or application to AI Gateway. You construct the proxy URL for a provider you have already created, authenticate (with xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[`rpk cloud login`] for local development or with OIDC client credentials for CI and application code), and send your first request with the SDK of your choice.
 
 After completing this guide, you will be able to:
 
@@ -46,16 +46,16 @@ TIP: The provider detail page generates ready-to-run snippets pre-filled with th
 [[authenticate-with-rpai]]
 == Use `rpk ai` for local development
 
-The `rpk ai` command is the Redpanda AI CLI. Use it to manage AI Gateway resources (LLM providers, MCP servers, OAuth providers) and call MCP tools from the command line. Authentication for `rpk ai` is owned by `rpk cloud login`. The active AI Gateway URL comes from your active rpk cloud profile.
+The xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] command is the Redpanda AI CLI. Use it to manage AI Gateway resources (LLM providers, MCP servers, OAuth providers) and call MCP tools from the command line. Authentication for `rpk ai` is owned by `rpk cloud login`. The active AI Gateway URL comes from your active rpk cloud profile.
 
-. Install `rpk ai`:
+. xref:reference:rpk/rpk-ai/rpk-ai-install.adoc[Install `rpk ai`]:
 +
 [source,bash]
 ----
 rpk ai install
 ----
 +
-Update later with `rpk ai upgrade`; remove with `rpk ai uninstall`.
+Update later with xref:reference:rpk/rpk-ai/rpk-ai-upgrade.adoc[`rpk ai upgrade`]; remove with xref:reference:rpk/rpk-ai/rpk-ai-uninstall.adoc[`rpk ai uninstall`].
 
 . Log in to Redpanda Cloud:
 +
@@ -66,14 +66,16 @@ rpk cloud login
 +
 This caches a cloud token in `~/.config/rpk/rpk.yaml`. On every invocation, `rpk ai` reads the cached token automatically.
 
-. Select a profile that points at a cluster with AI Gateway v2 attached. The AI Gateway URL is cached on the profile when you create it.
+. Select a xref:reference:rpk/rpk-profile/rpk-profile.adoc[profile] that points at a cluster with AI Gateway v2 attached. The AI Gateway URL is cached on the profile when you create it.
 +
 [source,bash]
 ----
 rpk profile use <profile-name>
 # or, to switch the cluster the active profile points at:
 rpk cloud cluster use <cluster-id>
 ----
++
+See xref:reference:rpk/rpk-cloud/rpk-cloud-cluster.adoc[`rpk cloud cluster`] for switching the active cluster.
 
 . Verify the connection:
 +

modules/ai-gateway/pages/overview.adoc

@@ -46,7 +46,7 @@ Use the provider's own SDK: OpenAI, Anthropic, Google AI, AWS Bedrock, or any Op
 
 === Managed authentication
 
-Applications authenticate to ADP with OIDC service accounts instead of long-lived provider API keys. Service accounts use the same role and audit model as every other ADP resource, and mint short-lived tokens that are easy to revoke. For local command-line workflows, use `rpk cloud login` to authenticate and `rpk ai` to talk to the gateway. CI and programmatic clients use the OIDC client-credentials grant directly. See xref:ai-gateway:connect-agent.adoc[Connect your agent].
+Applications authenticate to ADP with OIDC service accounts instead of long-lived provider API keys. Service accounts use the same role and audit model as every other ADP resource, and mint short-lived tokens that are easy to revoke. For local command-line workflows, use xref:reference:rpk/rpk-cloud/rpk-cloud-login.adoc[`rpk cloud login`] to authenticate and xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] to talk to the gateway. CI and programmatic clients use the OIDC client-credentials grant directly. See xref:ai-gateway:connect-agent.adoc[Connect your agent].
 
 === Per-provider observability
 

modules/get-started/pages/rpk-install.adoc

@@ -0,0 +1,5 @@
+= Install or Update rpk
+:description: pass:q[Install or update `rpk` to interact with Redpanda from the command line.]
+:env-cloud:
+
+include::ROOT:get-started:rpk-install.adoc[tag=single-source]

modules/mcp/pages/create-server.adoc

@@ -138,7 +138,7 @@ A populated tools list confirms that the connection works and credentials resolv
 
 == Create from the CLI
 
-Use `rpk ai` for a non-UI path through the same create flow, useful for scripting and CI.
+Use xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] for a non-UI path through the same create flow, useful for scripting and CI.
 
 [source,bash]
 ----

modules/mcp/pages/managed/metabase.adoc

@@ -3,7 +3,7 @@
 :page-topic-type: how-to
 :personas: app_developer, platform_admin
 :learning-objective-1: Configure the Metabase managed MCP server with a v0.49+ API key bound to the right Metabase group
-:learning-objective-2: Identify when to use semantic-layer tools (`search`, `get_metric`, `query`) versus the native-SQL escape hatches (`run_native_query`, `run_card`)
+:learning-objective-2: pass:q[Identify when to use semantic-layer tools (`search`, `get_metric`, `query`) versus the native-SQL escape hatches (`run_native_query`, `run_card`)]
 :learning-objective-3: Run a metric-first analysis against your Metabase instance from the Inspector or an agent
 
 The *Metabase* managed MCP server lets agents read and query a Metabase analytics instance. The tool surface is a hybrid of Metabase's semantic-layer primitives (tables, metrics, fields, dimensions) and SQL-first escape hatches (native queries and saved questions), wrapping the Metabase REST API with a long-lived API key.

modules/mcp/pages/oauth-providers.adoc

@@ -173,7 +173,7 @@ The provider appears in the *OAuth providers* list.
 
 == Register from the CLI
 
-Use `rpk ai` to script provider registration:
+Use xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] to script provider registration:
 
 // TODO(rpk-ai): aliases (oauth-provider, mcp-server, llm-provider) are kept for one release per cloudv2/apps/rpai/CLAUDE.md. Verified canonical command is `rpk ai oauth create` on 2026-05-05; flip examples cleanly to canonical names if the alias gets dropped.
 

modules/mcp/pages/test-tools.adoc

@@ -103,7 +103,7 @@ The Session panel keeps a running history of every call you've made through the
 
 == Test from the CLI
 
-Use `rpk ai` for the same tool calls outside the UI, when scripting smoke tests or running checks from CI.
+Use xref:reference:rpk/rpk-ai/rpk-ai.adoc[`rpk ai`] for the same tool calls outside the UI, when scripting smoke tests or running checks from CI.
 
 [source,bash]
 ----

modules/observability/pages/ingest-custom-traces.adoc

@@ -1,7 +1,7 @@
 = Ingest OpenTelemetry Traces from Custom Agents
 :description: Configure a Redpanda Connect pipeline to ingest OpenTelemetry traces from custom agents into Redpanda's immutable log for unified governance and observability.
 :page-topic-type: how-to
-:learning-objective-1: Configure and deploy a Redpanda Connect pipeline to receive OpenTelemetry traces from custom agents via HTTP and publish them to `redpanda.otel_traces`
+:learning-objective-1: pass:q[Configure and deploy a Redpanda Connect pipeline to receive OpenTelemetry traces from custom agents via HTTP and publish them to `redpanda.otel_traces`]
 :learning-objective-2: Validate trace data format and compatibility with existing MCP server traces
 :learning-objective-3: Secure the ingestion endpoint using authentication mechanisms
 
@@ -19,7 +19,7 @@ After reading this page, you will be able to:
 
 * A Redpanda Connect pipeline host (today: a Redpanda BYOC cluster with Connect enabled). Ability to manage secrets on that host.
 // TODO: Replace with the standalone-ADP ingestion target once defined (may no longer require a Redpanda Cloud cluster).
-* The latest version of xref:redpanda-cloud:manage:rpk/rpk-install.adoc[`rpk`] installed
+* The latest version of xref:get-started:rpk-install.adoc[`rpk`] installed
 * Custom agent or application instrumented with OpenTelemetry SDK
 * Basic understanding of the https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/[OpenTelemetry span format^] and https://opentelemetry.io/docs/specs/otlp/[OpenTelemetry Protocol (OTLP)^]
 

modules/reference/pages/rpk/index.adoc

@@ -0,0 +1,9 @@
+= rpk Commands
+:description: Reference for the `rpk` commands used to manage the Redpanda Agentic Data Plane from the command line.
+:page-layout: index
+
+This section documents the `rpk` commands you use to manage the Redpanda Agentic Data Plane (ADP) from the command line.
+
+Use `rpk ai` to manage AI Gateway resources (LLM providers, MCP servers, OAuth providers) and call MCP tools directly from your terminal. Authentication is owned by `rpk cloud login`. The `rpk ai` commands reuse your active `rpk profile` and the cached cloud token. The active AI Gateway URL is resolved from the same profile unless you override it with `--rpai-endpoint`.
+
+For subcommands available after install (`rpk ai llm`, `rpk ai mcp`, `rpk ai oauth`, and more), run `rpk ai <command> --help` from your terminal.

modules/reference/pages/rpk/rpk-ai/rpk-ai-install.adoc

@@ -0,0 +1,39 @@
+= rpk ai install
+
+Install the Redpanda AI CLI.
+
+This command installs the latest version by default.
+
+Alternatively, you may specify an `rpk ai` version using the `--ai-version` flag.
+
+You may force the installation using the `--force` flag.
+
+== Usage
+
+[,bash]
+----
+rpk ai install [flags]
+----
+
+== Flags
+
+[cols="1m,1a,2a"]
+|===
+|*Value* |*Type* |*Description*
+
+|--ai-version |string |Redpanda AI CLI version to install (e.g. 0.1.2) (default "latest").
+
+|--force |- |Force install of the Redpanda AI CLI.
+
+|-h, --help |- |Help for install.
+
+|--config |string |Redpanda or rpk config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`.
+
+|-X, --config-opt |stringArray |Override rpk configuration settings; '-X help' for detail or '-X list' for terser detail.
+
+|--ignore-profile |- |Ignore rpk.yaml and redpanda.yaml; use default settings.
+
+|--profile |string |rpk profile to use.
+
+|-v, --verbose |- |Enable verbose logging.
+|===

modules/reference/pages/rpk/rpk-ai/rpk-ai-uninstall.adoc

@@ -0,0 +1,29 @@
+= rpk ai uninstall
+
+Uninstall the Redpanda AI CLI.
+
+== Usage
+
+[,bash]
+----
+rpk ai uninstall [flags]
+----
+
+== Flags
+
+[cols="1m,1a,2a"]
+|===
+|*Value* |*Type* |*Description*
+
+|-h, --help |- |Help for uninstall.
+
+|--config |string |Redpanda or rpk config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`.
+
+|-X, --config-opt |stringArray |Override rpk configuration settings; '-X help' for detail or '-X list' for terser detail.
+
+|--ignore-profile |- |Ignore rpk.yaml and redpanda.yaml; use default settings.
+
+|--profile |string |rpk profile to use.
+
+|-v, --verbose |- |Enable verbose logging.
+|===

modules/reference/pages/rpk/rpk-ai/rpk-ai-upgrade.adoc

@@ -0,0 +1,31 @@
+= rpk ai upgrade
+
+Upgrade to the latest Redpanda AI CLI version.
+
+== Usage
+
+[,bash]
+----
+rpk ai upgrade [flags]
+----
+
+== Flags
+
+[cols="1m,1a,2a"]
+|===
+|*Value* |*Type* |*Description*
+
+|-h, --help |- |Help for upgrade.
+
+|--no-confirm |- |Disable confirmation prompt for major version upgrades.
+
+|--config |string |Redpanda or rpk config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`.
+
+|-X, --config-opt |stringArray |Override rpk configuration settings; '-X help' for detail or '-X list' for terser detail.
+
+|--ignore-profile |- |Ignore rpk.yaml and redpanda.yaml; use default settings.
+
+|--profile |string |rpk profile to use.
+
+|-v, --verbose |- |Enable verbose logging.
+|===

modules/reference/pages/rpk/rpk-ai/rpk-ai.adoc

@@ -0,0 +1,30 @@
+= rpk ai
+
+Manage the Redpanda AI Gateway
+
+== Usage
+
+[,bash]
+----
+rpk ai [flags]
+  rpk ai [command]
+----
+
+== Flags
+
+[cols="1m,1a,2a"]
+|===
+|*Value* |*Type* |*Description*
+
+|-h, --help |- |Help for ai.
+
+|--config |string |Redpanda or rpk config file; default search paths are `/var/lib/redpanda/.config/rpk/rpk.yaml`, `$PWD/redpanda.yaml`, and `/etc/redpanda/redpanda.yaml`.
+
+|-X, --config-opt |stringArray |Override rpk configuration settings; '-X help' for detail or '-X list' for terser detail.
+
+|--ignore-profile |- |Ignore rpk.yaml and redpanda.yaml; use default settings.
+
+|--profile |string |rpk profile to use.
+
+|-v, --verbose |- |Enable verbose logging.
+|===

modules/reference/pages/rpk/rpk-cloud/rpk-cloud-cluster-select.adoc

@@ -0,0 +1,3 @@
+= rpk cloud cluster select
+
+include::ROOT:reference:partial$rpk-cloud/rpk-cloud-cluster-select.adoc[tag=single-source]

modules/reference/pages/rpk/rpk-cloud/rpk-cloud-cluster.adoc

@@ -0,0 +1,3 @@
+= rpk cloud cluster
+
+include::ROOT:reference:partial$rpk-cloud/rpk-cloud-cluster.adoc[tag=single-source]

modules/reference/pages/rpk/rpk-cloud/rpk-cloud-login.adoc

@@ -0,0 +1,3 @@
+= rpk cloud login
+
+include::ROOT:reference:partial$rpk-cloud/rpk-cloud-login.adoc[tag=single-source]

modules/reference/pages/rpk/rpk-cloud/rpk-cloud-logout.adoc

@@ -0,0 +1,3 @@
+= rpk cloud logout
+
+include::ROOT:reference:partial$rpk-cloud/rpk-cloud-logout.adoc[tag=single-source]

modules/reference/pages/rpk/rpk-cloud/rpk-cloud.adoc

@@ -0,0 +1,3 @@
+= rpk cloud
+
+include::ROOT:reference:partial$rpk-cloud/rpk-cloud.adoc[tag=single-source]

modules/reference/pages/rpk/rpk-profile/rpk-profile.adoc

@@ -0,0 +1,4 @@
+= rpk profile
+:page-aliases: reference:rpk/rpk-profile.adoc
+
+include::ROOT:reference:rpk/rpk-profile/rpk-profile.adoc[tag=single-source]

modules/reference/pages/rpk/rpk-x-options.adoc

@@ -0,0 +1,19 @@
+= rpk -X
+
+Use the `-X` flag to override any rpk-specific configuration option for a single command, without modifying your rpk profile. Each option follows the form `key=value` — for example, `rpk -X tls.enabled=true` enables TLS for the Kafka API.
+
+Every `-X` option also has an environment-variable equivalent: prefix with `RPK_` and replace periods (`.`) with underscores (`_`). For example, `tls.enabled` becomes `RPK_TLS_ENABLED`.
+
+To list every available option, run:
+
+[,bash]
+----
+rpk -X list
+----
+
+Run `rpk -X help` for inline descriptions, or see the link:https://docs.redpanda.com/current/reference/rpk/rpk-x-options/[full `rpk -X` reference^] in the Redpanda docs.
+
+[TIP]
+====
+For persistent configuration across commands and sessions, prefer xref:reference:rpk/rpk-profile/rpk-profile.adoc[rpk profiles] over environment variables or `-X` flags.
+====