docs: audit app architecture and refresh feature documentation

docs/technical/animation.md

@@ -9,7 +9,9 @@ This document describes the 3D components that are currently used in the runtime
 | Interaction | `InteractableObject` | Focus detection through distance and raycasting                       |
 | Interaction | `TriggerObject`      | Press-to-trigger interactions, optional sound, optional spawned model |
 | Interaction | `GrabbableObject`    | Physics grab and hand-tracking grab behavior                          |
+| Model       | `AnimatedModel`      | GLTF animation playback with fade, speed, and context controls        |
 | Model       | `ExplodableModel`    | Split/reassemble a GLTF model into separated parts                    |
+| Model       | `SimpleModel`        | Lightweight static GLTF render helper                                 |
 | Gameplay    | `RepairCaseModel`    | Repair case lid animation, proximity float, and wobble                |
 
 ## Continuous Animation
@@ -27,6 +29,30 @@ Use GSAP only for discrete timeline-style transitions. Current example:
 
 - `RepairCaseModel` animates the case lid between open and closed rotations.
 
+## Animated Models
+
+`src/components/three/models/AnimatedModel.tsx` wraps drei `useAnimations()` around a loaded GLTF scene.
+
+It supports:
+
+- default animation playback
+- optional autoplay
+- fade duration
+- speed multiplier
+- `onLoaded`
+- `onAnimationEnd`
+- context controls through `AnimatedModelContext`
+
+The debug physics scene currently uses it to preview:
+
+```txt
+public/models/electricienne_animated/model.gltf
+```
+
+with the `Dance` animation.
+
+`src/hooks/animation/useCharacterAnimation.ts` is a hook-level alternative for components that need to own their group ref and animation controls directly.
+
 ## GLTF Reuse
 
 Use `useClonedObject` when a GLTF scene is reused by a component instance. It memoizes `scene.clone(true)` and keeps clone creation out of render churn.
@@ -44,7 +70,9 @@ src/components/three/
 │   ├── InteractableObject.tsx
 │   └── TriggerObject.tsx
 ├── models/
-│   └── ExplodableModel.tsx
+│   ├── AnimatedModel.tsx
+│   ├── ExplodableModel.tsx
+│   └── SimpleModel.tsx
 └── world/
     └── SkyModel.tsx
 ```