OCPBUGS-72557: Address logonoff review comments on AI documentation

[sg00dwin]

Fix outdated extension system examples, replace make commands with yarn scripts, clarify SDK re-export architecture, and reduce duplication by referencing authoritative sources.
Assisted-by Claude code

[openshift-ci-robot]

@sg00dwin: This pull request references Jira Issue OCPBUGS-72557, which is valid. The bug has been moved to the POST state.

3 validation(s) were run on this bug

• bug is open, matching expected state (open)
• bug target version (4.22.0) matches configured target version for branch (4.22.0)
• bug is in the state New, which is one of the valid states (NEW, ASSIGNED, POST)

Requesting review from QA contact:
/cc @yapei

The bug has been updated to refer to the pull request using the external bug tracker.

Details

In response to this:

Fix outdated extension system examples, replace make commands with yarn scripts, clarify SDK re-export architecture, and reduce duplication by referencing authoritative sources.
Assisted-by Claude code

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 openshift-eng/jira-lifecycle-plugin repository.

[coderabbitai]

Walkthrough

Three documentation files updated: development commands now reference frontend yarn workflows; architecture docs formalize JSONC-based plugin extension schema, naming and SDK guidance; conventions updated to prefer core package implementation with SDK re-exports and revised i18n usage.

Changes

Cohort / File(s)	Summary
Development Setup Instructions AGENTS.md	Replaced top-level make targets with frontend-scoped commands (`cd frontend && yarn install
Plugin Architecture & Extension Schema ARCHITECTURE.md	Reworked dynamic plugin guidance to use console-extensions.json (JSONC) as canonical extension source; converted inline TS extension examples to JSONC console.* typed entries and $codeRef lazy-load patterns; expanded extension types summary and public API re-export verification guidance.
Conventions & i18n / SDK Guidance CONVENTIONS.md	Changed recommendation from default SDK-first to prefer implementing in core packages then re-export to SDK; updated i18n guidance from %namespace~key% to useTranslation('namespace') usage; expanded ES6+ / modern JS guidance.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

---

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to data retention organization setting

Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting

📥 Commits

Reviewing files that changed from the base of the PR and between 14beb76 and 6302141.

📒 Files selected for processing (2)

• AGENTS.md
• ARCHITECTURE.md

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

-Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity.

Files:

• ARCHITECTURE.md
• AGENTS.md

🔇 Additional comments (6)

ARCHITECTURE.md (4)

39-68: JSON example looks syntactically correct.

The extension definitions follow the documented console.* naming convention and demonstrate proper use of $codeRef for lazy loading and %namespace~key% for i18n strings.

---

108-108: Verify the plugin-api-review.md file exists in the .claude/commands/ directory.

The ARCHITECTURE.md references a workflow document at .claude/commands/plugin-api-review.md. Confirm this file exists and is properly linked.

---

25-29: Verify referenced documentation files exist and confirm extension type count.

The ARCHITECTURE.md lines 25-29 reference three specific SDK documentation files:

• frontend/packages/console-dynamic-plugin-sdk/README.md
• frontend/packages/console-dynamic-plugin-sdk/docs/console-extensions.md
• frontend/packages/console-dynamic-plugin-sdk/docs/api.md

Additionally, the claim of "75+ extension types" should be verified by counting actual extension type definitions in the codebase.

Run the provided verification script to confirm file existence and validate the extension type count before merging.

---

87-94: Update the verification directive to include all SDK re-export source files.

The internal-*.ts pattern is incomplete. While it captures re-exports from @console/shared, @console/topology, and @console/dynamic-plugin-sdk, it misses useResolvedExtensions.ts which contains the @console/plugin-sdk re-export. Additionally, internal-types.ts contains only type definitions, not actual re-exports.

For accurate verification of all listed packages, check: frontend/packages/console-dynamic-plugin-sdk/src/api/internal-api.ts, internal-console-api.ts, internal-topology-api.ts, and useResolvedExtensions.ts.

Likely an incorrect or invalid review comment.

AGENTS.md (2)

22-34: LGTM! Yarn commands correctly replace make targets.

The transition from make commands to yarn scripts is consistent and correct. All frontend commands properly navigate to the frontend directory before executing, and the full build path (./build.sh) is appropriately distinguished from frontend-only builds.

---

72-73: Verify the SDK README file path exists before approval.

The reference to frontend/packages/console-dynamic-plugin-sdk/README.md needs manual verification to confirm the file exists at this location and contains relevant plugin development documentation.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: sg00dwin
Once this PR has been reviewed and has the lgtm label, please assign spadgett for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[sg00dwin]

/verified by @sg00dwin

[openshift-ci-robot]

@sg00dwin: This PR has been marked as verified by @sg00dwin.

Details

In response to this:

/verified by @sg00dwin

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 openshift-eng/jira-lifecycle-plugin repository.

[logonoff]

I'd like to point claude to read frontend/packages/console-dynamic-plugin-sdk/README.md since it's very very detailed

you may want to reference #15398 for AGENTS.md as well

[sg00dwin]

#15398 was closed as stale. Added a comment for Sam asking if it will be picked up and merged at some point.

[logonoff]

we also export from topology plugin, maybe it's safer to just ask it to check every time..? but may be an unneeded use of tokens

[openshift-ci]

@sg00dwin: all tests passed!

Full PR test history. Your PR dashboard.

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. I understand the commands that are listed here.