Fix broken xrefs across the site (zero build errors)

micheleRP · claude · micheleRP · commit 63fb6440d928 · 2026-05-05T15:25:11.000-06:00
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` -&gt; `redpanda-adp`
component migration plus a few cross-component xrefs that lost their
component prefix.

Local-component fixes:
- ai-agents:observability/concepts.adoc -&gt; observability:concepts.adoc
  (transcripts.adoc, ingest-custom-traces.adoc, partial)
- ai-agents:observability/transcripts.adoc -&gt; observability:transcripts.adoc
- ai-agents:agents/monitor-agents.adoc -&gt; agents:monitor.adoc
- governance:guardrails.adoc -&gt; governance:guardrails/index.adoc (the
  page moved into a subdirectory)
- integrations/index.adoc -&gt; 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 -&gt; redpanda-cloud:manage:rpk/rpk-install.adoc
- develop:connect/components/inputs/otlp_*.adoc -&gt;
  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) &lt;noreply@anthropic.com&gt;
diff --git a/modules/ai-gateway/pages/admin/setup-guide.adoc b/modules/ai-gateway/pages/admin/setup-guide.adoc
@@ -379,4 +379,4 @@ Users can then discover and connect to the gateway using the information provide
 == Next steps
 
 * xref:routing-cel.adoc[CEL Routing Cookbook]
-* xref:integrations/index.adoc[Integrations]
+* xref:integrations:index.adoc[Integrations]
diff --git a/modules/ai-gateway/pages/gateway-quickstart.adoc b/modules/ai-gateway/pages/gateway-quickstart.adoc
@@ -529,6 +529,6 @@ const openai = new OpenAI({
 
 * xref:routing-cel.adoc[]
 * xref:aggregation.adoc[]
-* xref:integrations/index.adoc[]
+* xref:integrations:index.adoc[]
 * xref:gateway-architecture.adoc[]
 * xref:overview.adoc[]
diff --git a/modules/governance/pages/budgets.adoc b/modules/governance/pages/budgets.adoc
@@ -61,7 +61,7 @@ Some guardrail evaluators call an LLM to do their work. A toxicity classifier, f
 
 Guardrail evaluator cost surfaces in the same spending pipeline as user-facing LLM calls. The evaluator's cost is attributed to the *evaluator's configured upstream provider* — usually a small classifier model, separate from the user-facing LLM — so per-provider breakdowns separate the two automatically.
 
-For the per-evaluator cost model and how it interacts with the dashboard's spend view, see xref:governance:guardrails.adoc[Configure guardrails].
+For the per-evaluator cost model and how it interacts with the dashboard's spend view, see xref:governance:guardrails/index.adoc[Configure guardrails].
 
 // TODO: confirm with eng that guardrail evaluator cost flows into the same SpendingService as user-facing LLM cost (vs. a separate stream). Open Q A3 in the companion plan, also flagged on the Guardrails plan.
 
@@ -87,7 +87,7 @@ Cap-management arrives after GA per the Governance V0 PRD. The planned feature s
 * *Alert hooks* — webhook, email, or chat notifications when a cap is approached or exceeded.
 * *Multi-tenant cap-setting* — per-tenant caps with override semantics.
 
-Until those features ship, treat the dashboard and breakdown queries as your visibility layer and use platform-level guardrails (xref:governance:guardrails.adoc[Configure guardrails]) for selective request blocking.
+Until those features ship, treat the dashboard and breakdown queries as your visibility layer and use platform-level guardrails (xref:governance:guardrails/index.adoc[Configure guardrails]) for selective request blocking.
 
 // TODO: once the cap-management surface lands, replace this section with a forward link to the configuration how-to. If cap-management content grows beyond a single section, split this page into a sub-folder. Open Q C1 in the companion plan.
 
diff --git a/modules/mcp/pages/register-remote.adoc b/modules/mcp/pages/register-remote.adoc
@@ -128,7 +128,6 @@ If the tools list is empty or stale, hit the *Refresh tools* action on the Overv
 
 |TLS errors when registering an `https://` URL
 |Confirm the server's certificate chains to a public CA (or the CA Redpanda's egress trusts). Self-signed certs aren't supported.
