docs: plan Omen cat Codex pet

docs/superpowers/specs/2026-07-16-omen-cat-pet-design.md

@@ -0,0 +1,96 @@
+# Omen Cat Codex Pet Design
+
+## Goal
+
+Create a Codex-compatible v2 animated pet inspired by the user-provided cartoon Omen cat reference. The pet should preserve the reference's feline silhouette and recognizable Omen cues while moving toward a darker, more detailed game-character interpretation that remains readable in a `192x208` sprite cell.
+
+The working display name is `幽喵`. The package id will use an ASCII-safe derivative chosen by the hatch pipeline.
+
+## Source Reference
+
+Canonical input:
+
+`C:/Users/admin/AppData/Local/Temp/codex-clipboard-ecce7d4b-e0a8-495f-98ba-9bf2f2d030b4.png`
+
+The source is an identity reference, not an atlas. It must be copied into the pet run before generation so the temporary clipboard path is not a long-term dependency.
+
+## Visual Direction
+
+Use a dark flat-illustration style with restrained cel shading. Preserve these identity invariants across every animation row:
+
+- oversized purple cat-eared hood with a layered, angular Omen silhouette
+- black void face framed by the hood
+- three cyan facial energy marks, with the center mark slightly longer
+- compact feline body, short paws, and a long attached tail
+- dark charcoal armor and bandage-like limb wraps
+- deep violet, charcoal, cool gray, and luminous cyan palette
+- heavy upper silhouette balanced by a compact grounded lower body
+
+Compared with the source, add a segmented shoulder mantle, layered scarf or short cape panels, and readable foreleg wraps. Keep all added armor broad and simple enough to survive reduction to pet size.
+
+Do not include readable logos, text, weaponry, scenery, floor shadows, smoke, floating particles, detached energy effects, or thin decorative fragments. Cyan glow should be represented by opaque hard-edged color shapes rather than blur or bloom.
+
+## Animation Language
+
+The standard animation rows follow the Codex v2 contract:
+
+- `idle`: subtle breathing, ear twitch, and slow tail sway
+- `running-right` and `running-left`: low feline dash with alternating paws and cape follow-through
+- `waving`: one forepaw wave without motion marks
+- `jumping`: compact crouch, lift, apex, and landing pose without a floor cue
+- `failed`: ears lower, cyan face marks dim, body slumps, and tail curls inward
+- `waiting`: alert seated pose with raised ears and an expectant head angle
+- `running`: focused task pose using quick paw and eye activity, not literal locomotion
+- `review`: narrowed cyan marks, deliberate head tilt, and restrained paw movement
+
+`running-left` may be derived from `running-right` only when the generated armor, face marks, and lighting are fully symmetrical. Otherwise it must be generated independently.
+
+## Look Mechanics
+
+The body base and paws remain anchored. Direction is carried by a coordinated motion family:
+
+1. The cyan face marks lead and shift within the black face plane.
+2. The hood opening and head turn follow the target direction.
+3. The cat ears tilt with restrained follow-through.
+4. The upper mantle and tail lag slightly while remaining attached.
+
+Cardinal directions must be unmistakable at normal pet size. Left and right require visible head and hood-opening turns, not only moving the cyan marks. Up and down use face-mark position, hood pitch, ear angle, and upper-body compression. Intermediate directions interpolate continuously without rotating or tilting the complete sprite.
+
+## Production Flow
+
+The `hatch-pet` workflow owns production:
+
+1. Copy the canonical source into a durable run directory and prepare prompts plus layout guides.
+2. Generate a grounded base image through `imagegen`.
+3. Generate and incrementally validate all nine standard animation rows.
+4. Define the final look-mechanics note, generate four cardinal anchors, and approve their semantics.
+5. Generate coherent look rows 9 and 10 with deterministic registration and edge checks.
+6. Assemble the `1536x2288` v2 atlas, remove the chroma key once, and validate the final WebP.
+7. Run contact-sheet review, motion previews, three isolated blind direction reviews, labeled direction semantics, and continuity review.
+8. Install `pet.json` and `spritesheet.webp` together with `spriteVersionNumber: 2`.
+
+Generated row strips are always grounded by the canonical reference and the relevant layout guide. Repairs replace the smallest failed complete row rather than patching individual cells.
+
+## Failure Handling
+
+- Identity drift, missing cat features, replacement face marks, or materially changed armor require row regeneration.
+- Clipping, extraction, registration, and chroma failures use deterministic corrections first.
+- A wrong or ambiguous cardinal direction blocks packaging.
+- Minor intermediate-direction uncertainty may be accepted only when labeled normal-size review confirms the intended quadrant and the ordered loop remains coherent.
+- Detached effects, accidental transparent body holes, reversed gait, visible size popping, or broken tail attachment are hard failures.
+
+## Acceptance Criteria
+
+- The final pet visibly matches the source cat and the selected dark Omen interpretation.
+- All nine standard animation rows communicate their intended state without text or detached effects.
+- All 16 look directions form a continuous clockwise family with unmistakable cardinals.
+- The final atlas is exactly `1536x2288`; used cells are non-empty and unused cells are transparent.
+- Deterministic atlas validation, chroma despill validation, frame inspection, direction blind review, semantic review, continuity review, and final visual QA pass.
+- The installed manifest declares `spriteVersionNumber: 2` and points to the packaged `spritesheet.webp`.
+
+## Out Of Scope
+
+- Reproducing an exact in-game model or official Riot asset
+- Adding weapons, readable VALORANT branding, UI, or game environments
+- Creating alternate skins or multiple pet variants in this run
+- Publishing or distributing the resulting pet outside the local Codex installation