diff --git a/docs/guides/color-grading.mdx b/docs/guides/color-grading.mdx
index 4a74a8877..1c181e8a5 100644
--- a/docs/guides/color-grading.mdx
+++ b/docs/guides/color-grading.mdx
@@ -268,9 +268,13 @@ just the endpoints.
 
 Two things this list does **not** give you:
 
-- **`--hf-color-grading-intensity` does not scale a grade at render time.**
-  Setting it to `0.5` renders the same as `0`, and animating `0 → 1` produces no
-  change. Do not reach for it as a generic "ramp the whole look" dial.
+- **`--hf-color-grading-intensity` scales the primary grade only.** The shader
+  mixes between the ungraded sample and the graded one at that value, so it
+  ramps `adjust`, `wheels`, `curves`, `hueCurves`, `secondaries` and the LUT.
+  It does **not** touch `details` or `effects` — grain, vignette, halftone,
+  twoInkPrint, bloom, the tape and CRT families are all applied *after* that
+  mix. So it is not a master "ramp the whole look" dial when the look is
+  effect-based; animate the specific effect instead.
 - **Every other property — `halftone`, `twoInkPrint`, `tapeDamage`, hue curves,
   secondaries — has no custom property**, so it cannot be tweened this way.
 
diff --git a/docs/prompting/color-grading.mdx b/docs/prompting/color-grading.mdx
index 88942ad35..1e6d06cb3 100644
--- a/docs/prompting/color-grading.mdx
+++ b/docs/prompting/color-grading.mdx
@@ -159,7 +159,7 @@ Nine properties expose a CSS custom property and tween directly — `ascii`, `bl
 
 Two caveats worth knowing before you promise a client a ramp:
 
-- **`--hf-color-grading-intensity` does not scale a grade at render time.** A static `0.5` renders the same as `0`. Do not reach for it as a generic "ramp the whole look" dial.
+- **`--hf-color-grading-intensity` scales the primary grade only** — `adjust`, `wheels`, `curves`, `hueCurves`, `secondaries` and the LUT. It does *not* scale `details` or `effects`, which are applied after that mix, so it will not ramp grain, halftone, bloom or the tape and CRT families. Reach for the specific effect instead of treating it as a master dial.
 - **Everything else has no custom property.** Some of those can still be animated by rewriting the `data-color-grading` payload from the timeline, and some cannot — the verified list of which is which lives in the guide's [Animating a Grade](/guides/color-grading#animating-a-grade), so it only has to be maintained in one place. Measure the effect you intend to animate before you promise a ramp, and fall back to a static treatment if it does not move.
 
 ## Next steps