docs(skills): scope gizmo behaviour by renderer and state both ambient workarounds

Author: apresmoi

packages/skills/skill/docs/controls-and-interaction.md

@@ -130,7 +130,11 @@ Raycasting runs on pointer events only — never per frame.
 ## Transform controls
 
 Translate mode gives axis arrows and plane handles; rotate mode gives axis
-rings. Dragging updates the attached mesh directly.
+rings. **In vanilla** dragging updates the attached mesh directly, because
+`createTransformControls` calls `handle.setTransform(...)` itself. **In React
+and Vue** dragging updates nothing on its own — the gizmo emits
+`onObjectChange` and your state update is what moves the mesh (and the gizmo
+with it).
 
 Key props: `object`, `mode`, `size`, `showX`, `showY`, `showZ`,
 `translationSnap`, `rotationSnap`, `enabled`, `onChange`, `onObjectChange`,

packages/skills/skill/docs/lighting.md

@@ -56,8 +56,12 @@ baseline.
 - **Vanilla `setOptions({ ambientLight })` changes nothing on its own.** There
   is no ambient branch in the change detection at all, so the baked surface
   stays stale *and* the shadow fill — which is derived from ambient — is not
-  re-emitted. Change the directional light in the same call, or call
-  `mesh.rebakeAtlas()`, to make an ambient edit take effect.
+  re-emitted. Two outputs are stale and **neither workaround fixes both**:
+  `mesh.rebakeAtlas()` refreshes that mesh's baked paint but does not re-emit
+  the receiver shadow, while touching the directional light in the same
+  `setOptions` call re-emits the shadow but leaves baked mesh colors frozen. To
+  fully apply an ambient edit, do both — nudge the directional light *and*
+  rebake every affected mesh.
 
 So the vanilla freeze covers the directional **and** ambient lights, not the
 directional light alone.

website/public/skill/docs/controls-and-interaction.md

@@ -130,7 +130,11 @@ Raycasting runs on pointer events only — never per frame.
 ## Transform controls
 
 Translate mode gives axis arrows and plane handles; rotate mode gives axis
-rings. Dragging updates the attached mesh directly.
+rings. **In vanilla** dragging updates the attached mesh directly, because
+`createTransformControls` calls `handle.setTransform(...)` itself. **In React
+and Vue** dragging updates nothing on its own — the gizmo emits
+`onObjectChange` and your state update is what moves the mesh (and the gizmo
+with it).
 
 Key props: `object`, `mode`, `size`, `showX`, `showY`, `showZ`,
 `translationSnap`, `rotationSnap`, `enabled`, `onChange`, `onObjectChange`,

website/public/skill/docs/lighting.md

@@ -56,8 +56,12 @@ baseline.
 - **Vanilla `setOptions({ ambientLight })` changes nothing on its own.** There
   is no ambient branch in the change detection at all, so the baked surface
   stays stale *and* the shadow fill — which is derived from ambient — is not
-  re-emitted. Change the directional light in the same call, or call
-  `mesh.rebakeAtlas()`, to make an ambient edit take effect.
+  re-emitted. Two outputs are stale and **neither workaround fixes both**:
+  `mesh.rebakeAtlas()` refreshes that mesh's baked paint but does not re-emit
+  the receiver shadow, while touching the directional light in the same
+  `setOptions` call re-emits the shadow but leaves baked mesh colors frozen. To
+  fully apply an ambient edit, do both — nudge the directional light *and*
+  rebake every affected mesh.
 
 So the vanilla freeze covers the directional **and** ambient lights, not the
 directional light alone.