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>
2026-08-11 16:07:41 -07:00
parent 854dbb5ce4
commit e08ad2f3e9
4 changed files with 781 additions and 0 deletions
@@ -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`.
@@ -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.
@@ -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.