docs(user): document the machine type each accelerator criterion targets

docs/user/cli-reference.md

@@ -466,6 +466,13 @@ Generate recipes using direct system parameters:
 | `--data` | | string | External data directory to overlay on embedded data (see [External Data](#external-data-directory)) |
 | `--criteria-strict` | | bool | Reject criteria values not in the embedded OSS catalog; ignores values registered from `--data`. Also honored via `AICR_CRITERIA_STRICT=1` or `spec.recipe.criteriaStrict: true` in `--config`. Intended for OSS CI gates. |
 
+**Accelerator values name a GPU model, not a machine type.** A provider
+usually offers several machine types for the same GPU, and the machine type —
+not the GPU — determines the fabric, the NIC count, and which components a
+recipe can use. `--accelerator h100` therefore does not, on its own, say which
+node shape the resolved recipe targets. See
+[Qualified Machine Types](#qualified-machine-types) below.
+
 > **Service / Accelerator / OS / Intent / Platform value listings above are the OSS-embedded set.** When `--data` registers additional values (e.g., undisclosed providers, proprietary platforms), the CLI admits them at runtime through the criteria registry — see [Data Extension](../integrator/data-extension.md). `--criteria-strict` restores the OSS-only set regardless of what `--data` contributes.
 
 **Examples:**
@@ -510,6 +517,60 @@ proceeds for compatibility. Use a current snapshot before deployment when you
 need conflict detection. See
 [Conflict detection requires snapshot evidence](slinky-slurm-accounting.md#conflict-detection-requires-snapshot-evidence).
 
+#### Qualified Machine Types
+
+Each recipe is qualified against a specific node shape. Criteria resolution
+does not reject another machine type of the same GPU model — there is no axis
+to reject it on — so a recipe always resolves. What differs by family is what
+happens afterwards: on some, deployment validation fails; on others it succeeds
+and only the performance gates are affected.
+
+| Accelerator | Service / intent | Qualified machine type | On other shapes of the same GPU |
+|---|---|---|---|
+| `h100` | `gke`, `training` | `a3-megagpu-8g` | **Components do not schedule.** The GPUDirect-TCPXO DaemonSets pin node affinity to `cloud.google.com/gke-accelerator: nvidia-h100-mega-80gb`, so on `a3-highgpu-*` / `a3-edgegpu-8g` nothing rolls out and the deployment health check fails. AICR ships no GPUDirect-TCPX component for the shapes that need one — tracked in [#2290](https://github.com/NVIDIA/aicr/issues/2290). |
+| `h100` | `gke`, `inference` | not machine-type-bound (`dynamo` floors calibrated on `a3-megagpu-8g`) | Deploys. The inference lineage carries no `gke-nccl-tcpxo` component, so the hard failure above does not apply. Plain `inference` declares no performance gates at all; the `dynamo` variant adds floors calibrated on the 8-GPU node, so smaller shapes such as `a3-highgpu-1g/2g/4g` can false-fail there. |
+| `h100` | `eks` | `p5.48xlarge` (8× H100 SXM, 32× EFA) | Deploys, but performance floors are calibrated on the full node; smaller shapes such as `p5.4xlarge` can false-fail a healthy run. |
+| `h100` | `aks` | `Standard_ND96isr_H100_v5` (8× H100 SXM, InfiniBand) | **Deployment fails on the non-IB NCads shapes.** The AKS chain wires `network-operator` with a NicClusterPolicy unconditionally, so the deployment-phase `expected-resources` check runs an RDMA-fabric readiness gate that fails closed. `Standard_NC80adis_H100_v5` (2 GPUs) and `Standard_NC40ads_H100_v5` (1 GPU) are PCIe H100 with no InfiniBand, so they never advertise the shared RDMA resource and the gate fails before any performance gate runs. Opt out at bundle time with `--set networkoperator:enabled=false`. |
+| `gb200` | `eks` | `p6e-gb200.36xlarge` (4 GPUs per K8s node) | Deploys; floors are sized for this shape and are themselves provisional pending production NVL72 data. |
+| `a100` | `gke` | the whole `a2` family (`a2-highgpu-*`, `a2-ultragpu-*`) | Family-level by construction, not per-shape: GPUDirect-TCPXO targets H100 `a3-megagpu-8g`, so the `gke-nccl-tcpxo` component is inapplicable to every `a2` shape and is intentionally omitted. No shape in the family carries a machine-type-bound component. |
+| `b200` | `gke` | the `a4` family — **specific machine type not recorded** | No separate NCCL plugin installer; multi-node NCCL comes from GPU Operator `gdrcopy` plus GKE `a4`'s GCP-managed multi-NIC, so nothing here is machine-type-bound. The overlay records a production reference cluster but no machine type, so this row cannot name one. |
+
+A row that names no intent applies to every intent for that accelerator and
+service. Where a row names a family rather than a machine type, the entry is a
+family-level statement — either because no component in that family binds to a
+machine type, or because the specific shape is not recorded in-repo. The row
+says which.
+
+Two distinct failure modes are worth separating:
+
+- **Component-level (hard).** Two families fail deployment outright, by
+  different mechanisms. The GKE H100 **training** lineage pins artifacts to a
+  machine type — `h100-gke-cos-training` and the leaves inheriting it — so on a
+  non-matching shape the DaemonSets have nowhere to land and a Chainsaw health
+  check fails. The AKS H100 **training** lineage instead wires an RDMA fabric
+  unconditionally, and a Go readiness gate in the deployment phase fails closed
+  when no node advertises the shared RDMA resource — which is every non-IB
+  NCads shape. Neither is a degradation; both stop the deployment phase.
+- **Performance-gate (soft).** Elsewhere the recipe deploys normally, but the
+  NCCL and inference floors are fixed absolute values calibrated on full,
+  high-bandwidth nodes. They are not normalized for GPU count or fabric class,
+  so a smaller shape can fail a gate while being perfectly healthy. This is the
+  EKS and GB200 case; on AKS the deployment gate above bites first. See
+  [Validation › Node-shape assumption](./validation.md). Normalizing these
+  floors per GPU or per fabric class was considered and declined
+  ([#1256](https://github.com/NVIDIA/aicr/issues/1256),
+  [#1254](https://github.com/NVIDIA/aicr/issues/1254), both closed as not
+  planned) — the floors are deliberately fixed absolute full-node values, so
+  running a qualified shape is the supported way to pass them.
+
+The table lists the accelerator/service pairs that have a qualified shape;
+a pair or a shape absent from it is **undocumented rather than known-broken**.
+It has not been qualified, and the criteria model has no axis that would
+distinguish it from one that has.
+Whether AICR should gain one — finer-grained accelerator values, a machine-type
+axis, or a fabric class — is tracked in
+[#2377](https://github.com/NVIDIA/aicr/issues/2377).
+
 #### Snapshot Mode
 
 Generate recipes from captured snapshots:

recipes/overlays/b200-gke-cos-training.yaml

@@ -44,8 +44,10 @@ spec:
     # enabled, combined with GKE A4's native multi-NIC infrastructure
     # managed by GCP. The `gke-nccl-tcpxo` component is intentionally
     # omitted because its DaemonSets pin to `cloud.google.com/gke-
-    # accelerator: nvidia-h100-mega-80gb` (a3-megagpu / H100) and a
-    # different transport (TCPX), so they would not run on A4 nodes.
+    # accelerator: nvidia-h100-mega-80gb` (a3-megagpu / H100) and carry a
+    # transport A4 does not use (GPUDirect-TCPXO), so they would not run on A4
+    # nodes. (TCPXO is the a3-megagpu transport; TCPX is the separate
+    # a3-highgpu/edge one. Neither applies here.)
     - name: gpu-operator
       type: Helm
       dependencyRefs:

recipes/overlays/gb200-eks-ubuntu-training.yaml

@@ -22,6 +22,11 @@ spec:
   # This overlay adds Ubuntu-specific configurations
   base: gb200-eks-training
 
+  # Machine type: qualified on p6e-gb200.36xlarge (4 GPUs per Kubernetes node).
+  # The performance floors inherited from gb200-eks-training are sized for that
+  # shape and are not normalized for GPU count, so another GB200 shape can
+  # false-fail a healthy run. Those thresholds are themselves provisional --
+  # see the parent overlay's note.
   criteria:
     service: eks
     accelerator: gb200

recipes/overlays/h100-aks-training.yaml

@@ -21,6 +21,20 @@ spec:
   # Inherits from aks-training recipe (AKS + training settings)
   base: aks-training
 
+  # Machine type: qualified on Standard_ND96isr_H100_v5 (8x H100 SXM). These
+  # criteria carry no machine-type axis, so they also match the smaller NCads
+  # H100 shapes (Standard_NC80adis_H100_v5 = 2 GPUs, Standard_NC40ads_H100_v5 =
+  # 1 GPU). Those do NOT merely under-perform: the aks base wires
+  # network-operator with a NicClusterPolicy unconditionally, so the
+  # deployment-phase expected-resources check runs verifyRDMAFabricReady, which
+  # fails closed when no node advertises the shared RDMA resource. NCads are
+  # PCIe H100 with no InfiniBand, so deployment fails before the performance
+  # floors below are ever evaluated. Opt out with
+  # `--set networkoperator:enabled=false`.
+  #
+  # On the qualified shape the floors still apply, and they are fixed absolute
+  # full-node values. Normalizing them was declined (#1256, #1254 — both closed
+  # not-planned); the qualified shape is the supported way to pass them.
   criteria:
     service: aks
     accelerator: h100

recipes/overlays/h100-eks-training.yaml

@@ -21,6 +21,14 @@ spec:
   # Inherits from eks-training recipe (EKS + training settings)
   base: eks-training
 
+  # Machine type: qualified on p5.48xlarge (8x H100 SXM, 32x EFA). These
+  # criteria carry no machine-type axis, so they also match smaller H100 shapes
+  # (e.g. p5.4xlarge). Those deploy normally — unlike the GKE leaf, no component
+  # here pins node affinity to a shape — but the performance floors below are
+  # fixed absolute values calibrated on the full node, so a smaller shape can
+  # false-fail a healthy run. Normalizing them per GPU/fabric class was declined
+  # (#1256, #1254 — both closed not-planned); the floors are deliberately
+  # absolute, so the qualified shape is the supported way to pass them.
   criteria:
     service: eks
     accelerator: h100

recipes/overlays/h100-gke-cos-training-slurm.yaml

@@ -25,6 +25,15 @@ spec:
   # `aicr bundle ... --set slinkyslurm:...` or a valuesFile.
   base: h100-gke-cos-training
 
+  # Machine type: qualified on a3-megagpu-8g only, same as the parent.
+  #
+  # Two different things carry over from `base`, and only one of them is
+  # inheritance: the gke-nccl-tcpxo componentRef is inherited by the base
+  # mechanism, while the machine-type qualification is a documented assumption
+  # that holds here because those same artifacts do. There is no machine-type
+  # axis in the criteria contract to inherit -- these criteria add none, so the
+  # parent's TCPXO-vs-TCPX selection gap applies unchanged. See the parent
+  # overlay's note and #2290.
   criteria:
     service: gke
     accelerator: h100

recipes/overlays/h100-gke-cos-training.yaml

@@ -21,6 +21,21 @@ spec:
   # Inherits from gke-cos-training recipe (GKE COS + training settings)
   base: gke-cos-training
 
+  # Machine type: this leaf is qualified on a3-megagpu-8g only.
+  #
+  # `accelerator: h100` names the GPU model, and GKE offers it on several A3
+  # machine types with different fabrics: a3-megagpu-8g uses GPUDirect-TCPXO,
+  # a3-highgpu-8g / a3-edgegpu-8g use GPUDirect-TCPX, and the smaller
+  # a3-highgpu-1g/2g/4g shapes have no GPUDirect at all. The criteria model has
+  # no axis that distinguishes them, so these criteria match all of them while
+  # the gke-nccl-tcpxo DaemonSets below pin node affinity to
+  # `cloud.google.com/gke-accelerator: nvidia-h100-mega-80gb`.
+  #
+  # On a non-mega shape nothing schedules and the deployment health check fails
+  # loudly (`desiredNumberScheduled > 0`). AICR ships no GPUDirect-TCPX
+  # component, so those shapes have no working alternative. Selection fix and a
+  # TCPX component are tracked in #2290; whether criteria should gain a
+  # machine-type or fabric axis is tracked in #2377.
   criteria:
     service: gke
     accelerator: h100