NO-JIRA: docs: update api-sme agent and api/AGENTS.md conventions

.claude/agents/api-sme.md

@@ -13,10 +13,10 @@ You are an API subject matter expert system architect specializing in HCP.
 - Basic security patterns (auth, rate limiting)
 
 ## Approach
-1. Follow OpenShift dev guides from https://github.com/openshift/enhancements/tree/master/dev-guide
-2. Apply best practices from https://github.com/openshift/enhancements/blob/master/dev-guide/api-conventions.md
-3. Consider any API stable, running in production and ensure any API change is backward compatible
-4. Keep it simple - avoid premature optimization
+
+**MANDATORY**: Before writing any review, you MUST run `make api-lint-fix` and include its output in your review. Do not skip this step. The linter is the authoritative source for convention violations. Your review must start with the linter findings, then add your own analysis on top.
+
+Stick to ../api/AGENTS.md
 
 ## Output
 - API definitions that align with OpenShift and Kubernetes best practices

api/AGENTS.md

@@ -15,24 +15,6 @@ For conventions, always trust the kube-api-linter (`make api-lint-fix`). Do not
 - Use feature gates for experimental functionality
 - CRD generation via controller-gen with OpenShift-specific tooling
 
-Key make targets for API work:
-
-```bash
-make api               # Regenerate all CRDs, deepcopy, clients
-make api-lint-fix      # Run API linter and auto-fix violations
-make verify-api-deps   # Verify API dependencies
-make verify            # Full verification (includes api, fmt, vet, lint)
-make update            # Full update (api-deps, workspace-sync, deps, api, api-docs, clients)
-ENVTEST_OCP_K8S_VERSIONS=1.35.0 make test-envtest-ocp # Run envtest for CEL validations
-```
-
-### API Dependencies
-
-It is imperative that the imported dependencies are kept minimal. Use `make verify-api-deps` to verify that the dependencies are allowed.
-New dependencies must be approved by API reviewers and added to `api/.imports_allowed`.
-
-To avoid introducing new dependencies, do not add utils or methods to the API types.
-
 ### Serialization
 
 - **Always set `omitempty` or `omitzero` on every field, regardless of whether it is `+required` or `+optional`.** `omitempty`/`omitzero` tags control serialization, not validation. `+required` is a schema constraint enforced at admission time; the serialization tag controls what goes on the wire. Without a tag, a zero-value field serializes as an explicit value (e.g., `"pullSecret": {"name": ""}`), which makes the API server unable to distinguish "not set" from "explicitly set to empty." This breaks defaulting, server-side apply field ownership, and strategic merge patch — all of which rely on field absence to mean "don't touch this." Additionally, without omission a structured client serializes the empty object, which passes the `+required` check (based on key presence) without validating the value — so a user can forget to set a required field, it passes admission, and the reader sees a required field with an unexpected empty value.
@@ -57,6 +39,16 @@ To avoid introducing new dependencies, do not add utils or methods to the API ty
 
 ## API Type Change Guidelines
 
+### Best Practices and Patterns
+
+Use api/karpenter/v1beta1/karpenter_types.go and api/hypershift/v1beta1/etcdbackup_types.go as examples of best practices and patterns.
+
+Don't use the other existing APIs as examples as they might have many legacy constraints.
+
+### Field Grouping
+
+**When multiple fields on a spec share a common prefix or relate to the same feature, they MUST be grouped into a dedicated struct.** Top-level specs like HostedClusterSpec and NodePoolSpec should only contain fields that are independently meaningful. If removing one field would make another field meaningless, they belong together in a sub-struct. A common signal is fields that share a name prefix (e.g., `BarEndpoint`, `BarConfig`, `BarID` all relate to "Bar" and should be a single `Bar` field with a `BarSpec` struct).
+
 ### N-1 and N+1 Compatibility
 
 Every change to an API type must be safe for both:
@@ -85,3 +77,16 @@ See `api/hypershift/v1beta1/nodepool_types_test.go` for an example of this patte
 
 All API CEL validations must be covered with envtests, see test/envtest/README.md for details
 
+#### Key make targets for API work:
+
+```bash
+make api               # Regenerate all CRDs, deepcopy, clients
+make api-lint-fix      # Run API linter and auto-fix violations
+make verify            # Full verification (includes api, fmt, vet, lint)
+make update            # Full update (api-deps, workspace-sync, deps, api, api-docs, clients)
+make test-envtest-ocp  # Run envtest for CEL validations
+# To target a specific k8s version, check api/go.mod (e.g. k8s.io/api v0.35.1 → 1.35):
+# ENVTEST_OCP_K8S_VERSIONS=1.35.0 make test-envtest-ocp
+```
+
+All these must pass for any change before creating a PR