Convert :personas: metadata to product-design-approved ADP vocabulary

docs-data/personas.yaml

@@ -0,0 +1,171 @@
+# Redpanda ADP (Agentic Data Plane) Documentation Personas
+#
+# These personas represent the target audience for adp-docs.
+# Use these IDs when assigning :personas: attributes to documentation pages.
+#
+# Vocabulary is product-design-approved for the ADP product. Each persona
+# describes a role and a set of constraints, not a specific person — slugs
+# are role-based and do not reference characters used elsewhere in product
+# research artifacts.
+#
+# Choose the minimum set of personas that genuinely fits the page. A page
+# tagged with all five is usually a sign the persona line is not adding signal.
+
+schema_version: "1.0"
+repository: adp-docs
+
+personas:
+  # ============================================================================
+  # GOVERNANCE
+  # The personas who decide whether ADP gets into the building.
+  # ============================================================================
+
+  - id: security_compliance_lead
+    name: Security and Compliance Lead
+    description: Security and compliance owner who must sign off on AI workloads before they ship. Needs evidence — prompt and output logs, data-flow diagrams, attestations — not vendor assurances.
+    experience_level: advanced
+    goals:
+      - Establish defensible audit trails for every AI request and response
+      - Produce regulator-ready compliance evidence without manual report-building
+      - Map data flows across every AI provider before procurement opens a ticket
+      - Maintain an AI inventory the board and risk committee can trust
+      - Approve workloads that meet SOC 2, BAA, and sector-specific obligations
+    pain_points:
+      - Past incidents where third-party AI tools captured sensitive data without disclosure
+      - Vendor claims about ephemeral or non-retained data with no attestation behind them
+      - Compliance reviews assembled by hand instead of generated by the platform
+      - No central inventory of which agents touch which data
+      - Logging that's labeled "audit-ready" but doesn't include prompts and outputs
+    content_preferences:
+      - Documented data-flow diagrams and storage locations
+      - Audit log examples with prompt and output fields
+      - Compliance attestation references (SOC 2, HIPAA-adjacent, BAA)
+      - Step-by-step procedures for incident response and access revocation
+      - Reference tables of what is and is not retained, and for how long
+    typical_content_types:
+      - reference
+      - how-to
+      - concepts
+      - best-practices
+
+  - id: platform_engineer
+    name: Platform Engineer
+    description: Owns the paved path for AI adoption across application teams. Cares about APIs, automation, observability, blast radius, and cost attribution. Allergic to UI-only configuration and to tools that generate platform-team support load.
+    experience_level: advanced
+    goals:
+      - Provide a self-serve, governed path for application teams to use AI Gateway and MCP
+      - Wire ADP into existing CI/CD, IaC, and secrets-management systems
+      - Make cost attributable per team so showback is possible from day one
+      - Set up observability that surfaces real failure modes, not just happy-path metrics
+      - Run the platform without expanding the platform team's on-call load
+    pain_points:
+      - Tools that look easy for users but generate platform-team tickets
+      - Configuration that lives only in UIs with no API or CLI behind it
+      - Cost models that can't attribute spend to the team that incurred it
+      - Onboarding gated behind sales calls when the docs should suffice
+      - Hidden runtime dependencies that surface as memory leaks or outages in production
+    content_preferences:
+      - API and CLI references with copy-pasteable examples
+      - Terraform, Helm, and CI templates
+      - Rate-limit, retry, and idempotency documentation
+      - Observability integration guides (Datadog, OpenTelemetry, Prometheus)
+      - Failure-mode catalogs, blast-radius analysis, and clear escalation paths
+    typical_content_types:
+      - reference
+      - how-to
+      - troubleshooting
+      - best-practices
+
+  # ============================================================================
+  # BUILDERS
+  # The personas who actually use ADP to build and validate AI workloads.
+  # ============================================================================
+
+  - id: agent_builder
+    name: Agent Builder
+    description: Builds and ships AI agents and workflows that solve a specific business problem. Reads docs to get unblocked on a concrete task, not to study. Spans low-code automators and software engineers writing against the SDK — what they share is a goal-driven, demo-driven mindset and impatience with anything that doesn't deliver value in the first session.
+    experience_level: intermediate
+    goals:
+      - Build a working agent or workflow in the first session
+      - Wire an existing agent or application into AI Gateway, MCP Gateway, or a managed MCP server
+      - Ship something demoable to leadership within the first sprint
+      - Iterate on agent behavior without breaking production
+      - Validate that the agent behaves as expected before turning on traffic
+    pain_points:
+      - Quickstarts that don't actually start in the time the page promises
+      - Examples written in languages or SDKs the builder doesn't use
+      - Silent failures in deployed flows with no notification path
+      - Free trials gated behind sales calls
+      - Tooling that requires IT approval before the builder can even try it
+    content_preferences:
+      - Quickstarts that produce a visible result in under an hour
+      - SDK examples in multiple languages (Python, TypeScript, Go)
+      - Step-by-step screenshots and short procedures
+      - Integration recipes for Cursor, Cline, Copilot, Continue, and similar coding assistants
+      - Tutorials that build toward a story a builder can tell their manager
+    typical_content_types:
+      - quickstart
+      - tutorial
+      - how-to
+      - cookbook
+
+  - id: domain_evaluator
+    name: Domain Evaluator
+    description: Subject-matter expert who is the final line of defense between an agent's output and the work product it feeds. Verifies sources, tests edge cases, and refuses to champion a tool until verification time is meaningfully lower than the time it saves.
+    experience_level: intermediate
+    goals:
+      - Verify that agent outputs are accurate, sourced, and defensible
+      - Test agents against real documents and real edge cases before they touch production work
+      - Reduce time spent re-checking agent output without losing accuracy
+      - Establish trust criteria the rest of the team can adopt
+      - Catch and report regressions in agent behavior
+    pain_points:
+      - Tools that can't show their sources or surface citation provenance
+      - Outputs that vary across identical inputs
+      - Past incidents where an AI-generated artifact contained fabricated facts
+      - No clear answer on how confidential or privileged data is handled
+      - Demos that don't reflect real-world edge cases
+    content_preferences:
+      - Pages that explain how outputs are grounded — sources, retrieval, citations
+      - Eval traces, replay logs, and reproducibility documentation
+      - Edge-case test patterns and accuracy benchmarks
+      - Confidential-data handling and isolation guarantees
+      - Comparison tables across model behaviors on the same input
+    typical_content_types:
+      - concepts
+      - how-to
+      - reference
+      - best-practices
+
+  # ============================================================================
+  # BRIDGE
+  # The persona who owns making the rollout stick.
+  # ============================================================================
+
+  - id: pilot_lead
+    name: Pilot Lead
+    description: Operations or team lead running an ADP pilot or first rollout. Sits between governance and builders — neither group naturally asks about adoption metrics, day-2 support, or the onboarding experience for the next teammate. Owns the success or failure of the pilot publicly.
+    experience_level: intermediate
+    goals:
+      - Roll out ADP to a single team with metrics they can defend in a VP one-on-one
+      - Onboard new team members onto agents in under an hour
+      - Surface errors and usage in dashboards the team can act on
+      - Make adoption repeatable so it can scale to the next team
+      - Avoid championing a tool whose day-2 experience falls apart
+    pain_points:
+      - Tools that work in pilot but break at scale
+      - Errors that aren't visible to the team owning them
+      - Onboarding paths that assume engineering background a non-technical team doesn't have
+      - Metrics that look good in demos but don't map to a business outcome
+      - Day-2 support tickets landing on a platform team that didn't sign up for them
+    content_preferences:
+      - Adoption playbooks and rollout checklists
+      - Dashboards that show usage, errors, and outcomes per team
+      - Onboarding guides written for the new joiner, not the original champion
+      - Escalation and incident-response paths
+      - Reference architectures from comparable rollouts
+    typical_content_types:
+      - overview
+      - how-to
+      - best-practices
+      - tutorial

