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 to align development workflow with frontend tooling and formalize plugin architecture guidance. Development instructions now reference frontend-specific yarn commands; architecture documentation expanded with JSON-based extension schema and refined API stability considerations; conventions shifted to prioritize core package implementation with SDK re-export pattern and updated i18n practices.

Changes

Cohort / File(s)	Summary
Development Setup Instructions AGENTS.md	Development workflow updated from top-level make targets to frontend-specific yarn commands (install, dev, lint, test, build); added explicit ./build.sh invocation for full builds
Plugin Architecture & Development Guidelines ARCHITECTURE.md, CONVENTIONS.md	ARCHITECTURE.md expanded with formalized JSON-based extension schema (console-extensions.json JSONC format), refined type naming conventions (console.\*), and strengthened API stability/backward-compatibility guidance; CONVENTIONS.md shifted to prefer core package implementation with SDK re-export over direct SDK development, and updated i18n patterns from namespace-key format to function-based approach

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 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 8ed410b and 14beb76.

📒 Files selected for processing (3)

• AGENTS.md
• ARCHITECTURE.md
• CONVENTIONS.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:

• CONVENTIONS.md
• AGENTS.md
• ARCHITECTURE.md

🔇 Additional comments (9)

CONVENTIONS.md (3)

15-16: ✓ Clear SDK re-export guidance.

The updated guidance aligns the plugin architecture with the broader PR objectives. Directing developers to implement features in core packages first and then expose via SDK re-export (with stabilization emphasis) establishes clear separation of concerns and backward compatibility considerations.

---

38-38: ✓ ES6+ practices well-defined.

The explicit enumeration of modern JavaScript practices (const/let, arrow functions, async/await, destructuring, template literals, optional chaining) provides clear, actionable guidance for developers.

---

18-18: No action needed. The i18n patterns documented in CONVENTIONS.md and ARCHITECTURE.md serve different purposes and are not inconsistent. CONVENTIONS.md documents the React component pattern (useTranslation('namespace') hook with plain key format) for runtime code, while ARCHITECTURE.md documents the static JSON configuration pattern (%namespace~key% format) for console-extensions.json files. Both formats are correct and complementary for their respective contexts.

Likely an incorrect or invalid review comment.

ARCHITECTURE.md (5)

9-16: ✓ Core packages clearly organized.

Addition of console-app and console-internal as explicit core areas clarifies the architecture hierarchy and improves navigation for developers implementing features or reviewing code.

---

35-75: ✓ JSON schema format clearly documented.

The console-extensions.json format with practical examples (page/route, navigation/href, perspective) and key concepts (file location, type naming, code references) provides a solid foundation for plugin developers. The shift from inline code examples to a declarative JSON schema improves maintainability and clarity.

---

84-92: ✓ Public API re-export governance strengthened.

Explicit enumeration of re-exported packages (@console/shared, @console/internal, @console/plugin-sdk, @console/app) with clear warning about verification before modifications establishes strong governance for SDK stability. The directive to review frontend/packages/console-dynamic-plugin-sdk/src/api/ provides a concrete path for verification.

---

99-105: ✓ SDK development guidelines are clear and properly referenced.

The SDK-Specific guidelines appropriately emphasize backward compatibility as a public API, and the link to .claude/commands/plugin-api-review.md is present and valid, directing developers to detailed review procedures.

---

69-74: No changes needed - no i18n format inconsistency exists.

ARCHITECTURE.md line 73 correctly describes the %namespace~key% format used in console-extensions.json files. CONVENTIONS.md line 18 describes the useTranslation('namespace') hook used in React component code. These are complementary patterns for different layers: the JSON manifest uses declarative %namespace~key% strings that the console runtime resolves, while component code uses the useTranslation() hook for runtime translation. Actual plugin examples (dev-console, helm-plugin) confirm the %namespace~key% format is the correct approach for JSON manifests.

Likely an incorrect or invalid review comment.

AGENTS.md (1)

22-22: ✓ All documented frontend yarn commands and build.sh are properly configured.

Migration from make targets to yarn commands with explicit cd frontend context is accurate. All documented commands exist in frontend/package.json: install, dev, lint, test, build, and i18n. The ./build.sh full-build script exists at repo root. Documentation aligns with actual tooling setup.

---

_{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.

[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.

[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

[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