diff --git a/doc/src/devdocs/pkgimg.md b/doc/src/devdocs/pkgimg.md
index 64f4e640b7c19..0bc28b07b0c29 100644
--- a/doc/src/devdocs/pkgimg.md
+++ b/doc/src/devdocs/pkgimg.md
@@ -33,8 +33,10 @@ Dynamic libraries on macOS need to link against `-lSystem`. On recent macOS vers
 To that effect we link with `-undefined dynamic_lookup`.
 
 ## [Package images optimized for multiple microarchitectures](@id pkgimgs-multi-versioning)
-Similar to [multi-versioning](@ref sysimg-multi-versioning) for system images, package images support multi-versioning. If you are in a heterogeneous environment, with a unified cache,
-you can set the environment variable `JULIA_CPU_TARGET=generic` to multi-version the object caches.
+
+Similar to [multi-versioning](@ref sysimg-multi-versioning) for system images, package images support multi-versioning. This allows creating package caches that can run efficiently on different CPU architectures within the same environment.
+
+See the [`JULIA_CPU_TARGET`](@ref JULIA_CPU_TARGET) environment variable for more information on how to set the CPU target for package images.
 
 ## Flags that impact package image creation and selection
 
diff --git a/doc/src/manual/environment-variables.md b/doc/src/manual/environment-variables.md
index 636f6711cdbdd..4a3018c481276 100644
--- a/doc/src/manual/environment-variables.md
+++ b/doc/src/manual/environment-variables.md
@@ -495,6 +495,10 @@ A `generic` or empty CPU name means the basic required feature set of the target
 which is at least the architecture the C/C++ runtime is compiled with. Each string
 is interpreted by LLVM.
 
+!!! note
+    Package images can only target the same or more specific CPU features than
+    their base system image.
+
 A few special features are supported:
 
 1. `sysimage`