-+
 // TODO: confirm TLS / private CA story for the standalone ADP product surface.
 
 |`401 Unauthorized` from the upstream
diff --git a/modules/observability/pages/ingest-custom-traces.adoc b/modules/observability/pages/ingest-custom-traces.adoc
@@ -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:manage:rpk/rpk-install.adoc[`rpk`] installed
+* The latest version of xref:redpanda-cloud:manage:rpk/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)^]
 
@@ -60,11 +60,11 @@ For non-LangChain applications or custom instrumentation, continue with the sect
 
 Custom agents are applications with OpenTelemetry instrumentation that operate independently of Redpanda's Remote MCP servers or declarative agents (such as LangChain, CrewAI, or manually instrumented applications).
 
-When these agents send traces to `redpanda.otel_traces`, you gain unified observability alongside Remote MCP server and declarative agent traces. See xref:ai-agents:observability/concepts.adoc#cross-service-transcripts[Cross-service transcripts] for details on how traces correlate across services.
+When these agents send traces to `redpanda.otel_traces`, you gain unified observability alongside Remote MCP server and declarative agent traces. See xref:observability:concepts.adoc#cross-service-transcripts[Cross-service transcripts] for details on how traces correlate across services.
 
 === Trace format requirements
 
-Custom agents must emit traces in OTLP format. The xref:develop:connect/components/inputs/otlp_http.adoc[`otlp_http`] input accepts both OTLP Protobuf (`application/x-protobuf`) and JSON (`application/json`) payloads. For <<use-grpc,gRPC transport>>, use the xref:develop:connect/components/inputs/otlp_grpc.adoc[`otlp_grpc`] input.
+Custom agents must emit traces in OTLP format. The xref:redpanda-connect:components:inputs/otlp_http.adoc[`otlp_http`] input accepts both OTLP Protobuf (`application/x-protobuf`) and JSON (`application/json`) payloads. For <<use-grpc,gRPC transport>>, use the xref:redpanda-connect:components:inputs/otlp_grpc.adoc[`otlp_grpc`] input.
 
 Each trace must follow the OTLP specification with these required fields:
 
@@ -96,7 +96,7 @@ Optional but recommended fields:
 - `parentSpanId` for hierarchical traces
 - `attributes` for contextual information
 
-For complete trace structure details, see xref:ai-agents:observability/concepts.adoc#understand-the-transcript-structure[Understand the transcript structure].
+For complete trace structure details, see xref:observability:concepts.adoc#understand-the-transcript-structure[Understand the transcript structure].
 
 == Configure the ingestion pipeline
 
@@ -573,15 +573,15 @@ After your custom agent sends traces through the pipeline, they appear in the *T
 
 ==== Identify custom agent transcripts
 
-Custom agent transcripts are identified by the `service.name` resource attribute, which differs from Redpanda's built-in services (`ai-agent` for declarative agents, `mcp-{server-id}` for MCP servers). See xref:ai-agents:observability/concepts.adoc#cross-service-transcripts[Cross-service transcripts] to understand how the `service.name` attribute identifies transcript sources.
+Custom agent transcripts are identified by the `service.name` resource attribute, which differs from Redpanda's built-in services (`ai-agent` for declarative agents, `mcp-{server-id}` for MCP servers). See xref:observability:concepts.adoc#cross-service-transcripts[Cross-service transcripts] to understand how the `service.name` attribute identifies transcript sources.
 
 Your custom agent transcripts display with:
 
 * **Service name** in the service filter dropdown (from your `service.name` resource attribute)
 * **Agent name** in span details (from the `gen_ai.agent.name` attribute)
 * **Operation names** like `"invoke_agent my-assistant"` indicating agent executions
 
