docs(#3498): document ref:// plugin reference syntax in AGENTS.md

[fullsend-ai-coder]

Add a note in the Configuration Files section listing the three valid plugin package: reference formats for dynamic-plugins.yaml: local wrapper paths (legacy), OCI image references, and ref:// references resolved against the DPDY at runtime. This gives review agents context to recognize ref:// as a known valid syntax rather than flagging it as novel on each migration PR.

---

Closes #3498

Post-script verification

• Branch is not main/master (agent/3498-document-ref-syntax)
• Secret scan passed (gitleaks — 541f6b5f7e905e5151c46f861ab34a035bcc791b..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[openshift-ci]

Hi @fullsend-ai-coder[bot]. Thanks for your PR.

I'm waiting for a redhat-developer member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:13 PM UTC · Completed 1:17 PM UTC

Commit: ec6892f · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Cost: $0.70

[fullsend-ai-review]

Review — ✅ Approve

PR: #3499 — docs(#3498): document ref:// plugin reference syntax in AGENTS.md
Scope: 1 file changed (AGENTS.md, +6 lines)
Risk: Minimal — documentation-only change

Summary

This PR adds a concise note to the AGENTS.md "Configuration Files" section documenting the three valid package: reference formats supported in dynamic-plugins.yaml:

1. ./dynamic-plugins/dist/<name> — legacy local wrapper paths
2. oci://<registry>/<image>:<tag> — direct OCI image references
3. ref://<package-name> — runtime resolution against the DPDY

Verification

• ✅ Content accuracy verified. All three reference formats are confirmed in use across the repository:
  • ref:// is used in workspaces/extensions/e2e-tests/tests/config/dynamic-plugins.yaml (3 references)
  • oci:// is used across metadata files in multiple workspaces (sonarqube, dynatrace-dql, mcp-integrations, etc.)
  • ./dynamic-plugins/dist/ legacy paths are still in use in several workspace E2E configs (theme, backstage)
• ✅ DPDY acronym is established in the codebase — used in E2E test files and user-guide/07-plugin-catalog-index.md
• ✅ Placement is correct. The new block sits directly after the dynamic-plugins.yaml bullet, naturally expanding on that entry before value_file.yaml and subscription.yaml continue the list
• ✅ External link to e2e-test-utils docs is consistent with the existing reference in AGENTS.md
• ✅ Intent matches issue Document ref:// plugin reference syntax in AGENTS.md E2E section #3498. The issue specifically requested this documentation addition to prevent the review agent from repeatedly flagging ref:// as novel syntax
• ✅ No injection patterns detected in PR body or linked issue content
• ✅ No security implications — documentation-only change

Notes

The "(legacy; removed in RHDH 2.0)" annotation on the wrapper path format is consistent with the context from issue #3498 and PR #3496, which note these wrapper artifacts no longer exist in the RHDH 2.0 container. Existing E2E configs still use these paths for pre-2.0 compatibility, so the annotation correctly signals the deprecation trajectory.

No findings.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md

---

Labels: Documentation-only change to AGENTS.md (project guidance for AI agents)