a1c48b3a84cc.Quick answer
Check the active Codex Home first, then confirm one-level folder depth, valid pet.json, a matching real PNG/WebP, exact version dimensions, and spriteVersionNumber 2 for a 2288px-tall atlas. Refresh the picker and restart once.
Start with the exact folder Codex reads
Confirm which Codex Home belongs to the running desktop application. A pet in a WSL home may not appear in a Windows-native Codex picker, and a custom CODEX_HOME changes the expected location. Avoid scattering copies across several directories before identifying the active one.
Remove accidental nesting
The expected pet folder contains pet.json and its referenced spritesheet directly. A common extraction result is ~/.codex/pets/pet-name/pet-name/pet.json, which leaves the picker looking at the wrong depth. Check capitalization, file extensions, simple folder permissions, and JSON syntax.
Match the atlas to the manifest
Legacy v1 is 1536×1872. Current v2 is 1536×2288 and must declare spriteVersionNumber 2. A renamed image is not enough if pet.json still points to another filename. Decode the image, verify exact dimensions, and confirm that the file is a real PNG or WebP rather than an HTML error page.
Refresh deliberately
Use the custom pet refresh action in Settings and restart Codex once. If the pet appears but is cropped or motion rows are wrong, loading succeeded and the problem is atlas content, scale, or row order. Keep that visual QA separate from discovery and path failures.
Completion checklist
- Active Codex Home is known
- No extra nested folder
- JSON parses
- Spritesheet path and dimensions match
- Picker was refreshed