docs: sync ADP changes from cloudv2 (2026-06-08)

[micheleRP]

Summary

Syncs a user-facing ADP access-control change from cloudv2: agent conversation transcripts now have their own permissions and a dedicated built-in role, instead of piggybacking on the broad agent-read permission.

Deploy preview

• Transcript permissions reference: https://deploy-preview-67--redpanda-agentic-data-plane.netlify.app/agentic-data-plane/control/permissions-reference/

(The link 404s until Netlify finishes building the preview.)

Source commit

• 6dfd3b3 — adp: split transcript authz into dedicated get/list permissions (cloudv2 PR #26829, merged in 39b752a), author @birdayz

What changed in the product

• Two new permissions in pkg/permissions/permissions_constants.go:
  • dataplane_adp_transcript_get — View a single agent conversation transcript
  • dataplane_adp_transcript_list — List agent conversation transcripts
• The TranscriptsService.ListTranscripts / GetTranscript RPCs now enforce these permissions instead of dataplane_adp_agent_get (proto/public/cloud/redpanda/api/adp/v1alpha1/transcript.proto).
• A new built-in role TranscriptReader (apps/backoffice-worker) grants both permissions. It is provisioned only for organizations that have an ADP cluster. Admin still grants everything; Writer and Reader deliberately do not grant transcript access, because transcripts carry full conversation content.

What I documented and why

• modules/control/pages/permissions-reference.adoc: added a Transcript permissions section (with the two permissions and a TranscriptReader column) and a TranscriptReader row in the built-in roles summary. A note calls out the behavior change: agent read access no longer implies transcript read access.
• modules/control/pages/permissions-overview.adoc: added the dataplane_adp_transcript_* family to the namespace list and TranscriptReader to the built-in roles table.
• modules/monitor/pages/transcripts.adoc: updated the prerequisite and the "Transcript missing entirely" troubleshooting step to require the TranscriptReader role, and removed the now-resolved TODO about the missing permission model.

Verified against the cited commit. npm run build succeeds; the changed pages produce no AsciiDoc warnings or broken xrefs (remaining build errors are pre-existing GitHub API rate-limit failures and dropping cells warnings in auto-generated rpk-ai reference files, untouched here).

Reviewers

Added @birdayz (author of the source commit) as an optional reviewer for a source-accuracy check. Their approval is not required to merge.

Considered but not documented this run

These cloudv2 changes from the same window are UI-surface or internal-deployment changes without new config/API/CLI to document. Flagged as TODO for human review rather than guessing at UI specifics:

• Live transcripts consumer enabled (3fd869c, PR #26850): turns on the adp-api transcripts consumer so live conversations land in redpanda.otel_traces. Internal deployment config; the Transcripts feature is already documented.
• Per-agent Cost & Usage on the agents registry (PR #26789): new UI panel. May warrant a mention in control/budgets.adoc or the monitoring docs once the GA UI labels are confirmed.
• MCP server connection tab code snippets (PR #26833): copy-ready Python/Node/Go/Java snippets in the Console connection tab. May warrant an update to the MCP client connection docs once the GA UI is confirmed.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for redpanda-agentic-data-plane ready!

Name	Link
🔨 Latest commit	5c31c06
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-agentic-data-plane/deploys/6a26d4689c196a00085ee701
😎 Deploy Preview	https://deploy-preview-67--redpanda-agentic-data-plane.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[micheleRP]

[adp-docs PR critic]

Verdict: looks accurate against the cited cloudv2 source. I verified every factual claim against commit 6dfd3b3 (PR #26829) and found no inaccuracies. One minor wording nit, nothing blocking.

Source accuracy (verified — pass)

• The two permissions and their descriptions — dataplane_adp_transcript_get = "View a single agent conversation transcript" and dataplane_adp_transcript_list = "List agent conversation transcripts". Match pkg/permissions/permissions_constants.go exactly (the new dataPlanePermissions entries in commit 6dfd3b3). The reference-table operation strings are verbatim from the source descriptions. ✓
• RPC enforcement change — proto/public/cloud/redpanda/api/adp/v1alpha1/transcript.proto: ListTranscripts now enforces dataplane_adp_transcript_list and GetTranscript enforces dataplane_adp_transcript_get (both previously dataplane_adp_agent_get). Confirms the NOTE's claim that dataplane_adp_agent_get no longer implies transcript read. ✓
• TranscriptReader role grants exactly these two permissions — pkg/permissions/permissions_constants.go transcriptReaderPermissions = ["dataplane_adp_transcript_get", "dataplane_adp_transcript_list"] via GetTranscriptReaderPermissions. ✓
• Writer/Reader do not grant; Admin does — confirmed by the dedicated role and the commit message ("not handed out through the broad Writer/Reader defaults… Admin still gets everything"). Reference table correctly checks only the TranscriptReader column; Admin omitted per the page's existing convention. ✓
• "Provisioned for organizations with an ADP cluster" — confirmed in apps/backoffice-worker/internal/workflows/organization/builtin_roles.go: TranscriptReader is registered with requireADPCluster = true, and ensureBuiltinRoles skips requireADPCluster roles when !hasADPCluster — same gating as the AIAgentInvoker/MCPInvoker/LLMProviderInvoker roles. Role name string is "TranscriptReader" (apps/backoffice-worker/common/roles.go). ✓
• "Transcripts carry full conversation content (system prompts, user messages, tool arguments, and model output)" — consistent with GetTranscriptResponse in the proto (system_prompt, turns[].content, tool_calls[].input/output). ✓

Correctness (verified)

• The [[transcript-permissions]] anchor added in permissions-reference.adoc matches both inbound xrefs from transcripts.adoc (#transcript-permissions). The new table keeps the standard cols="2,2,1,1,1" 5-column layout, and the added sentence ("adds a TranscriptReader column in place of the Invoker column") correctly reconciles the substitution with the "How to read this reference" section (which otherwise names only Writer/Reader/Invoker). No malformed AsciiDoc or broken xrefs introduced. ✓
• Replacing the old redpanda.otel_traces topic-read prerequisite/troubleshooting step with the TranscriptReader requirement is the right call: the read path is the permission-gated TranscriptsService API, not direct topic access. Removing the now-resolved TODO is appropriate. ✓

Minor (non-blocking)

• permissions-overview.adoc (transcript family bullet): "Granted only by the dedicated TranscriptReader role, not by Writer or Reader" omits Admin, which also grants it. The reference page's NOTE states it precisely ("Only the dedicated TranscriptReader role and Admin grant them"). The overview's family list is brief and the page elsewhere notes Admin grants everything, so this is a small imprecision rather than an error — consider "Granted by the dedicated TranscriptReader role (and Admin), not by Writer or Reader" for consistency with the reference page.

Reviewed the full reference/overview/transcripts pages for context, not just the hunks. Nothing to change for accuracy.

---

Generated by Claude Code

[Feediver1]

PR Review

Files reviewed: 3 .adoc files
Overall assessment: Well-sourced sync PR with strong cross-page consistency. New "Transcript permissions" section is clear and the behavior-change NOTE pre-empts the obvious migration question. One companion TODO in concepts.adoc should be resolved in the same change; remaining items are minor symmetry/verbosity polish.

What this PR does

Syncs cloudv2 commit 6dfd3b3 (PR #26829, @birdayz): transcript reads now have dedicated dataplane_adp_transcript_get / dataplane_adp_transcript_list permissions and a new TranscriptReader built-in role, replacing the previous "transcripts piggyback on dataplane_adp_agent_get" model.

Critical issues (must fix)

1. modules/monitor/pages/concepts.adoc:319 — Companion TODO is now resolved by this PR but left unaddressed. The TODO reads: "Re-add guidance on ACL scoping for redpanda.otel_traces once the standalone-ADP permission model lands. Today's wording assumed users manage topic ACLs on their own Redpanda Cloud cluster, which won't apply when ADP is a separate product surface." This is the same standalone permission model this PR documents — same author who removed the matching TODO from transcripts.adoc:194 should also act on this one.
   • Fix: Replace this TODO with a sentence in the surrounding paragraph, e.g., "Read access to transcript data is granted through the TranscriptReader role, not topic ACLs. See xref:control:permissions-reference.adoc#transcript-permissions[Transcript permissions]." Otherwise the PR ships its own change but leaves a now-stale TODO that says exactly what it just shipped.

Suggestions (should consider)

1. transcripts.adoc:22 (Prerequisites bullet) — The bullet has grown to ~3 sentences, longer than the bullet above it. The detailed rationale is repeated almost verbatim at L194 (troubleshooting).

   • Current: "The TranscriptReader role (or Admin) to read transcripts. Transcripts carry full conversation content, so the dataplane_adp_transcript_get and dataplane_adp_transcript_list permissions stay out of the default Reader and Writer roles. See xref:control:permissions-reference.adoc#transcript-permissions[Transcript permissions]."
   • Suggested: "The xref:control:permissions-reference.adoc#transcript-permissions[TranscriptReader role] (or Admin). Transcript reads are not part of the default Reader or Writer roles."

2. Asymmetric "does not grant transcript reads" caveat between Reader and Writer rows — The Reader row in both built-in roles tables adds "Does not grant transcript reads." Writer is just as deliberately excluded per the PR description ("Writer and Reader deliberately do not grant transcript access"), but the Writer row doesn't get a parallel caveat. Either add one to Writer for symmetry, or drop the Reader caveat and rely on the dedicated TranscriptReader row + NOTE callout to convey the exclusion.

3. permissions-overview.adoc:65 (Reader row) — The "Does not grant transcript reads." sentence is inserted mid-paragraph before "Use for auditors..." which breaks the use-case framing flow.

   • Current: "Read-only access ... plus MCP runtime read operations such as resources_list and prompts_get. No create, update, delete, or invoke. Does not grant transcript reads. Use for auditors, evaluators, and stakeholders..."
   • Suggested: Move the caveat to the end: "Read-only access ... plus MCP runtime read operations ... No create, update, delete, or invoke. Use for auditors, evaluators, and stakeholders who need visibility without mutation rights. Does not grant transcript reads — those require the TranscriptReader role." (Same treatment in permissions-reference.adoc:480.)

Impact on other files

• modules/monitor/pages/concepts.adoc:319 — see Critical Initial setup: ADP documentation repository #1 above.
• Other standalone-ADP TODOs are out of scope: byoa-telemetry.adoc:123, ingest-custom-traces.adoc (multiple), mcp-overview.adoc:61 — these are about service-account auth for OTLP ingest, the broader ingestion-flow rewrite, and screenshot wording, not the transcript permission model. Correctly left untouched.
• No release notes / What's New page exists in adp-docs; not applicable.
• No nav.adoc update needed — no new pages.
• Cross-section consistency in permissions-reference.adoc: the new Transcript section sits at L239 between Agent credential (L214) and Spending (L265) — logical placement.
• Tabular pattern consistency: the new table uses 5 columns (Writer | Reader | TranscriptReader), substituting TranscriptReader for the Invoker column used in MCP/LLM provider/A2A/Pipeline/Knowledge base tables. The single-sentence explainer at L32 prevents reader confusion.
• Anchor [[transcript-permissions]] verified: defined at L238 in permissions-reference.adoc, referenced from transcripts.adoc:22 and transcripts.adoc:194 — both resolve.

What works well

• Sourced and traceable: PR description cites the cloudv2 commit SHA, the original PR number, and the source author.
• Source-verification comments embedded in the .adoc files themselves (the // Transcript permissions and the TranscriptReader role verified against cloudv2 commit 6dfd3b3 line at L10 of both control pages) — future-proofs the next sync.
• The NOTE callout at L260-263 explicitly describes the behavior change in operator-terms.
• TranscriptReader role naming and casing matches existing role-name convention (AIAgentInvoker, MCPInvoker, LLMProviderInvoker, PipelineInvoker).
• Provisioning detail preserved: "Provisioned for organizations with an ADP cluster" matches the source code's conditional role creation.
• Active voice, second person, present tense maintained throughout.
• Considered-but-not-documented items explicitly listed in PR description with reasoning.

---

🤖 Generated with Claude Code via /docs-team-standards:pr-review

[micheleRP]

Thanks both. All review feedback is now addressed.

Feediver1's review — resolved in commit 07e23ec:

• Critical (concepts.adoc:319 TODO): the standalone-ADP TODO is replaced with a sentence pointing read access to the TranscriptReader role (not topic ACLs), plus an xref to the Transcript permissions section.
• Suggestion 1 (transcripts.adoc:22 prerequisite): shortened to the TranscriptReader role xref + a one-line note that transcript reads aren't part of the default Reader/Writer roles.
• Suggestions 2 & 3 (asymmetric / mid-paragraph "Does not grant transcript reads" Reader caveat): resolved by dropping the Reader-row caveat from both pages and letting the dedicated TranscriptReader row + the behavior-change NOTE carry the exclusion.

PR critic's minor (Admin omission) — resolved in commit 5c31c06: the dataplane_adp_transcript_* bullet in permissions-overview.adoc now reads "Granted by the dedicated TranscriptReader role (and Admin), not by Writer or Reader," matching the reference page NOTE.