-For detailed instructions on filtering, searching, and navigating transcripts in the UI, see xref:ai-agents:observability/transcripts.adoc[View Transcripts].
+For detailed instructions on filtering, searching, and navigating transcripts in the UI, see xref:observability:transcripts.adoc[View Transcripts].
 
 ==== Token usage tracking
 
@@ -619,7 +619,7 @@ If requests succeed but traces do not appear in `redpanda.otel_traces`:
 
 == Next steps
 
-* xref:ai-agents:observability/transcripts.adoc[]
-* xref:ai-agents:agents/monitor-agents.adoc[Observability for declarative agents]
-* xref:develop:connect/components/inputs/otlp_http.adoc[OTLP HTTP input reference]
-* xref:develop:connect/components/inputs/otlp_grpc.adoc[OTLP gRPC input reference]
+* xref:observability:transcripts.adoc[]
+* xref:agents:monitor.adoc[Observability for declarative agents]
+* xref:redpanda-connect:components:inputs/otlp_http.adoc[OTLP HTTP input reference]
+* xref:redpanda-connect:components:inputs/otlp_grpc.adoc[OTLP gRPC input reference]
diff --git a/modules/observability/pages/transcripts.adoc b/modules/observability/pages/transcripts.adoc
@@ -8,7 +8,7 @@
 
 Use the Transcripts view to read a complete record of an agent or MCP server execution, turn by turn. Each transcript captures the conversation between the user, the agent, any LLM calls, and any tools it invoked, along with token usage, USD cost, latency, and any errors.
 
-For conceptual background on the underlying OpenTelemetry data model, see xref:ai-agents:observability/concepts.adoc[].
+For conceptual background on the underlying OpenTelemetry data model, see xref:observability:concepts.adoc[].
 
 After reading this page, you will be able to:
 
@@ -41,7 +41,7 @@ Each row in the list represents one execution (one trace). Columns include:
 * *USD cost* — total cost for the execution, derived from per-model pricing. See <<troubleshooting>> if this column shows `0`.
 * *Duration* — wall-clock time between the first and last span.
 
-A transcript marked _reconstructed_ is one in which some turns were rebuilt from LLM message context after the original spans were evicted from `redpanda.otel_traces`. See xref:ai-agents:observability/concepts.adoc#history-reconstruction[Reconstructed transcript history] for what that means.
+A transcript marked _reconstructed_ is one in which some turns were rebuilt from LLM message context after the original spans were evicted from `redpanda.otel_traces`. See xref:observability:concepts.adoc#history-reconstruction[Reconstructed transcript history] for what that means.
 
 // TODO: Confirm final column list on the GA Console UI. Today's labels likely shift. Verify against adp-production before merge.
 
@@ -102,7 +102,7 @@ Turns are listed in order by role:
 * *ASSISTANT* — a response from the LLM. Shows the model, input/output token counts, USD cost for that turn, and latency. If the assistant turn called a tool, its tool calls are nested underneath.
 * *TOOL* — a tool invocation. Shows the tool name, the arguments passed, the result, and the latency of the call.
 
-Any turn may carry the `is_reconstructed` marker. Reconstructed turns preserve role order and the high-level content of the conversation but do not carry per-turn token counts, latency, or tool-call arguments. See xref:ai-agents:observability/concepts.adoc#history-reconstruction[Reconstructed transcript history] for the mechanics.
+Any turn may carry the `is_reconstructed` marker. Reconstructed turns preserve role order and the high-level content of the conversation but do not carry per-turn token counts, latency, or tool-call arguments. See xref:observability:concepts.adoc#history-reconstruction[Reconstructed transcript history] for the mechanics.
 
 === Errors
 
@@ -148,7 +148,7 @@ If the failure happened during a tool call, the error is attached to the TOOL tu
 == Limitations
 
 * Large time windows sample the list to keep the UI responsive. The exact transcript you need may not be in the current page; narrow the time range or add filters.