modules/ROOT/pages/index.adoc

@@ -3,7 +3,7 @@
 :page-layout: index
 :page-topic-type: overview
 :page-categories: Agentic Data Plane
-:personas: evaluator, ai_agent_developer, platform_admin
+:personas: agent_builder, platform_engineer, security_compliance_lead, pilot_lead, domain_evaluator
 :learning-objective-1: Identify the key components of Redpanda ADP and their purposes
 :learning-objective-2: Describe how each component addresses enterprise governance and reliability requirements
 :learning-objective-3: Determine whether Redpanda ADP fits your organization's requirements for AI agent deployment

modules/ROOT/partials/ai-hub/configure-ai-hub.adoc

@@ -1,7 +1,7 @@
 = Configure AI Hub Gateway
 :description: Create and configure zero-config AI Hub gateways with pre-configured routing and backend pools.
 :page-topic-type: how-to
-:personas: platform_admin
+:personas: platform_engineer
 :learning-objective-1: Create an AI Hub gateway with one-click configuration
 :learning-objective-2: Configure user preference toggles to customize routing behavior
 :learning-objective-3: Manage provider credentials for OpenAI, Anthropic, and Google Gemini

modules/ROOT/partials/ai-hub/eject-to-custom-mode.adoc

@@ -1,7 +1,7 @@
 = Eject to Custom Mode
 :description: Transition an AI Hub gateway to Custom mode for full configuration control.
 :page-topic-type: how-to
