docs(animations): naming conventions, wiring audit, unwired catalogue + claude-desktop context brief

NAMING.md/AUDIT.md/UNWIRED.md are the conventions-doc pivot after the
mass-rename was killed; committing so the bridge repo tree is clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

animation-context-for-claude-desktop.md

@@ -0,0 +1,140 @@
+# Animation Pipeline — Context Brief
+
+> Compiled from claude-mem across the `ariki-game` and `animation` projects (July 2026 sessions). This is a portable context dump so a fresh Claude (e.g. Claude Desktop) understands how the ARIKI game's animation system works, what assets and tools exist, and the conventions/gotchas that matter.
+
+---
+
+## 1. The big picture
+
+There are **two related repos** and **two distinct animation domains**.
+
+**Repos**
+- `~/Tinqs/local.repo/ariki-game` — the Godot 4 / C# game project. Consumes finished animation clips.
+- `~/Tinqs/local.repo/animation` — a **Mac↔PC pipeline hub**. Bridges iClone/Character Creator output (produced on PC) with the Mac side for conversion and import into the game. Uses Git LFS for large binary assets (FBX, iProject files, texture maps, reference videos).
+
+**Two animation domains inside the game (do not conflate them):**
+1. **Character-clip / dance pipeline** — skeletal animation clips retargeted onto the shared Quaternius skeleton, plus hot-reloadable JSON dance choreography. Test bed lives in `src/Testing/Dance/`; runtime consumer is `src/Animation/`.
+2. **FX / VFX pipeline** — effects animation via Tweens, `GpuParticles3D`, shaders, and per-feature "Beat" controllers. Lives in `src/Rendering/` and `src/Beats/`.
+
+---
+
+## 2. Runtime animation code (`src/Animation/`)
+
+The runtime character-animation layer is **compact — 5 files** — and sits between the clip library and actual gameplay:
+
+- `CharacterAnimDriver.cs` — low-level clip playback + state machine; shared base/adapter between the clip pipeline and game character nodes.
+- `PlayerAnimationLogic.cs` — shared transition/blend-tree logic (was a late discovery; doesn't contain "dance"/"AnimationTree" keywords so early greps missed it).
+- `PlayerAnimController.cs` — in-game player animation controller; Godot `AnimationTree` integration + IK hooks. (Distinct from `DebugAnimPlayer` in the test bed.)
+- `PlayerIKRig.cs` — runtime inverse kinematics (foot placement, hand targets).
+- `AnimalAnimationLogic.cs` — separate animation path for animal characters; canonical state keys via `StateKeyFor`.
+
+Likely layering: `CharacterAnimDriver` → `PlayerAnimationLogic` → `PlayerAnimController` → `PlayerIKRig`.
+
+**Not animation:** `src/Character/` is outfit/clothing systems (OutfitCatalog, OutfitSystem, ClothingItem, CharacterBuffSystem, CharacterPreview), not animation.
+
+**QA surface is ~2x the runtime:** 9 test-bed files (ClipStation, UpperBodyBlendStation, AnimGalleryStation, AnimationShowcase, PlayerAnimTestBed, AnimActionTestBed, JumpAnimTestBed, LandingSlideTestBed, AiAnimationTestScene) vs 4–5 production files. `PlayerAnimTestBed.cs` (~410 lines) is the largest/most dance-relevant test bed and models the clip-loading pattern.
+
+Player setup entry point: `src/Viewer/PlayerController.cs` (`SetupAnimations` around line 508).
+
+---
+
+## 3. Animation assets
+
+### Character clips (shared Quaternius skeleton)
+- **Kevin Iglesias packs** — `assets/quaternius/kevin/`, ~12 GLB packs, **~810 clips total** (combat, idles, misc, movement, social, work — male + female).
+  - `kevin_male_social.glb`: 68 anims (military salutes w/ weapon variants, 7 dance poses as begin/loop/stop triplets, 18 dance clips, claps/waves/cheers, talk/emotion cycles).
+  - `kevin_male_movement.glb`: 157 anims (rolling, sliding, 8-directional walking, crouch idle/turn/strafe/walk) — each in **root-motion (`_RM`) and in-place variants**.
+  - Plus idles, misc (eat/drink/sleep/sit), work (chop/mine/hammer/fish/gather/farm/water/carry/skin).
+- **UAL libraries** — `UAL1_Standard.glb` (anim-lib-1, ~19 player clips: idle/walk/run/sprint/jump chain/dance/death/swim/interact/punch/throw/crouch) and `UAL2_Standard.glb` (anim-lib-2, running-jump chain: NinjaJump Start/Idle/Land).
+- **Combined** — `anim-combined/Run_Punch.glb`.
+- **Pre-extracted single-clip FBX** — `assets/animations/kevin/` (13 gameplay-critical FBX: Archer combat/death/idle/run/damage, Throwing@BigAxe, Villager gathering/skinning) and `assets/animations/basic-motions/` (Idle01, Walk01, Run01, Sprint01). **Note:** social/misc/dance clips were *not* extracted to individual FBX — they live only inside the GLB packs.
+- **Generated dances** — `assets/quaternius/dancegen/` (auto-discovered by `ClipCatalog`): fertility_dance_01(_pp), taming_dance_01(_pp), hakadance1_static.
+
+**Load order (later overrides earlier for same clip name):** `PlayerController.SetupAnimations` loads UAL1 → UAL2 → Kevin packs. Example override: Kevin `work` chop overrides UAL1 Sword_Attack.
+
+**Naming conventions (Quaternius):** `CharacterName@AnimationName.fbx`; suffix `_RM` = root motion; `_Loop` = looping; directionals `_Forward`/`_BackwardLeft`/etc.; dances use `_Begin` / `_Loop` / `_Stop` triplets.
+
+### Dance choreography (hot-reload JSON)
+`assets/dances/*.json` — hot-reloadable: clap_stomp, fertility_dance_01(_pp), haka_tutorial, hakadance1_static, hype_line, taming_dance_01(_pp), test_trio, haka_mocap.
+
+**Dance type assignments (configured):** Haka = "war dance 1", Aloha = "fertility", Dance1 = "taming dance". **Requirement: every dance must ship a dedicated `_Loop` version** so it plays continuously without restarting.
+
+### Animals
+`assets/models/animals_catalog.json` — **96 species, 320 distinct clips** (avg 3.33/species, max 6 = Chick). Fields: `anims`, `category`, `state_clips`, `default_clip`, `glb`, `size_m`. Canonical states: idle, walk, run, fly, swim, attack, death, + ambient eat/sleep/drink/graze.
+
+### Retarget bone maps
+`assets/retarget/kevin_bonemap.tres`, `assets/retarget/bozo_bonemap.tres`. No standalone `.anim`/AnimationLibrary resources — animations are embedded in FBX/GLB.
+
+---
+
+## 4. Tooling (Python retarget + GLB utilities)
+
+Located under `tools/`:
+
+- `mocap_retarget.py` — **MediaPipe pose JSON → solved bone rotations → Quaternius-skeleton GLB** via headless Blender. Uses limb-aim deltas, torso-basis solve, char-frame conjugation, squat-height reconstruction from leg extent, shortest-arc rotation solving.
+- `cc_retarget.py` — Reallusion Character Creator / iClone `CC_Base_*` FBX retargeting; rejects motionless `TempMotion` placeholder takes.
+- `mixamo_retarget.py` — Mixamo FBX → Quaternius.
+- `kevin_retarget.py` — Kevin FBX → Quaternius.
+- `convert_all_fbx.py` — batch FBX conversion.
+- `anim_qc.py` / `anim_qc.py` — loop-seam / velocity / stutter quality checks.
+- GLB utilities: `glb_oracle.py`, `validate_glb_structure.py`, `batch_convert_glb.py`, `strip_glb_textures.py`, `normalize_animal_glbs.py`, `normalize_item_glbs.py`.
+
+`ClipCatalog.cs` (`src/Testing/Dance/`) scans `quaternius/dancegen`, `kevin`, and `mixamo` paths for clips.
+
+**Proof-of-concept that works:** MediaPipe→GLB ran end-to-end on a YouTube haka tutorial → **208 frames / 26 s @ 30fps** `HakaFull`, with **0.0° elbow-angle error** across all sampled frames. Output: `assets/quaternius/mixamo/haka_mocap.glb`. Detection caveat: **94% on solo-framed characters, 0% on wide shots.**
+
+---
+
+## 5. Claude skills & MCP setup
+
+**ariki-game skills** (`.claude/skills/`):
+- `animation-creation` — the master skill. Documents **6 creation paths, cheapest-first:** (1) reuse existing ~810 clips, (2) retarget Mixamo/Kevin FBX with Blender scripts, (3) author composite clips in JSON (upper/lower body masks), (4) author full dance choreography sequences, (5) live Blender (blender-mcp), (6) video mocap. Companion recipes: `blender-mcp-recipes.md`, `gltf-transform-recipes.md`.
+- `iclone-video-mocap` — feeds `cc_retarget.py`. Backed by a 31KB `references/iclone8-core-animation.md` (Motion Clips + Layer Keys model, Edit Motion Layer / HumanIK, Timeline ops, Curve Editor F12 filters, Motion Correction, AccuLips face anim, FBX/USD export). iClone is Z-up, 1 unit = 1 cm, 60fps internal. **BVH export NOT available from iClone 8.** 3DXchange discontinued (merged into iClone 8 + CC4). Reallusion content needs an Export License for FBX/OBJ/USD.
+- `retarget-animations` (agent-level, `.agents/skills/`) — **deprecated/retired May 2026** (was Kevin→BoZo).
+
+**MCP:** `.mcp.json` registers **blender-mcp via `uvx blender-mcp`** (replaced the old Playwright entry + removed a hardcoded token). Five mature **Godot MCP** projects exist that can drive `AnimationPlayer`/scenes directly (godot-mcp-pro = 175 tools, Godot AI = 150+ w/ fade/slide/shake/pulse presets, tugcantopaloglu `game_play_animation`, mkdevkit, tomyud1). Closes the loop: **Blender MCP (rig/animate) → glTF-Transform (optimize GLB) → Godot MCP (engine integration).**
+
+**General media/animation skills available (`~/.claude/skills/`):** `video-editing` (FFmpeg/Remotion/ElevenLabs/fal.ai), `videodb`, `manim-video`, `remotion-video-creation`, `fal-ai-media`.
+
+---
+
+## 6. The video→dance generation pipeline (7 stages)
+
+Documented in `.agents/plans/animation-gen-pipeline-2026-07-13.md`. Honest framing: it produces a **cover version using a discrete clip vocabulary, not true motion capture.**
+
+1. Ingest source video with a beat grid.
+2. Programmatic + vision choreography breakdown.
+3. Clip-card catalog of the ~810 existing clips (blocked on building `CatalogMode` in the test bed — the identified next build item).
+4. DTW matching with split-mask composite fallback.
+5. Mixamo gap-fill for unmatched segments.
+6. Emit dance JSON.
+7. Self-verify: play in-game, capture via VideoRecorder, compare poses back to the source (uses the `pose-estimation` skill for scoring).
+
+**Risks flagged:** camera-angle mismatch, multi-dancer sources, catalog scale, score-threshold calibration.
+
+---
+
+## 7. Hard constraints & gotchas
+
+- **Never use `*RM` root-motion variants** in contexts expecting in-place animation.
+- **Skeleton path remap is mandatory** when retargeting.
+- **Clip-name fallback logic:** exact → try `+"_Loop"` → try `-"_Loop"`.
+- **Skip `RESET` clips.** `.uid` files auto-generate.
+- **Every dance needs a `_Loop` version** (see §3).
+- Retarget tools **reject motionless `TempMotion` placeholder takes** (CC export artifact).
+- The `animation` repo is LFS-heavy — pulls can be 100+ MB (one iClone `.iProject` was 109 MB).
+- Pose detection fails on wide shots (0%); frame subjects solo for mocap.
+
+## 8. iClone correction workflow notes (from the animator)
+
+- To fade a correction in/out over a range: **bracket the fix with a clean keyframe before and after** the blend zone.
+- Use the **Animation Layer panel (F11)** — stackable named layers, each with a keyframeable weight slider — for non-destructive experiments; merge down when satisfied.
+- Curve Editor (F12) Optimize/Smooth/Butterworth filters clean up mocap jitter after sampling clips to layer keys.
+- Motion Correction auto-creates hand/foot prints + Reach keys to fix sliding; requires iterative Flatten→deactivate→correct cycling.
+
+---
+
+## 9. Future / planned
+
+- **Crowd-animation platform** (`.agents/wiki/crowd-animation-platform.md`): baked bone-matrix **animation-texture GPU instancing** to render thousands of colonists, beyond the current per-skeleton `PlayerAnimController` path.
+- A dedicated `animation` skill for recording animator preferences/lessons was requested (source of the §3 dance-type + §8 iClone notes).

docs/animations/AUDIT.md

@@ -0,0 +1,249 @@
+# Animation Audit — 2026-07-24
+
+Working audit for the animation naming-system project. Captures the current-state
+inventory, what the game actually implements, what Ozan removed during his recent
+animation work, and the open scope decisions. This is the evidence base for the
+plan at `~/.claude/plans/i-want-to-audit-enchanted-squid.md`.
+
+**Status:** audit findings recorded. **Decision (Ozan, 2026-07-24): do NOT implement a
+mass-renaming system.** Pivot to *document the existing conventions + catalogue provenance/
+status*; keep vendor names, name new files to conform. See `docs/animations/NAMING.md` for
+the conventions. Nothing renamed. The rename-scope questions in §6 are now moot (resolved:
+no rename); the registry catalogue in §6 still proceeds.
+
+---
+
+## 1. Goal
+
+Audit and revise the animation naming system across the two repos. Five deliverables:
+
+1. Create a naming system for **all** animations.
+2. Figure out which animations Ozan removed ("Kevin" clips) during his last animation
+   work, and document the full list of animations the game needs.
+3. Rename current animations per the new naming system.
+4. Document the system.
+5. The animation list must store, per clip: where it came from, when it was created,
+   how it was created, and whether it is **approved / work-in-progress / not-started**.
+
+### Decisions locked (Jeremy, 2026-07-24)
+
+- **Rename every animation in the game** per the new system; the registry stores each
+  clip's **old/original name**. *(Scope of "in the game" narrowed by the §3 finding —
+  see the open question in §6.)*
+- Registry is **machine-readable YAML + a generated Markdown** view.
+- Coverage = **all avatar skeletal clips** (locomotion, tools/work, combat, swim, dance,
+  boat, emotes/social). Animals out of scope.
+- Naming docs + registry live in the **animation repo** under `docs/animations/`, with
+  pointers from ariki-game docs.
+
+### Registry fields required
+
+`canonical name` · `old name(s)` · `category` · `source/origin` · `creation date` ·
+`creation method` · `status (approved | wip | not_started)` · `notes`.
+
+---
+
+## 2. Where the packs live
+
+All game-loaded animation packs are under `assets/quaternius/` in **ariki-game**
+(`/Users/jeremykashkett/Tinqs/local.repo/ariki-game`).
+
+| Group | Path | Files | Clips | What it is |
+|---|---|---|---|---|
+| **UAL vendor** | `assets/quaternius/anim/` | UAL1.glb, UAL2.glb (+ `_RM` twins, Mannequin_F) | 254 unique (508 w/ RM) | Purchased Quaternius packs — the game's loco + work source of truth |
+| **Kevin** | `assets/quaternius/kevin/` | 12 GLBs (`kevin_{male,female}_{combat,idles,misc,movement,social,work}.glb`) | 1,307 (male/female mirror → ~650 unique) | Kevin Iglesias retargets; game uses "gap-only" |
+| **msrig** (stale) | `assets/quaternius/msrig/` | 18 GLBs (Kevin packs + UAL_Standard + a few Mixamo) | 1,399 | Superseded MixamoSkin retargets — flagged stale in the 2026-07-23 audit |
+| **Mixamo** | `assets/quaternius/mixamo/` | 4 GLBs (run_to_dive, walking, northern_soul, ual_loco) | 11 | One-off Mixamo clips |
+| **dancegen** | `assets/quaternius/dancegen/` | 10 GLBs (war/fertility/taming + `_pp`, nd_01, canoedismount1, hakadance1_static) | 11 | Our authored iClone-mocap dances + boat one-off |
+| **anim-combined** | `assets/quaternius/anim-combined/` | Run_Punch.glb | 1 | Baked composite (run legs + punch upper body) |
+
+**Animation-repo side** (`/Users/jeremykashkett/Tinqs/local.repo/animation`) holds the
+pipeline staging/source, not what the game loads:
+- `exchange/` — incoming FBX, converted GLB, pingpong loops, outgoing props
+- `archive/` — retired takes (never deleted, per policy)
+- `.agents/wiki/dances/REGISTRY.md` — existing partial naming system (dances + boat actions)
+- `tools/` — all Blender-based (`cc_retarget.py`, `rename_clip.py`, `loop_qc.py`, `pingpong_bake.py`, …)
+
+Dance JSONs that tell the game which clip to play: `ariki-game/assets/dances/*.json`.
+
+---
+
+## 3. Full clip census (2026-07-24)
+
+Read directly from each GLB's glTF JSON chunk (pure-stdlib parser, no Blender).
+
+| Pack | Files | Clips |
+|---|---|---|
+| `anim/` (UAL1 120, UAL1_RM 120, UAL2 134, UAL2_RM 134, Mannequin_F 0) | 5 | 508 |
+| `kevin/` | 12 | 1,307 |
+| `msrig/` | 18 | 1,399 |
+| `mixamo/` (ual_loco 8, + 3 one-offs) | 4 | 11 |
+| `dancegen/` | 10 | 11 |
+| `anim-combined/` | 1 | 1 |
+| **GRAND TOTAL** | 50 | **3,237** |
+
+Per-file Kevin breakdown (male mirrors female): `combat` 286, `movement` 157, `work` 72,
+`social` 68, `misc` 55, `idles` 15–16. Most Kevin clips are irrelevant to this game —
+`Rifle_Aim*`, `ThrowGrenade*`, `ThrowBoomerang*`, `Bow*`, `Casting*`/magic.
+
+---
+
+## 4. What the game actually implements (~90–100 clips)
+
+Traced through `PlayerController.SetupAnimations()`
+(`ariki-game/src/Viewer/PlayerController.cs:779`) — the authoritative clip→game-key
+mapping — plus the dance system's `ClipCatalog` auto-discovery of `dancegen/`.
+
+**Only 9 pack files are loaded at all. Of ~3,237 clips on disk, ~90–100 are wired.**
+
+| Pack (loaded) | Clips wired | On disk | What's used |
+|---|---|---|---|
+| `anim/UAL1.glb` | ~41 | 120 | idle/walk/jog/sprint 8-dir, crouch 8-dir, jumps, turns, drink/sit, sword, interact |
+| `anim/UAL2.glb` | ~30 | 134 | chop/mine/fish/farm/carry/eat/sleep, 8-dir walk, shield set, running jump, 180 turns |
+| `kevin_*_movement.glb` | 10 | 157 | full directional swim set (loaded after UAL to override stock swim) |
+| `kevin_*_combat.glb` | 3 | 286 | ThrowWeapon01_R, ThrowSpear02_R, ThrowBall01_R |
+| `kevin_*_work.glb` | 1 | 72 | skin (SkinningGround01_R_Loop) |
+| `kevin_*_social.glb` | 1 | 68 | pray (Reverence01_Loop) |
+| `anim-combined/Run_Punch.glb` | 1 | 1 | run_punch composite |
+| `mixamo/` (3 files) | 3 | 11 | walking, run_to_dive, northern_soul (→ dance_soul) |
+| `dancegen/` | ~10 | 11 | war/fertility/taming dances + `_pp` loops, nd_01 + `_pp`, canoe clips |
+
+**Packs with ZERO clips implemented:** all of `msrig/` (1,399, superseded), `kevin_*_idles`
+and `kevin_*_misc` (0 wired), the `_RM` root-motion UAL twins (never loaded — game loads
+non-RM only), `mixamo/ual_loco.glb`.
+
+**Takeaway:** ~97% of on-disk clips are unused vendor-library bulk buried inside purchased
+multi-clip GLBs. The implemented ~90 are what map cleanly to a naming system and are worth
+physically renaming; the rest are candidates you *could* pull from later.
+
+### Sample of implemented clip → game-key mapping (UAL, from SetupAnimations)
+
+UAL1 clip → key: `Idle_Loop→idle`, `Walk_Loop→walk`, `Jog_Fwd_Loop→run`,
+`Sprint_Loop→sprint`, `Dance_Loop→dance/dance2/dance3` (one source, 3 keys),
+`Sword_Attack→weapon_attack`, `Fixing_Kneeling→hammer`, `Spell_Simple_Shoot→throw`,
+`GroundSit_Idle_Loop→sit`, 8-dir jog/crouch, `Turn90_L/R`.
+UAL2 clip → key: `TreeChopping_Loop→chop`, `Mining_Loop→mine`, `Fish_Cast_Idle_Loop→fish`,
+`Farm_Harvest→gathering`, `Farm_PlantSeed→farm`, `Consume→eat`, `IdleToLay→sleep`,
+`Walk_*_Loop→walk_*` (8-dir), shield set, `NinjaJump_*→running_jump_*`.
+
+Kevin gap clips (game-key = same or mapped): swim set `Swim01_*→swim*` / `SwimIdle01→swim_idle`,
+`SkinningGround01_R_Loop→skin`, `Reverence01_Loop→pray`, three throw clips kept as-is.
+
+---
+
+## 5. Kevin-removal forensics (what Ozan removed)
+
+During Ozan's recent animation work (2026-07-22/23), two relevant removals in **ariki-game**:
+
+### 5a. Loose Kevin + Synty FBXs deleted — commit `f5ee3a7d0` (2026-07-22)
+> `chore(anims): drop unused Unity/Synty FBXs and dead import-time retarget`
+
+Deleted animation FBXs (each with its `.import` sidecar):
+- **Kevin** (`assets/animations/kevin/`): `Archer@CombatIdle01/02`, `Archer@Death01/02`,
+  `Archer@Idle01/02`, `Archer@Run01`, `Archer@TakeDamage01`, `Throwing@BigAxe`,
+  `Villager@Gathering01/02/03`, `Villager@Skinning01` — **13 clips**
+- **Synty BasicMotions** (`assets/animations/basic-motions/`): `@Idle01`, `@Run01`,
+  `@Sprint01`, `@Walk01` — 4 clips
+- Also dropped: Unity-format UAL/mannequin/base-character FBX exports (the Godot pipeline
+  uses the Godot/GLB exports, so these were redundant format duplicates).
+
+**Important nuance:** these were the *loose per-clip FBX* form of Kevin content. The Kevin
+**category GLB packs** (`assets/quaternius/kevin/kevin_*_*.glb`, 1,307 clips) survive and
+still contain equivalent content — e.g. the deleted `Villager@Skinning01` corresponds to
+`SkinningGround01_R_Loop` still present in `kevin_*_work.glb` (and still wired as `skin`).
+So most of these are **superseded**, not truly lost. Each needs a clip-level cross-check in
+Phase 1 to classify **truly gone** vs **still available in a pack / covered by a UAL clip**
+(e.g. `Villager@Gathering` ↔ UAL2 `Farm_Harvest`; Archer combat ↔ `kevin_*_combat.glb`).
+
+### 5b. UAL Standard packs removed — commit `2292174dc` (2026-07-23)
+> `feat(anims+character): canonicalize UAL packs under anim/, land QuatSkin body work + tool kit`
+
+Removed the older UAL **Standard** clip GLBs (`UAL1_Standard.glb`, `UAL2_Standard.glb`, etc.)
+in favor of **UAL1 Pro (120 clips)** + **UAL2 Source (134 clips)** under `anim/`. This is a
+supersession/upgrade, not a loss — the Pro/Source packs are complete supersets. (Stale
+`UAL*_Standard.glb` copies still linger inside `msrig/`.)
+
+### 5c. Animation-repo archive
+Retired dance takes are already tracked in `.agents/wiki/dances/REGISTRY.md` and physically in
+`animation/archive/` (`alohaOG`, `firedance1`, `hakaOG`, `hakadance2`, `haka_mocap`) —
+never deleted.
+
+**Git authors for context:** Ozan Bozkurt is by far the dominant author of animation commits;
+"Kevin" refers to the Kevin Iglesias vendor animation packs, not a team member.
+
+---
+
+## 6. Open scope decisions (BLOCKING — need Jeremy)
+
+The §3/§4 findings changed the picture after the "rename everything" decision was made,
+so these need an explicit call before any renaming:
+
+1. **Rename scope.** Given ~90 clips are implemented and ~3,000+ are unused vendor bulk:
+   - **(A, recommended)** Physically rename only the ~90 implemented clips + all our
+     authored content; catalogue everything else in the registry with a canonical ID +
+     old-name mapping but leave vendor names in the GLBs. Keeps the vendor re-download/upgrade
+     path clean.
+   - **(B)** Rename the whole functional set the game might ever wire (few hundred), leaving
+     only clearly-irrelevant vendor clips (rifles, magic) untouched.
+   - **(C)** Literally rename all 3,237 — max consistency, breaks vendor upgrade path, huge
+     effort for near-zero value on unused clips.
+
+2. **msrig/ (1,399 stale clips).** Recommended: archive it (never delete), mark superseded in
+   the registry, don't rename — but confirm with Ozan first since code still has `msrig`
+   fallback paths (`PlayerController.cs`, test beds). Alternatives: catalogue-in-place, or
+   rename-too.
+
+---
+
+## 7. Key technical constraints (for the rename phase)
+
+- **One skeleton:** Quaternius 65-bone UE-named rig. Renaming a clip name inside a GLB is
+  **metadata-only** and safe for the rig. The risk is entirely in *references*.
+- **Reference sites to migrate** (ariki-game): `PlayerController.SetupAnimations()` (the
+  clip→game-key arrays — #1 silent-failure spot), `PlayerAnimGraphBuilder.cs`,
+  `CharacterAnimDriver.Resolve()` (already has alias fallback — useful during migration),
+  `ToolActionResolver.cs`, `ThrowActionCatalog.cs`, `AnimationClipProfile.cs` +
+  `data/animation-clip-profile.json`, `ClipCatalog.cs` (dance bed, discovers packs by
+  basename), `assets/dances/*.json`, docs.
+- **Multi-clip GLBs:** `rename_clip.py` assumes one action per armature; UAL/Kevin packs have
+  many. The batch rename tool must handle multi-action GLBs.
+- **Godot sidecars:** after any asset rename, regenerate `.import` via `bash tools/game.sh import`.
+- **Vendor originals** are archived unmodified in `tinqs/ariki-assets`; renames must be applied
+  by a **re-runnable rename-map script** so a future pack update re-canonicalizes in one pass.
+- **Existing gates to reuse:** `tools/rig_pose_gate.py` (rest-pose delta vs UAL1 ref),
+  `ariki-game/tools/anim_qc.py` (post-ingest seam/stutter), animation-repo `tools/loop_qc.py`
+  (pre-commit loop gate), locomotion + dance test beds (launch only after asking Jeremy).
+- **Repo etiquette:** `tinqs push` / `tinqs pull` (raw git pull hangs on LFS), explicit-path
+  staging, report commit hashes, archive-never-delete, clip numbers never reused.
+
+---
+
+## 8. Existing naming precedent (to generalize)
+
+From `animation/.agents/wiki/dances/REGISTRY.md` (currently dances + boat only):
+- **snake_case** matching the game's item-id convention (e.g. `war_dance_01`); clip name baked
+  in GLB is **PascalCase** (`WarDance01`).
+- **Provisional stage:** new takes get `nd_##` (never a content name), renamed to a dance code
+  only when Jeremy adopts them for a ceremony.
+- **Loop-pair rule:** every adopted dance ships base + ping-pong `_pp` variant, must pass
+  `loop_qc.py`.
+- **Suffixes seen in use:** `_loop`, `_idle`, `_pp`, directional (`_fwd/_bwd/_l/_r`), `_rm`.
+- **Archive, never delete; numbers never reused.**
+
+Game-side keys already in use (lowercase snake_case): `idle`, `walk`, `run`, `sprint`, `swim`,
+`swim_idle`, `chop`, `mine`, `fish`, `gathering`, `farm`, `skin`, `pray`, `crouch_*`, `turn90_l`,
+etc. The new naming system should reconcile the canonical clip IDs with these existing game keys.
+
+---
+
+## 9. Next steps
+
+1. **Resolve §6 scope decisions** (blocking).
+2. Phase 0 — draft `docs/animations/NAMING.md` (naming spec) + Jeremy approval gate.
+3. Phase 1 — full clip inventory JSON + `docs/animations/REMOVALS.md` (clip-level removal
+   cross-check).
+4. Phase 2 — `docs/animations/registry.yaml` + render/check tools.
+5. Phase 3 — staged, gated rename execution.
+6. Phase 4 — documentation + maintenance protocol.
+
+Full plan: `~/.claude/plans/i-want-to-audit-enchanted-squid.md`.

docs/animations/NAMING.md

@@ -0,0 +1,169 @@
+# Animation Naming Conventions
+
+**Decision (Ozan, 2026-07-24): do NOT mass-rename existing animations.** Renaming clip
+strings inside purchased vendor packs (Quaternius UAL, Kevin Iglesias) breaks the
+vendor re-download/upgrade path, forces a risky full-pack re-export through Blender, and
+buys only cosmetic consistency. Instead: **document the conventions that already exist,
+keep each source's native names, and name new files to conform going forward.** Provenance
+and status are tracked in the registry catalogue, not by renaming.
+
+This file is the source of truth for *how animations are named*. `.agents/wiki/dances/REGISTRY.md`
+remains the source of truth for the dance/boat clip roster.
+
+---
+
+## 1. The three name-spaces
+
+Animation naming spans three independent layers. They are joined by explicit mappings, not
+by making the strings equal. **You almost never need them to match.**
+
+| Layer | What it is | Case style | Example | Who reads it |
+|---|---|---|---|---|
+| **Pack file** | the `.glb` basename on disk | lowercase snake_case | `kevin_male_movement.glb`, `UAL1.glb`, `war_dance_01.glb` | filesystem, `ClipCatalog` (discovers by basename) |
+| **Clip name** | the animation string baked inside the GLB | *source-dependent* (see §3) | `Swim01_Forward`, `TreeChopping_Loop`, `WarDance01` | GLB metadata, dance JSON `clip` field, `SetupAnimations()` mapping |
+| **Game key** | the logical id the game code plays | lowercase snake_case | `swim`, `chop`, `war_dance_01` | `PlayerAnimController`, `PlayerAnimationLogic`, `AnimationTree`, AI, dance JSON `name` |
+
+**Key fact:** the game controller speaks *only game keys* — it never references a raw clip
+name. The single place the clip-name layer meets the game-key layer is the mapping arrays in
+`ariki-game/src/Viewer/PlayerController.cs → SetupAnimations()` (`clip name → game key`).
+That indirection is why we can keep vendor clip names untouched: the game key is our stable
+API, the vendor clip name is just what that key happens to bind to.
+
+---
+
+## 2. Game keys — the one namespace we fully own
+
+Game keys are the cleanest, most important naming layer, because they are the game's actual
+vocabulary and we control them 100%. **Rules:**
+
+- **lowercase snake_case**, matching the game's item-id convention (`ceremonial_garb`, `dance_platform`).
+- **Semantic, not source-derived.** Name the *action*, never the vendor clip it currently
+  points at: `chop`, not `treechopping`. If we later swap the underlying clip, the key is stable.
+- **Directional suffixes** use short forms: `_fwd`, `_bwd`, `_l`, `_r`, and diagonals
+  `_fwd_l`, `_fwd_r`, `_bwd_l`, `_bwd_r`.
+- **State suffixes:** `_idle`, `_enter`, `_exit`, `_start`, `_land`.
+- Examples in use: `idle`, `walk`, `run`, `sprint`, `crouch_idle`, `crouch_walk`, `swim`,
+  `swim_idle`, `swim_up`, `swim_down`, `swim_strafe_left`, `chop`, `mine`, `fish`, `gathering`,
+  `farm`, `carry`, `eat`, `sleep`, `skin`, `pray`, `weapon_attack`, `shield_block`, `turn90_l`.
+
+When you wire a new animation, **the game key is what you invent** — pick a semantic
+snake_case key and add the `clip → key` row in `SetupAnimations()`. The clip name stays
+whatever the source produced.
+
+---
+
+## 3. Current clip-name conventions, by source
+
+We keep each source's native convention. Recognise them; don't fight them.
+
+### 3a. Quaternius UAL (`anim/UAL1.glb`, `anim/UAL2.glb`) — VENDOR, keep as-is
+- **PascalCase, `_`-separated.** `Climb_Idle_Loop`, `Jog_Fwd_Loop`, `TreeChopping_Loop`.
+- Looping clips end **`_Loop`** (or `_Idle_Loop`).
+- Directions: **`_Fwd` / `_Bwd` / `_Left` / `_Right`**; diagonals **`_Fwd_L` / `_Fwd_R` / `_Bwd_L` / `_Bwd_R`**.
+- Transitions: **`_Enter` / `_Exit`**; jumps **`_Start` / `_Land`**; variants numbered **`01`, `02`**.
+- Root-motion twins carry **`_RM`** (in the `*_RM.glb` packs; game loads non-RM only).
+
+### 3b. Kevin Iglesias (`kevin/kevin_{male,female}_*.glb`) — VENDOR, keep as-is
+- **PascalCase, action + zero-padded number, then full-word direction.**
+  `Walk01_ForwardLeft`, `Swim01_Forward`, `Crouch01_Walk_BackwardRight`.
+- Looping clips end **`_Loop`**; handedness uses **`_L` / `_R`** (`SkinningGround01_R_Loop`,
+  `ThrowSpear02_R`); root-motion uses a trailing **`RM`** (`Walk01_ForwardRM`).
+- Packs are split by theme: `combat`, `movement`, `work`, `social`, `idles`, `misc`.
+
+### 3c. Our authored clips — the convention WE apply to new content
+This is the part you actively control. Two sub-cases:
+
+**Dances & boat actions** — follow `.agents/wiki/dances/REGISTRY.md` exactly:
+- New dance take → **provisional** id `nd_##` (never a content-guessed name): pack/file
+  `nd_08`, clip `ND08`, dance JSON `nd_08.json`. Variants keep the base id + suffix:
+  `nd_08_pp` / `ND08PP`.
+- On **adoption** to a ceremony → dance code = snake_case of the sim `DanceType` enum + index:
+  pack `war_dance_01`, clip **`WarDance01`** (PascalCase, matches the enum), JSON `war_dance_01.json`.
+- **Loop-pair rule:** every adopted dance ships base + ping-pong `_pp` variant
+  (`war_dance_01_pp` / `WarDance01PP`), baked with `tools/pingpong_bake.py`, must pass `loop_qc.py`.
+- Boat actions get direct `boat_*` codes (no provisional stage): `boat_dive`, `boat_row_loop`,
+  clip `BoatDive` / `BoatRowLoop`.
+
+**Other authored one-offs (Mixamo, iClone mocap, composites):**
+- Pack file = **lowercase snake_case**: `run_to_dive.glb`, `northern_soul.glb`, `Run_Punch.glb`.
+- Clip name = **PascalCase of the file**: `RunToDive`, `NorthernSoulFloorCombo`, `Run_Punch`.
+- Game key = **semantic snake_case**: `run_to_dive`, `dance_soul`, `run_punch`.
+
+### The general rule for a NEW authored clip
+```
+pack file:  <category>_<descriptor>_<##>.glb     (lowercase snake_case)   e.g. work_haul_01.glb
+clip name:  PascalCase of the file                                         e.g. WorkHaul01
+game key:   <semantic snake_case>                                          e.g. haul
+```
+Categories (closed set): `loco`, `swim`, `work`, `combat`, `dance`, `boat`, `emote`, `misc`.
+Variants numbered, **never reused**. Looping authored clips ship a `_pp` (or `_loop`) variant
+that passes `loop_qc.py`.
+
+---
+
+## 4. Suffix & direction quick-reference
+
+| Meaning | Game key (ours) | UAL (vendor) | Kevin (vendor) |
+|---|---|---|---|
+| looping | `_idle` / (implicit) | `_Loop` | `_Loop` |
+| forward / back | `_fwd` / `_bwd` | `_Fwd` / `_Bwd` | `_Forward` / `_Backward` |
+| left / right | `_l` / `_r` | `_Left` / `_Right` | `_Left` / `_Right` |
+| diagonal | `_fwd_l` … | `_Fwd_L` … | `_ForwardLeft` … |
+| transition | `_enter` / `_exit` | `_Enter` / `_Exit` | — |
+| ping-pong loop | `_pp` | — | — |
+| root motion | (not loaded) | `_RM` | `RM` |
+| variant index | `_01` | `01` | `01` |
+
+---
+
+## 5. Decision tree — naming a future file
+
+1. **Is it a vendor clip (UAL/Kevin/other purchased pack)?**
+   → Keep the vendor's clip name and pack layout untouched. To use it, add a `clip → game key`
+   row in `SetupAnimations()` and a catalogue entry in the registry. Do **not** re-export or rename.
+2. **Is it a dance or boat action?** → Follow `.agents/wiki/dances/REGISTRY.md` (`nd_##` → ceremony
+   code; boat `boat_*`; loop-pair rule).
+3. **Is it another clip we author (Mixamo/iClone/composite)?** → Apply the §3c general rule:
+   snake_case file, PascalCase clip, semantic snake_case game key, closed-set category, `_pp` loop.
+4. **In all cases:** add/update the registry row (§6) in the same commit, and — if the game plays
+   it — the `SetupAnimations()` mapping.
+
+---
+
+## 6. The registry catalogue (provenance & status — no renaming)
+
+The catalogue records, per clip we care about, the fields Jeremy asked for — **without
+changing any names**:
+
+`canonical_id` (our snake_case handle) · `clip` (actual name in GLB, vendor or ours) ·
+`pack` · `category` · `game_keys` · `source` · `created` · `method` · `status`
+(`approved` / `wip` / `not_started`) · `notes`.
+
+- For vendor clips, `canonical_id` is just our stable handle for the catalogue; `clip` stays
+  the vendor string. Nothing on disk changes.
+- `not_started` rows capture animations the game *needs but doesn't have yet* (the 13 dance
+  ceremony slots, the 6 boat actions awaiting takes, any gap from the removals audit).
+- Kept machine-readable (YAML/JSON) with a generated Markdown view; see the audit doc for the
+  build plan. This is the deliverable that survives Ozan's no-rename decision.
+
+---
+
+## 7. Maintenance
+
+- Every convert / adopt / archive **updates the registry row in the same commit** — the rule
+  already in `.agents/wiki/dances/REGISTRY.md`, generalized to all categories.
+- **Archive, never delete; numbers never reused.** Rejected/superseded takes move to
+  `archive/` (this repo) and `archive/dances/` (ariki-game), keeping their names.
+- Sync via `tinqs push` / `tinqs pull` (raw git pull hangs on LFS). Report commit hashes.
+
+---
+
+## 8. Why this shape (rationale, for future readers)
+
+The game controller is decoupled from asset names by the game-key layer, so the *valuable*
+outcomes — provenance, status, a "what do we still need" list, and a stable controller
+vocabulary — come from the **registry + game-key discipline**, not from mutating vendor clip
+strings. Renaming purchased packs would cost a full-pack Blender re-export (risking rig-pose
+drift, caught only by `rig_pose_gate.py`), permanent vendor-upgrade friction, and LFS bloat,
+for cosmetic gain. Hence: document the conventions, name new files to fit, catalogue
+everything, rename nothing that already ships.