-* Reconstructed turns do not carry token counts, latency, or tool-call arguments for the reconstructed range. For byte-level fidelity, lower the ingestion lag or extend `redpanda.otel_traces` retention (see xref:ai-agents:observability/concepts.adoc#opentelemetry-traces-topic[How Redpanda stores trace data]).
+* Reconstructed turns do not carry token counts, latency, or tool-call arguments for the reconstructed range. For byte-level fidelity, lower the ingestion lag or extend `redpanda.otel_traces` retention (see xref:observability:concepts.adoc#opentelemetry-traces-topic[How Redpanda stores trace data]).
 * USD cost is only populated for models covered by the pricing table.
 // TODO: List which providers/models are priced at GA and what users see for un-priced ones (`0`, `null`, or an explicit "unknown" marker).
 // TODO: If the GA Console UI ships transcript export, document the entry point and output format here; otherwise omit.
@@ -165,7 +165,7 @@ A transcript stays in `RUNNING` until the root span closes. Common causes:
 
 === USD cost shows 0
 
-`TranscriptUsage.usd_cost` is populated by the cost-reporting pipeline from the `gen_ai.usage.*` attributes on each LLM-call span combined with a per-model pricing table. For the full list of cost-bearing attributes (including the explicit USD-cost fields), see xref:ai-agents:observability/concepts.adoc#key-attributes-by-layer[Key attributes by layer].
+`TranscriptUsage.usd_cost` is populated by the cost-reporting pipeline from the `gen_ai.usage.*` attributes on each LLM-call span combined with a per-model pricing table. For the full list of cost-bearing attributes (including the explicit USD-cost fields), see xref:observability:concepts.adoc#key-attributes-by-layer[Key attributes by layer].
 // TODO: Document which providers/models are priced at GA.
 
 If cost is `0` for a transcript that clearly used tokens, check:
diff --git a/modules/observability/partials/transcripts-ui-guide.adoc b/modules/observability/partials/transcripts-ui-guide.adoc
@@ -23,8 +23,8 @@
 //     Valid values: "agent" | "mcp"
 //
 // DEPENDENCIES:
-//   - xref:ai-agents:observability/concepts.adoc#agent-trace-hierarchy[]
-//   - xref:ai-agents:observability/concepts.adoc#mcp-server-trace-hierarchy[]
+//   - xref:observability:concepts.adoc#agent-transcript-hierarchy[]
+//   - xref:observability:concepts.adoc#mcp-server-transcript-hierarchy[]
 //
 // CONTENT TYPE:
 //   UI navigation and interface explanation (procedural context for how-to pages)
@@ -66,10 +66,10 @@ The trace list shows nested operations with visual duration bars indicating how
 
 // Link to appropriate concepts section based on context
 ifeval::["{context}" == "agent"]
-For details on span types, see xref:ai-agents:observability/concepts.adoc#agent-trace-hierarchy[Agent trace hierarchy].
+For details on span types, see xref:observability:concepts.adoc#agent-transcript-hierarchy[Agent transcript hierarchy].
 endif::[]
 ifeval::["{context}" == "mcp"]
-For details on span types, see xref:ai-agents:observability/concepts.adoc#mcp-server-trace-hierarchy[MCP server trace hierarchy].
+For details on span types, see xref:observability:concepts.adoc#mcp-server-transcript-hierarchy[MCP server transcript hierarchy].
 endif::[]
 
 ==== Summary panel
@@ -91,6 +91,6 @@ ifeval::["{context}" == "mcp"]
 * Service: The MCP server identifier
 endif::[]
 
-If any turns were rebuilt from LLM message context after their original spans were evicted, the panel shows a _reconstructed_ marker on those turns. For the mechanics, see xref:ai-agents:observability/concepts.adoc#history-reconstruction[Reconstructed transcript history].
+If any turns were rebuilt from LLM message context after their original spans were evicted, the panel shows a _reconstructed_ marker on those turns. For the mechanics, see xref:observability:concepts.adoc#history-reconstruction[Reconstructed transcript history].
 
 // TODO: Re-verify this field list against the GA Console UI on adp-production. Beta labels may shift; update wording before GA.
