docs(adp): expand Excalidraw diagrams

[malinskibeniamin]

Summary

• expand the docs-only diagram set from 4 to 14 user-facing flows, each with one editable .excalidraw source and one rendered SVG
• explain MCP Inspector and MCP Gateway, LLM Playground and AI Gateway, Agent Inspector and A2A, guardrails, rpk ai, managed versus self-managed ownership, and OAuth client onboarding
• audit all 14 diagrams for enterprise docs: clean sans-serif type, consistent geometry, high-contrast semantic accents, deliberate line wrapping, and safer edge padding
• remove the crossing Playground connector, route the chart error branch vertically, and repair overflow in OAuth, rpk ai, remote MCP authentication, and MCP tool discovery
• keep the diagrams opaque and readable in both light and dark docs themes without exposing implementation internals
• align A2A, MCP, OAuth, gateway, CLI, and ownership claims with current ADP behavior and current official protocol specifications

Why

These workflows cross authentication, gateway, protocol, runtime, and observability boundaries. Focused diagrams help users understand the paths and trust boundaries they operate without exposing internal implementation details or tying the docs to specific UI libraries.

Commits

• 23d6181 docs(adp): add Excalidraw diagrams
• 372d794 docs(adp): expand Excalidraw diagrams
• bdfc598 docs(adp): spell out product name in ownership diagram and tune figure placement
• f5143a3 docs(adp): fit the gateway box title in the rpk ai workflow diagram
• 2d3ce5c docs(adp): keep diagram text inside its boxes across eight diagrams
• 761e4c6 docs(adp): polish Excalidraw diagrams
• a13f8a5 docs(adp): align diagrams with product behavior

Reviewer guide

1. Review the captions and alt text next to each diagram.
2. Compare each SVG with its adjacent editable Excalidraw source.
3. Check protocol copy at modules/connect/pages/mcp-overview.adoc and modules/connect/pages/a2a-concepts.adoc.
4. Check typography, connector routing, text containment, and theme treatment in the representative diagrams below.

Representative diagrams

MCP Gateway	LLM Playground

Agent Inspector	Runtime ownership

Visual review

• Status: ready; no P0 or P1 findings remain
• Checked all 14 source renders and 12 rendered Antora routes that contain them
• Audited claims against current ADP UI, CLI, gateway, protocol, and test evidence plus official MCP and A2A specifications
• Checked light and dark docs themes
• Checked Chromium at 390 × 844: SVGs remain responsive without clipping or horizontal overflow
• Verified the full diagrams remain opaque against both docs themes and preserve a stable aspect ratio
• Static SVGs add no interaction lifecycle; keyboard, notification, and form-state checks do not apply

Dogfood evidence

• Verdict: PASS
• Entrypoint: current Antora docs build; 12 customer routes covering all 14 diagrams
• Actions and break attempts: opened every diagram route, switched light/dark themes, tested Chromium desktop and 390 × 844, opened and closed the image zoom surface, checked accessible image names and console/network output
• Observations: every editable source has one matching SVG; all figures loaded; opaque dark canvases remain consistent in both themes; labels remain contained; mobile keeps the figures responsive and offers click-to-enlarge
• Repairs and replay: corrected protocol identification, CIMD/DCR roles, optional transcript wording, CLI context, runtime ownership, A2A links/version semantics, and stale alt text; regenerated six source/SVG pairs; replay passed
• Limits: no authenticated live ADP tenant; product semantics were verified against current implementation source/tests. Firefox, WebKit, forced colors, and RTL were not exercised.
• Visual review report: /tmp/visual-review-adp-diagrams-20260807.html (local evidence; representative SVGs and deploy previews are linked below)

Preview pages

• Redpanda Agentic Data Plane Overview (updated)
• How AI Gateway Works (updated)
• Configure an LLM Provider (updated)
• How MCP Servers Work (updated)
• Test an MCP Server's Tools with the Inspector (updated)
• Connect Remote MCP Clients (updated)
• Connect Agents with A2A (updated)
• Run Claude Code and Codex through AI Gateway (updated)
• Draw Charts from an Agent (updated)
• How Guardrails Work (updated)
• Monitor Agent Activity (updated)
• Use the Agentic Data Plane CLI (updated)

Test plan

• Run the six-diagram layout regression audit
• Run 10 reality-backed semantic checkpoints against diagrams and surrounding copy
• Audit all 14 diagrams against current ADP implementation evidence and official protocol specifications
• Build the current local Antora preview
• Run the complete multi-repository Antora build
• Validate all 14 Excalidraw sources as JSON and all 14 SVGs as XML
• Confirm every editable source has exactly one matching SVG
• Confirm SVGs contain no scripts or JavaScript URLs
• Run git diff --check
• Run repository lint and type-check scripts when present

[netlify]

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

Name	Link
🔨 Latest commit	0820a5c
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-agentic-data-plane/deploys/6a77d06bede77f00086932cd
😎 Deploy Preview	https://deploy-preview-198--redpanda-agentic-data-plane.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

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

[malinskibeniamin]

Automated /review: 4 finding(s).

[micheleRP]

Thanks @malinskibeniamin! I pushed bdfc598 to this branch with a few review fixes:

• Spelled out the "ADP" acronym in the resource-ownership diagram (we don't use that acronym in customer-facing text; it's trademarked elsewhere). The column header is now "Agentic Data Plane governance" and the provider cell reads "Provider config in / Agentic Data Plane". I edited both the SVG and the .excalidraw source, so if you re-export from your tooling, please carry those labels forward.
• Moved the intro figures below the learning-objectives blocks on the CLI, coding-agents, and MCP overview pages, and split the two stacked figures on remote-mcp-clients: onboarding options moved up to the intro, and the auth flow stays in Architecture. Small alt-text capitalization fixes there too.
• Standardized on capitalized "MCP Gateway" (matching "AI Gateway"), including the older architecture alt text on adp-overview.

Two items from the automated review findings still need your call:

1. The .excalidraw sources don't round-trip in Excalidraw (labels drop on load). Could you re-export real scenes from your tooling? Alternatively we could drop the sources and treat the SVGs as the artifacts.
2. The .excalidraw files under modules/*/images/ get published as site assets. If we keep the sources, a location outside the image family might be better. Since these are the first in the repo, whatever this PR does becomes the convention.

It would also be worth re-running the contrast check on the rebuilt SVGs to confirm the per-container ratios.

[micheleRP]

Follow-up since my earlier comment: f5143a3 and 2d3ce5c fix text that overflowed or crowded box edges in nine diagrams, and move the note pill in mcp-gateway-connection-flow clear of the Self-managed server box. Most fixes are pure geometry (boxes widened on arrow-free edges, labels shifted). Three change wording or line breaks: "HTTPS URL as client ID" in oauth-client-onboarding-options, the re-wrapped "Acts for user at upstream system" block in remote-mcp-client-authentication, and "Gateway connection" wrapped to two lines in resource-ownership-models.

Every change is in both the SVG and its .excalidraw source, so if you re-export from your own tooling, please regenerate from the committed sources or carry these forward.

I resolved the contrast and acronym threads after verifying them at head; the round-trip and published-sources threads are still open for your call. Also refreshed the PR description's commit list and re-pinned the representative diagram images to the current head.