-:personas: platform_admin
+:personas: platform_engineer
 :learning-objective-1: Evaluate the implications of ejecting from AI Hub to Custom mode
 :learning-objective-2: Prepare for ejection by documenting current configuration
 :learning-objective-3: Execute the ejection process and configure the gateway post-ejection

modules/ROOT/partials/ai-hub/gateway-modes.adoc

@@ -1,7 +1,7 @@
 = AI Gateway Modes
 :description: Understand AI Hub mode and Custom mode, and choose the right approach for your organization.
 :page-topic-type: concept
-:personas: evaluator, platform_admin, app_developer
+:personas: platform_engineer, agent_builder
 :learning-objective-1: Differentiate between AI Hub and Custom gateway modes
 :learning-objective-2: Determine which mode suits your use case based on configuration needs
 :learning-objective-3: Identify which mode a gateway is running in using Console or API

modules/ROOT/partials/ai-hub/use-ai-hub-gateway.adoc

@@ -1,7 +1,7 @@
 = Use AI Hub Gateway
 :description: Connect to and use AI Hub mode gateways with pre-configured intelligent routing.
 :page-topic-type: how-to
-:personas: app_developer
+:personas: agent_builder
 :learning-objective-1: Identify whether a gateway is running in AI Hub mode
 :learning-objective-2: Connect your application to an AI Hub gateway using the OpenAI SDK
 :learning-objective-3: Describe how intelligent routing directs requests to providers

modules/ROOT/partials/integrations/claude-code-admin.adoc

@@ -1,7 +1,7 @@
 = Configure AI Gateway for Claude Code
 :description: Configure Redpanda AI Gateway to support Claude Code clients.
 :page-topic-type: how-to
-:personas: platform_admin
+:personas: platform_engineer
 :learning-objective-1: Configure AI Gateway endpoints for Claude Code connectivity
 :learning-objective-2: Set up authentication and access control for Claude Code clients
 :learning-objective-3: Deploy MCP tool aggregation for Claude Code tool discovery

modules/ROOT/partials/integrations/claude-code-user.adoc

@@ -1,7 +1,7 @@
 = Configure Claude Code with AI Gateway
 :description: Configure Claude Code to use Redpanda AI Gateway for unified LLM access and MCP tool aggregation.
 :page-topic-type: how-to
-:personas: ai_agent_developer, app_developer
+:personas: agent_builder
 :learning-objective-1: Configure Claude Code to connect to AI Gateway endpoints
 :learning-objective-2: Set up MCP server integration through AI Gateway
 :learning-objective-3: Verify Claude Code is routing requests through the gateway

