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>

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`.