auto-docs: Update CRD reference doc

modules/reference/pages/k-crd.adoc

@@ -1374,7 +1374,7 @@ PostInstallJob configures configurations for the post-install job that run after
 | *`enabled`* __boolean__ | Specifies whether the job is deployed. +
 | *`labels`* __object (keys:string, values:string)__ | Applies labels to the job to facilitate identification and selection based on custom criteria. +
 | *`affinity`* __invalid type__ | Affinity constraints for scheduling Pods. For details, see the +
-[Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity). +
+https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity[Kubernetes' documentation]. +
 | *`securityContext`* __invalid type__ | SecurityContext is deprecated. Prefer [PodTemplate.Spec.SecurityContext] +
 or [PodTemplate.Spec.Containers[*].SecurityContext]. +
 | *`podTemplate`* __xref:{anchor_prefix}-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-podtemplate[$$PodTemplate$$]__ | PodTemplate is a subset of Kubernetes' PodTemplate that will be merged +
@@ -1403,7 +1403,7 @@ PostUpgradeJob configures configurations for the post-upgrade job that run after
 | *`resources`* __invalid type__ | Sets resource requirements (CPU, memory) for the job to ensure proper allocation and limit resource usage. +
 | *`backoffLimit`* __integer__ | 
 | *`affinity`* __invalid type__ | Affinity constraints for scheduling Pods. For details, see the +
-[Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity). +
+https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity[Kubernetes' documentation]. +
 | *`securityContext`* __invalid type__ | SecurityContext is deprecated. Prefer [PodTemplate.Spec.SecurityContext] +
 or [PodTemplate.Spec.Containers[*].SecurityContext]. +
 | *`podTemplate`* __xref:{anchor_prefix}-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-podtemplate[$$PodTemplate$$]__ | PodTemplate is a subset of Kubernetes' PodTemplate that will be merged +
@@ -1859,7 +1859,30 @@ ResourceType specifies the type of resource an ACL is applied to.
 [id="{anchor_prefix}-github-com-redpanda-data-redpanda-operator-operator-api-redpanda-v1alpha2-resources"]
 == Resources 
 
-Resources configures resource allocation. The default values are for a development environment. Production-level values and other considerations are documented, where those values are different from the default.
+RedpandaResources encapsulates the calculation of the redpanda container's
+https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core[corev1.ResourceRequirements]
+and parameters such as `--memory`, `--reserve-memory`, and `--smp`. This
+calculation supports two modes:
+
+
+  - Explicit mode (recommended):  Activated when `Limits` and `Requests` are
+    set. In this mode, the CLI flags are calculated directly based on the
+    provided `Limits` and `Requests`. This mode ensures predictable resource
+    allocation and is recommended for production environments. If additional
+    tuning is required, the CLI flags can be manually overridden using
+    `statefulset.additionalRedpandaCmdFlags`.
+
+
+  - Legacy mode (default): Used when `Limits` and `Requests` are not set.
+    In this mode, the container resources and CLI flags are calculated using
+    built-in default logic, where 80% of the container's memory is allocated
+    to Redpanda and the rest is reserved for system overhead. Legacy mode is
+    intended for backward compatibility and less controlled environments.
+
+
+Explicit mode offers better control and aligns with Kubernetes best
+practices. Legacy mode is a fallback for users who have not defined `Limits`
+and `Requests`.