modules/ROOT/partials/integrations/cline-admin.adoc

@@ -1,7 +1,7 @@
 = Configure AI Gateway for Cline
 :description: Configure Redpanda AI Gateway to support Cline clients.
 :page-topic-type: how-to
-:personas: platform_admin
+:personas: platform_engineer
 :learning-objective-1: Configure AI Gateway endpoints for Cline connectivity
 :learning-objective-2: Set up authentication and access control for Cline clients
 :learning-objective-3: Deploy MCP tool aggregation for Cline tool discovery

modules/ROOT/partials/integrations/cline-user.adoc

@@ -1,7 +1,7 @@
 = Configure Cline with AI Gateway
 :description: Configure Cline to use Redpanda AI Gateway for unified LLM access, MCP tool integration, and autonomous coding workflows.
 :page-topic-type: how-to
-:personas: ai_agent_developer, app_developer
+:personas: agent_builder
 :learning-objective-1: Configure Cline to connect to AI Gateway for LLM requests and MCP tools
 :learning-objective-2: Set up autonomous mode with custom instructions and browser integration
 :learning-objective-3: Verify Cline routes requests through the gateway and optimize for cost

modules/ROOT/partials/integrations/continue-admin.adoc

@@ -1,7 +1,7 @@
 = Configure AI Gateway for Continue.dev
 :description: Configure Redpanda AI Gateway to support Continue.dev clients.
 :page-topic-type: how-to
-:personas: platform_admin
+:personas: platform_engineer
 :learning-objective-1: Configure AI Gateway endpoints for Continue.dev connectivity
 :learning-objective-2: Set up multi-provider backends with native format routing
 :learning-objective-3: Deploy MCP tool aggregation for Continue.dev tool discovery

modules/ROOT/partials/integrations/continue-user.adoc

@@ -1,7 +1,7 @@
 = Configure Continue.dev with AI Gateway
 :description: Configure Continue.dev to use Redpanda AI Gateway for unified LLM access, MCP tool integration, and AI-assisted coding.
 :page-topic-type: how-to
-:personas: ai_agent_developer, app_developer
+:personas: agent_builder
 :learning-objective-1: Configure Continue.dev to connect to AI Gateway for chat and autocomplete
 :learning-objective-2: Set up MCP server integration through AI Gateway
 :learning-objective-3: Optimize Continue.dev settings for cost and performance

modules/ROOT/partials/integrations/cursor-admin.adoc

@@ -1,7 +1,7 @@
 = Configure AI Gateway for Cursor IDE
 :description: Configure Redpanda AI Gateway to support Cursor IDE clients.
 :page-topic-type: how-to
-:personas: platform_admin
+:personas: platform_engineer
 :learning-objective-1: Configure AI Gateway endpoints for Cursor IDE connectivity
 :learning-objective-2: Set up OpenAI-compatible transforms for multi-provider routing
 :learning-objective-3: Deploy multi-tenant authentication strategies for Cursor clients

modules/ROOT/partials/integrations/cursor-user.adoc

@@ -1,7 +1,7 @@
 = Configure Cursor IDE with AI Gateway
 :description: Configure Cursor IDE to use Redpanda AI Gateway for unified LLM access, MCP tool integration, and AI-assisted coding.
 :page-topic-type: how-to
-:personas: ai_agent_developer, app_developer
+:personas: agent_builder
 :learning-objective-1: Configure Cursor IDE to route LLM requests through AI Gateway
 :learning-objective-2: Set up MCP server integration for tool access through the gateway
 :learning-objective-3: Optimize Cursor settings for multi-tenancy and cost control

modules/ROOT/partials/integrations/github-copilot-admin.adoc

@@ -1,7 +1,7 @@
 = Configure AI Gateway for GitHub Copilot
 :description: Configure Redpanda AI Gateway to support GitHub Copilot clients.
 :page-topic-type: how-to