docs/animations/UNWIRED.md

@@ -0,0 +1,223 @@
+# Unwired Animations — GDD vs. Animation Controller Gap Analysis (2026-07-24)
+
+Cross-references what the **GDD design calls for** against what the **production
+animation controller actually wires** (`PlayerController.SetupAnimations()` +
+`CharacterAnimDriver` + `ToolActionResolver` + `ThrowActionCatalog` + graph builder).
+Companion to `AUDIT.md` (which covers disk-vs-wired). This doc answers: *of the
+animations the design needs, which are missing from the game?*
+
+**Method:** GDD shot-list (GDD.md + GDD_TODO + tech-tree `colonist-tasks.json`)
+∩ controller trace. Every "wired" claim is code-anchored; see `AUDIT.md §7` for files.
+
+## Gap types
+
+- **MISSING** — GDD needs it; no clip loaded and no trigger path. Author + wire.
+- **DEAD** — clip is already *loaded* in `SetupAnimations()` but nothing triggers it.
+  Cheap win: only needs a driver/trigger case, no new art.
+- **COLLAPSED** — GDD wants N distinct animations but they all resolve to one clip
+  (biggest offender: 12 dance types → 1 `Dance_Loop`). Needs per-variant clips + mapping.
+
+---
+
+## The big picture
+
+The production animator wires **~55 game-keys** off 9 GLB packs. Against the GDD's
+design surface (~80 colonist tasks, 12+ dances, boat wayfinding, survival states,
+combat reactions) there are **three structural holes**:
+
+1. **The signature mechanic is one clip.** All 12 sim `DanceType`s and every
+   ceremony collapse to the single `dance` key (UAL1 `Dance_Loop`). 6 of the 12
+   aren't even exposed in the client UI. This is the largest gap by design weight.
+2. **The colonist economy is visually collapsed.** ~80 tasks map to ~8 work clips;
+   whole task families (animal husbandry, water/weed/compost, carry modes,
+   star observation) have no distinct animation.
+3. **No survival/reaction layer.** Wounded, hungry, hit-reaction, celebration —
+   none wired, despite the Valheim-style needs model being core to §9.
+
+---
+
+## 1. Dance & Ceremony — SIGNATURE MECHANIC (highest priority)
+
+Wired: **`dance`** (UAL1 `Dance_Loop`) — one clip, played for every DanceType.
+`pray` (Kevin `Reverence01_Loop`) for worship.
+
+| Animation | GDD | Gap | Note |
+|---|---|---|---|
+| Water Dance | §1/§25 | COLLAPSED | → generic `dance` |
+| Fire Dance | §1/§25 | COLLAPSED | → generic `dance` |
+| Moon/Tide Dance | §1/§25 | COLLAPSED | naming drift: sim=`RainDance`, TSK=`Tide`, icon=`tidedance` (dead branch) |
+| Fertility Dance | §1/§25 | COLLAPSED | asset exists (`fertility_dance_01`) in test-bed only, not wired to avatar |
+| Food Dance | §1/§25 | COLLAPSED | → generic `dance` |
+| Taming Dance | §1/§25 | COLLAPSED | asset exists (`taming_dance_01`) test-bed only |
+| Rain Dance | §25/§13 | COLLAPSED | → generic `dance` |
+| Sailing Dance | §1 (Age 2) | COLLAPSED + not in client UI | sim-only DanceType |
+| War Dance (Haka) | §1/§28i | COLLAPSED + not in client UI | assets exist (`war_dance_01`, `hakadance1_static`) test-bed only |
+| Building Dance | §1 (Age 2) | COLLAPSED + not in client UI | |
+| Colony Shield Dance | §1 (Age 2) | COLLAPSED + not in client UI | |
+| Age Progression Dance | §1 (Age 3) | COLLAPSED + not in client UI | |
+| Star Watching Dance | §8f (Age 3) | COLLAPSED + not in client UI | |
+| Christening Solo | §10 (ends Act 1) | MISSING | bespoke solo ceremony |
+| Dance-off attack/defend moves (QWEASD) | §23/§25 | MISSING | rhythm-combo move set — core to PvP dance-off |
+| Dance-off power-up / bonus moves | §23 | MISSING | potion/food/artifact-unlocked |
+| Body percussion / clapping / thigh-slap | §13 | MISSING | in test-bed composites only, no production path |
+| Instrument-play-during-dance | §25/§13 | MISSING | drum/conch/flute buff pose |
+| Colonist formation choreography | §1/TODO | MISSING | colonists perform in formation |
+
+**Client/sim mismatch (confirmed):** sim `DanceType` = 12 (`GameSystems.cs:151`);
+client `DancePanel.cs:11` exposes 6. Even the exposed 6 all play one avatar clip.
+
+---
+
+## 2. Work / Tools / Colonist Economy
+
+Wired distinct work clips: `chop`, `mine`, `fish`, `gathering` (Farm_Harvest),
+`farm` (PlantSeed), `hammer`/build (Fixing_Kneeling), `interact`, `weapon_attack`, `hold`.
+
+### DEAD (loaded, no trigger — cheap wins)
+| Key | Clip | Note |
+|---|---|---|
+| skin | `SkinningGround01_R_Loop` | GDD needs skinning bench (§skin); no `CharacterAnimDriver` case |
+| watering | `Farm_Watering` | GDD §2a "water crops"; colonist `farm` never routes to `watering` |
+| carry | `Walk_Carry_Loop` | GDD §19 carry modes; test-bed only in production |
+| sit | `GroundSit_Idle_Loop` | no player/colonist case |
+
+### MISSING (no clip)
+| Animation | GDD / TSK | Note |
+|---|---|---|
+| Hoe / till land | §2a, TSK | field prep |
+| Weed | §2a "colonists weed" | field tending |
+| Compost | TSK | fertility upkeep |
+| Tend irrigation / terraced gardens | TSK | paddy/terrace upkeep |
+| Feed chickens / pigs | §2d, TSK | pen feeding |
+| Collect eggs | TSK | coop gather |
+| Herd animals | TSK | drive livestock |
+| Milk goats | TSK | milking pose |
+| Shear animals | TSK | shearing pose |
+| Breed animals | TSK | pen interaction |
+| Tend kennel (dogs) | TSK | care pose |
+| Tend pearl oyster bed | TSK | shore/underwater tend |
+| Dive for shells/coral | §27, TSK | underwater gather (swim exists; no gather-underwater) |
+| Shell open/close timed grab | §27 shell mechanic | timed reach |
+| Cook (dedicated) | §29b/c | currently routes to generic `interact` |
+| Backpack crafting (player, no bench) | §6 | `craft` key never loaded → pulse placeholder |
+| Bench crafting (generic, 12 benches) | §8j | `PlayCraft`/`PlayBuild` fall through to placeholder pulse |
+| Rebuild ruins (Spirit Temple / Dance Arena) | §8f | restoration work |
+| Fuel HQ | TSK, §10 | feed the hearth |
+| Stock birdhouse / collect feathers | §8l | charisma chain |
+| Operate trade building | §15c | trade-post interaction |
+| Load / unload trade canoe | TSK | dock cargo |
+| Observe stars / stick-chart trace | §8f | sky-watch tracing minigame |
+
+### COLLAPSED
+| GDD wants | Reality |
+|---|---|
+| gather coconuts/bamboo/vines/flint/shells/starfish, forage berries/herbs/lotus | all → `gathering` (Farm_Harvest) |
+| multi-level directional chop (5 wedges, 4 facings — flagship visible-work, §4a) | single `chop` loop |
+| Carry modes: EquipHand / TwoHandCarry / ShoulderCarry / plate-tray (§19) | none — `carry` clip loaded but dead |
+
+---
+
+## 3. Combat
+
+Wired: `punch`, `run_punch`, `throw` (OverhandThrow), spear/axe/ball throws
+(Kevin, via `ThrowActionCatalog`), `shield_block`, `weapon_attack` (Sword_Attack), `death`.
+
+### DEAD (loaded, no trigger)
+`sword_block`, `melee_light_combo`, `shield_idle`, `shield_break`, `shield_dash`,
+`shield_sprint`, `swim_drown`, `swim_drowned`, `swim_left`, `swim_right`.
+
+### MISSING
+| Animation | GDD | Note |
+|---|---|---|
+| Hit reaction / stagger | §5a-ii, §5b | player + enemy take-damage — nothing wired |
+| Enemy / spirit attack set | §5a/§5b | humanoid-rigged spirits, ≥1 attack each |
+| Retrieve thrown spear (walk-over pickup) | §5a-ii | ground-item recovery beat |
+
+### COLLAPSED
+7+ weapon types (spear/axe/knife/club/trident/adze/biface) → one `Sword_Attack` thrust.
+(May be acceptable; flag for weapon-feel pass.)
+
+---
+
+## 4. Boat / Canoe / Voyage
+
+Wired: `canoe_sit` (helm idle), `canoe_dismount`, `run_to_dive`, `swim`.
+
+| Animation | GDD | Gap |
+|---|---|---|
+| Paddle (active propulsion) | §3, §10 | MISSING — only seated idle |
+| Seat-switch between roles | §3, TODO §7 | MISSING |
+| Wayfinding: star reading | §3/§24 | MISSING |
+| Wayfinding: swell reading | §3 | MISSING |
+| Wayfinding: bird following | §3/§24 | MISSING |
+| Wayfinding: storm navigation | §3 | MISSING |
+| Colonist crew / sail (autonomous) | §3, TSK "Sail" | MISSING |
+
+(Voyage is sim-resolved, so these are posed beats, not a steering controller.)
+
+---
+
+## 5. Emote / Social / Interaction
+
+Wired: `pray` only. No emote wheel / emote input exists in production.
+
+| Animation | GDD | Gap |
+|---|---|---|
+| Shrine offering (kneel/offer) | §8b | MISSING |
+| Kava ceremony | §16 | MISSING |
+| Meditate (god-mode, vulnerable) | TODO §12 | MISSING |
+| Greet / elder first-contact | §10 tutorial | MISSING |
+| Talk to colonists | §10 tutorial | MISSING |
+| Feast / first-feast celebration | §10 arc | MISSING |
+| Sit | §social | DEAD (clip loaded, no trigger) |
+
+Note: `kevin_*_social` clips (HandClap, Cheer, HandWave, Angry, Dance01-13) are
+reachable **only** through the test-bed JSONs — no production path.
+
+---
+
+## 6. Locomotion & Reaction States
+
+Wired loco is strong: idle, 8-dir walk/jog, sprint(+enter/exit), 8-dir crouch,
+turns, jump, running_jump, full swim set.
+
+| Animation | GDD | Gap |
+|---|---|---|
+| Wade (50%-speed shore water) | §27 zone 2–4m | MISSING |
+| Idle variants / fidget | §9c, disconnect-idle | MISSING — one idle only |
+| Idle-at-hearth cluster | §10 | MISSING |
+| Crouch enter / exit | — | DEAD (loaded; `SetCrouching` plays idle/walk directly) |
+| Wounded / low-health degraded | §5a-ii, §9 | MISSING |
+| Hungry / thirsty posture | §9a needs | MISSING |
+| Low-mana / low-morale | §25 | MISSING |
+| Celebration | §10 feast, §22 victory | MISSING |
+| Persist-as-idle-figure (disconnect) | §Recent | partially — reuses `idle` |
+
+(No cold state — tropical setting; correctly absent.)
+
+---
+
+## Priority ranking (studio lens)
+
+1. **Per-dance choreography + dance-off move set** — the marquee feature is a single
+   looping clip. Author 12 dance clips + the QWEASD attack/defend moves + Christening
+   Solo. Also fix the sim(12)↔client(6) `DanceType` mismatch and dead `tidedance` icon branch.
+2. **Colonist work legibility** — animal husbandry family, water/weed/compost, carry
+   modes, cook, star observation. "Real swings at real trees" is a named selling point
+   (§Recent); right now most of the economy plays 8 clips.
+3. **Survival/combat reaction layer** — hit-reaction, wounded, hungry, celebration.
+   Core to the Valheim needs model but invisible.
+4. **Boat wayfinding poses** — 4 wayfinding beats + paddle + crew.
+5. **Quick wins (DEAD clips — wiring only, no new art):** `skin`, `watering`, `carry`,
+   `sit`, `crouch_enter/exit`, `sword_block`, `melee_light_combo`, shield set, `swim_drown*`.
+
+---
+
+## Notes / caveats
+
+- "COLLAPSED" is a design call, not always a defect (weapon variants, forage variety
+  may be intentionally shared). Dance collapse is unambiguously a gap — it's the signature.
+- The `assets/dances/*.json` test-bed dances (haka_tutorial, war_challenge, etc.) are
+  authoring/preview only; they have **no code path to the in-game player or colonist**.
+- Several dance assets already exist in `dancegen/` (fertility/taming/war) but are wired
+  only to the test-bed, not to the production avatar. Bridging that is cheaper than authoring.