@@ -4,6 +4,8 @@ A Virtual Machine Disk
 
 > `storageClass` and `source` are annotated as immutable in the chart schema — see [`docs/storage-immutability.md`](../../../docs/storage-immutability.md) for the contract and which consumers enforce it. `DataVolume.spec` is immutable in CDI, so the chart also fails the release on an attempted `storageClass`/`source` edit of an existing disk rather than silently reusing the old spec; delete and recreate the disk to change either field.
 
+> Whether CDI has finished populating the disk shows up in the `WorkloadsReady` condition, not in `Ready`, which follows the Helm release and does not wait on the DataVolume: `WorkloadsReady` stays `False` while an import or clone is in flight and when the DataVolume fails. A disk created before this behaviour was introduced keeps its old release settings, under which `Ready` may wait on the DataVolume, until its application is next updated. A disk counts as ready while it waits for its consumer with `bindImmediately` off on a `WaitForFirstConsumer` class, and while a `source.upload` disk waits for `virtctl image-upload`, because both are states such a disk is supposed to rest in.
+
 > `bindImmediately` is on by default, so a disk's volume is provisioned when the disk is created rather than deferred to the first consumer. That default exists because a VMDisk is a standalone object with a lifecycle of its own: on a `WaitForFirstConsumer` StorageClass a disk that no VM has attached yet would otherwise never populate at all. It costs something on a node-pinned class such as `local`, where the CDI worker pod becomes the first consumer and the volume lands where that pod was scheduled rather than where the VM will run, so a VM whose placement is constrained (a `nodeSelector`, a resource request only one node satisfies, or the Windows affinity applied by `_cluster.scheduling.dedicatedNodesForWindowsVMs`) can stay unschedulable against a node-affinity conflict, and `storageClass` is immutable so the only exit is deleting and recreating the disk. Turn `bindImmediately` off for a disk a VMInstance will consume on such a class: KubeVirt then renders a temporary launcher pod carrying the VM's own affinity and node selector, and the volume binds where the VM can actually run. The chart default `replicated` binds `Immediate` regardless, so neither setting changes anything there.
 
 ## Parameters