-:personas: platform_admin
+:personas: platform_engineer
 :learning-objective-1: Configure AI Gateway endpoints for GitHub Copilot connectivity
 :learning-objective-2: Deploy multi-tenant authentication strategies for Copilot clients
 :learning-objective-3: Set up model aliasing and BYOK routing for GitHub Copilot

modules/ROOT/partials/integrations/github-copilot-user.adoc

@@ -1,7 +1,7 @@
 = Configure GitHub Copilot with AI Gateway
 :description: Configure GitHub Copilot to use Redpanda AI Gateway for unified LLM access and custom provider management.
 :page-topic-type: how-to
-:personas: ai_agent_developer, app_developer
+:personas: agent_builder
 :learning-objective-1: Configure GitHub Copilot in VS Code and JetBrains IDEs to route requests through AI Gateway
 :learning-objective-2: Set up multi-tenancy with gateway routing for cost tracking
 :learning-objective-3: Configure enterprise BYOK deployments for team-wide Copilot access

modules/ROOT/partials/migration-guide.adoc

@@ -1,7 +1,7 @@
 = Migrate to AI Gateway
 :description: Step-by-step migration guide to transition existing applications from direct LLM provider integrations to Redpanda AI Gateway with minimal disruption.
 :page-topic-type: how-to
-:personas: app_developer, platform_admin
+:personas: agent_builder, platform_engineer
 :learning-objective-1: Migrate LLM integrations to AI Gateway with zero downtime using feature flags
 :learning-objective-2: Verify gateway connectivity and compare performance metrics
 :learning-objective-3: Roll back to direct integration if issues arise during migration

modules/ROOT/partials/observability-logs.adoc

@@ -1,7 +1,7 @@
 = Observability: Logs
 :description: Guide to AI Gateway request logs, including where to find logs, log fields, filtering, searching, inspecting requests, common analysis tasks, log retention, export options, privacy/security, and troubleshooting.
 :page-topic-type: reference
-:personas: platform_admin, app_developer
+:personas: platform_engineer, security_compliance_lead, agent_builder
 :learning-objective-1: Locate and filter request logs to debug failures or reconstruct conversations
 :learning-objective-2: Interpret log fields to diagnose performance and cost issues
 :learning-objective-3: Export logs for compliance auditing or long-term analysis

modules/ROOT/partials/observability-metrics.adoc

@@ -1,7 +1,7 @@
 = Observability: Metrics and Analytics
 :description: Guide to AI Gateway metrics and analytics, including where to find metrics, key metrics explained, dashboard views, filtering/grouping, alerting, exporting, common analysis tasks, retention, API access, best practices, and troubleshooting.
 :page-topic-type: reference
-:personas: platform_admin, app_developer
+:personas: platform_engineer, pilot_lead
 :learning-objective-1: Monitor aggregate metrics to track usage patterns and budget adherence
 :learning-objective-2: Compare model and provider performance using latency and cost metrics
 :learning-objective-3: Configure alerts for budget thresholds and performance degradation

modules/agents/pages/a2a-concepts.adoc

@@ -1,7 +1,7 @@
 = A2A Protocol
 :description: Learn how the A2A protocol enables agent discovery and communication.
 :page-topic-type: concepts
-:personas: agent_developer, app_developer, streaming_developer
+:personas: agent_builder
 :learning-objective-1: Describe the A2A protocol and its role in agent communication
 :learning-objective-2: Explain how agent cards enable discovery
 :learning-objective-3: Identify how authentication secures agent communication

modules/agents/pages/architecture-patterns.adoc

@@ -2,7 +2,7 @@
 :description: Design maintainable agent systems with single-agent and multi-agent patterns based on domain complexity.
 :page-byoc: true
 :page-topic-type: best-practices
-:personas: agent_developer, streaming_developer
+:personas: agent_builder
 :learning-objective-1: Evaluate single-agent versus multi-agent architectures for your use case
 :learning-objective-2: Choose appropriate LLM models based on task requirements
 :learning-objective-3: Apply agent boundary design principles for maintainability