@codyswann/lisa 2.189.22 → 2.190.0

package/npm-package/package-lisa/package.lisa.json

@@ -3,7 +3,7 @@
     "scripts": {
       "prepublishOnly": "$npm_execpath run build",
       "setup:deploy-key": "setup-deploy-key",
-      "prepare": "$npm_execpath run build || husky install || true"
+      "prepare": "$npm_execpath run build && husky install || true"
     },
     "devDependencies": {
       "vite": "^8.0.16",

package/package.json

@@ -95,7 +95,7 @@
     "ws": ">=8.20.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.189.22",
+  "version": "2.190.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser/agents/art-director.md

@@ -1,12 +1,35 @@
 ---
 name: art-director
-description: Art director persona agent (opt-in). Critiques visual cohesion, style-guide adherence, readability, and the art-pipeline implications for a Phaser game against the project's art direction. Reviews visual design, not engine code.
+description: Art director persona agent (opt-in). Critiques visual cohesion, style-guide adherence, readability, and the art-pipeline implications for a Phaser game against the project's art direction. Demands real rendered art (not placeholders) and reviews rendered screenshots of the live game. Reviews visual design, not engine code.
+skills:
+  - phaser-asset-sourcing
 ---
 
 # Art Director Persona Agent
 
 You are the game's art director. You guard visual cohesion and make sure everything on screen reads and belongs together. You are a **critic**; you do not produce final art or write code.
 
+## Review the RENDERED game, not the code
+
+Your review is worthless if you only read source. **Look at the actual pixels**:
+run the game (`bun run dev`) and capture rendered screenshots of each scene at
+gameplay resolution (a Playwright screenshot, or ask for them). Critique what is
+on screen, not what the code claims will be on screen. If you cannot see rendered
+output, say so and treat the review as blocked — do not sign off from code alone.
+
+## Placeholder art is a BLOCKING finding
+
+Programmer-art placeholders — `generateTexture` rectangles, solid-color fills,
+untextured shapes standing in for characters/props/UI — are a **top-severity,
+blocking** result, not a stylistic nit. A scene rendered in placeholders is not
+"on style," it is **unfinished**. Flag every placeholder-only scene explicitly,
+point the team at **`phaser-asset-sourcing`** (route real, properly-licensed art
+through the pipeline), and require a linked art-debt issue for any placeholder that must
+ship temporarily. Never accept "zero binary assets / zero licensing risk" as a
+virtue — that framing is how the game ended up as wireframes. Characters must
+render with a **playing idle/walk animation**; a frozen single frame is a
+placeholder smell, flag it.
+
 ## Source of Truth — the style guide is binding
 
 - `wiki/design/art-direction.md` — the visual style guide: palette, shape language, lighting, scale, mood. Treat it as binding.
@@ -31,7 +54,12 @@ If `art-direction.md` is absent, critique against general visual-cohesion and re
 ## Art Direction Review
 
 ### Verdict
-[ON STYLE / NEEDS REVISION / OFF MODEL] — one sentence
+[ON STYLE / NEEDS REVISION / OFF MODEL / PLACEHOLDER-BLOCKED] — one sentence
+(use PLACEHOLDER-BLOCKED whenever any reviewed scene renders in placeholder art)
+
+### Rendered evidence
+- [screenshots reviewed, per scene — or "BLOCKED: no rendered output available"]
+- Placeholder/`generateTexture` art present? [list scenes] → art-debt issue linked? [#NNN / NO]
 
 ### Style-guide check
 - Palette: ... | Shape language: ... | Lighting/mood: ... | Scale/proportion: ...
@@ -53,6 +81,8 @@ If `art-direction.md` is absent, critique against general visual-cohesion and re
 
 ## Rules
 
+- Review rendered screenshots of the live game, not source code; block the review if you cannot see rendered output.
+- Treat placeholder-only / `generateTexture` art as a top-severity blocking finding; point at `phaser-asset-sourcing` and require a linked art-debt issue for anything shipping temporarily.
 - Hold every asset to the documented style guide; cite the guideline you're applying.
 - Judge cohesion and readability first — a beautiful asset that doesn't belong is a failure.
 - Always check the asset *in context* (next to existing art, at gameplay scale), not in isolation.

package/plugins/lisa-phaser/agents/audio-director.md

@@ -33,7 +33,8 @@ If `audio-direction.md` is absent, critique against general game-audio principle
 ## Audio Direction Review
 
 ### Verdict
-[ON STYLE / NEEDS WORK / SILENT GAPS] — one sentence
+[ON STYLE / NEEDS WORK / SILENT GAPS / PLACEHOLDER-BLOCKED] — one sentence
+(use PLACEHOLDER-BLOCKED when the game ships beeps/temp audio with no tracked debt)
 
 ### Audio identity check
 - Musical fit: ... | SFX language: ... | Mix priorities: ...
@@ -57,6 +58,7 @@ If `audio-direction.md` is absent, critique against general game-audio principle
 ## Rules
 
 - Map feedback coverage first — every meaningful action should be audible; flag silent state changes at top severity.
+- Treat temp/placeholder audio (synth beeps, un-sourced SFX) as tracked debt: acceptable only with a linked audio-debt issue, never as the finished mix; real audio must be sourced (CC0 or human-approved) and run through the audiosprite pipeline. Never frame "no audio assets" as zero-risk best practice.
 - Judge the mix by whether critical cues survive over music and ambience.
 - Tie issues to feedback clarity, mood, or fatigue, citing the audio-direction guideline you're applying.
 - Respect the baked audio pipeline and the mobile audio-unlock-on-first-gesture constraint; flag anything that breaks them.

package/plugins/lisa-phaser/rules/phaser.md

@@ -55,11 +55,18 @@ tools for scenes/assets/tilemaps) is defined for this project type but
    and create no objects/tweens/timers inside `update()`**; atlas everything; use
    `BitmapText` for high-churn text; use `SpriteGPULayer` / `TilemapGPULayer` for
    mass rendering. See the official `game-object-components` skill.
-7. **Baked-in asset pipeline.** Raw art in `assets/src` is packed at build time
-   (free-tex-packer-core atlases, audiosprite, BMFont) into `public/assets`, and
-   a codegen step emits typed keys to `src/assets.ts` so a missing or renamed key
-   is a **compile error**. No raw string asset / scene / event keys anywhere.
-   See `phaser-asset-pipeline`.
+7. **Baked-in asset pipeline with REAL art.** Raw art in `assets/src` is packed
+   at build time (free-tex-packer-core atlases, audiosprite, BMFont) into
+   `public/assets`, and a codegen step emits typed keys to `src/assets.ts` so a
+   missing or renamed key is a **compile error**. No raw string asset / scene /
+   event keys anywhere. The art itself must be **real and licensed** — sourced
+   per `phaser-asset-sourcing` (CC0-or-equivalent only, with an exact license
+   quote + evidence URL in `assets/LICENSES.md` and committed provenance).
+   Procedural `generateTexture` placeholders are **tracked art debt**: a scene
+   may ship them **only** with a linked art-debt issue, never as the finished
+   state and never described as "zero-asset best practice." Characters ship real
+   idle+walk animation, not static frames. See `phaser-asset-sourcing` and
+   `phaser-asset-pipeline`.
 8. **PWA on by default** via `vite-plugin-pwa` (`registerType: "autoUpdate"`,
    `globPatterns` extended to cover game assets). See `phaser-build-deploy`.
 9. **Cross-cutting services are scaffolded** in `src/services/**`: SoundService

package/plugins/lisa-phaser/skills/phaser-asset-pipeline/SKILL.md

@@ -1,27 +1,42 @@
 ---
 name: phaser-asset-pipeline
-description: This skill should be used when setting up or changing the build-time asset pipeline of a Phaser 4 game — packing raw art in assets/src into public/assets (free-tex-packer-core texture atlases, audiosprite audio sprites, BMFont bitmap fonts) and the codegen step that emits typed keys to src/assets.ts so a missing or renamed key is a compile error. Use it when adding source art, wiring packing into the build, regenerating typed keys, or eliminating raw string asset keys. Pairs with the official loading-assets skill, phaser-build-deploy, and phaser-services.
+description: This skill should be used when setting up or changing the build-time asset pipeline of a Phaser 4 game — packing raw art in assets/src into public/assets (free-tex-packer-core texture atlases, audiosprite audio sprites, BMFont bitmap fonts) and the codegen step that emits typed keys to src/assets.ts so a missing or renamed key is a compile error. Use it when adding source art, wiring packing into the build, regenerating typed keys, or eliminating raw string asset keys. Assumes the raw art already exists — get it first via phaser-asset-sourcing (CC0 sourcing + license gate). Pairs with phaser-asset-sourcing, the official loading-assets skill, phaser-build-deploy, and phaser-services.
 ---
 
 # Phaser 4 Asset Pipeline
 
+## Where the raw art comes from (read this first)
+
+This skill **packs** raw art; it does not conjure it. The inputs under
+`assets/src/**` are **real, licensed source art you sourced first** — they do not
+magically pre-exist, and they are not procedural `generateTexture` rectangles.
+Before you can pack anything, use **[[phaser-asset-sourcing]]**: it covers where
+game art comes from (curated CC0 packs like Kenney and Ninja Adventure → deriving
+CC0 art → asking the human), the strict CC0-or-equivalent license gate with
+`assets/LICENSES.md` evidence, provenance via a committed ingest script, and why
+`generateTexture` placeholders are tracked art debt rather than a finished state.
+The rule of thumb: **source → `assets/src` → pack (this skill) → typed keys.**
+
 ## Overview
 
-Runtime assets are **generated, not hand-placed**. Raw source art lives in
-`assets/src/**` (PNGs, audio, font sources); a build step packs it into
-`public/assets/**` (atlases, audio sprites, bitmap fonts) and **codegens typed
-key constants into `src/assets.ts`**. The payoff: a missing or renamed asset is a
-**compile error**, not a green square or silent-missing audio at runtime. No raw
-string asset / scene / event keys anywhere — they all come from the generated
-module (the official `loading-assets` skill covers loading those keys at runtime).
+The pipeline turns committed source art into runtime form — it is a build step,
+not a substitute for having art. Raw source art lives in `assets/src/**` (PNGs,
+audio, font sources); a build step packs it into `public/assets/**` (atlases,
+audio sprites, bitmap fonts) and **codegens typed key constants into
+`src/assets.ts`**. The payoff: a missing or renamed asset is a **compile error**,
+not a green square or silent-missing audio at runtime. No raw string asset /
+scene / event keys anywhere — they all come from the generated module (the
+official `loading-assets` skill covers loading those keys at runtime).
 
 ## Layout
 
 | Path | Role |
 | --- | --- |
-| `assets/src/sprites/**` | Raw individual PNGs — the art source of truth |
+| `assets/src/sprites/**` | Raw individual PNGs — the art source of truth (sourced per [[phaser-asset-sourcing]]) |
 | `assets/src/audio/**` | Raw audio clips (wav/ogg sources) |
 | `assets/src/fonts/**` | Font sources for BMFont generation |
+| `assets/LICENSES.md` | License evidence per source pack (CC0 quote + evidence URL) — see [[phaser-asset-sourcing]] |
+| `scripts/ingest-assets.mjs` | The provenance record — how each frame was carved from its source pack into `assets/src` (re-runnable) |
 | `public/assets/**` | **Generated** packed output (atlases, audiosprites, fonts, `pack.json`) — git-ignored or committed as a build artifact |
 | `src/assets.ts` | **Generated** typed key constants — never edited by hand |
 | `scripts/pack-assets.mjs` | The pipeline driver (runs the three packers + codegen) |
@@ -43,16 +58,34 @@ const images = await Promise.all(
   })));
 
 const files = await packAsync(images, {
-  textureName: "game", width: 2048, height: 2048,
-  padding: 2, allowRotation: false, allowTrim: true,
-  exporter: "JsonHash", removeFileExtension: true,
+  textureName: "game", width: 4096, height: 4096,
+  packer: "MaxRectsPacker", packerMethod: "Smart", // see gotcha below
+  padding: 2, extrude: 1,                            // 1px extrude kills bleeding at integer scales
+  allowRotation: false, allowTrim: false,            // pixel-art-safe (see below)
+  detectIdentical: true,
+  exporter: "JsonHash", removeFileExtension: true, prependFolderName: true,
 });
 for (const f of files) await writeFile(`public/assets/atlases/${f.name}`, f.buffer ?? f.content);
 ```
 
 The frame names in the manifest become the atlas frame keys you reference as
 generated constants. Atlas everything that renders together — loose images break
-sprite batching (the official `loading-assets` skill).
+sprite batching (the official `loading-assets` skill). Full-screen backdrops and
+parallax layers are the exception: copy them verbatim into `public/assets/images`
+and `load.image` them — they would bloat an atlas. Even this exception keeps the
+no-raw-string promise: the codegen step emits one generated constant per copied
+image (the `Img` record below), and the loader derives the file path from the
+key in exactly one place — a call site never spells out a path string.
+
+**Packer gotcha (verified in the reference implementation):** use
+`packer: "MaxRectsPacker"` with `packerMethod: "Smart"`. The other packer methods
+produce degenerate single-row *strip* atlases that waste enormous texture space
+and can blow past the max texture size. **For pixel art**, set `allowTrim: false`
+and `allowRotation: false`: trimming makes animation frames different sizes so
+anchors swim between frames, and rotation makes Phaser frame-flipping non-trivial.
+Add `extrude: 1` to stop edge bleeding when the game renders at integer scales.
+Keep inputs **sorted** and emit **no timestamps** so the packed output is
+deterministic and can be committed + `git diff --exit-code`-checked in CI.
 
 ## Step 2: audio sprites with audiosprite
 
@@ -90,10 +123,13 @@ the step that turns runtime failures into compile failures:
 const atlas = JSON.parse(await readFile("public/assets/atlases/game.json", "utf8"));
 const frames = Object.keys(atlas.frames); // raw keys, e.g. "player/idle"
 const sfx = Object.keys(JSON.parse(await readFile("public/assets/audio/sfx.json","utf8")).spritemap);
+const images = (await readdir("public/assets/images", { recursive: true }))
+  .filter(f => f.endsWith(".png")).sort(); // standalone backdrops/parallax layers
 
 const out = `// AUTO-GENERATED by scripts/pack-assets.mjs — do not edit.
 export const Tex = { GameAtlas: "game" } as const;
 export const Frame = { ${frames.map(k => `${toIdent(k)}: "${k}"`).join(", ")} } as const;
+export const Img = { ${images.map(p => `${toIdent(p)}: "img-${p.replace(/\.png$/u, "")}"`).join(", ")} } as const;
 export const Audio = { Sfx: "sfx" } as const;
 export const Sfx = { ${sfx.map(s => `${toIdent(s)}: "${s}"`).join(", ")} } as const;
 export const Font = { UI: "ui" } as const;
@@ -103,11 +139,20 @@ export const GameEvent = { ScoreChanged:"score-changed", EnemyDied:"enemy-died"
 await writeFile("src/assets.ts", out);
 ```
 
-Scenes import `Tex`, `Frame`, `Sfx`, `Font`, `SceneKeys`, `GameEvent` — never an
-inline string. Rename art, re-run the pipeline, and every now-stale reference
-fails `bun run typecheck` immediately. (Scene/event keys are kept in the same
-generated module so they share the no-raw-string discipline; edit them via the
-codegen template, not by hand.)
+Scenes import `Tex`, `Frame`, `Img`, `Sfx`, `Font`, `SceneKeys`, `GameEvent` —
+never an inline string. Rename art, re-run the pipeline, and every now-stale
+reference fails `bun run typecheck` immediately. (Scene/event keys are kept in
+the same generated module so they share the no-raw-string discipline; edit them
+via the codegen template, not by hand.)
+
+**Animation keys are the one deliberately hand-authored layer.** Codegen cannot
+know how frames group into cycles, so animation keys live in a hand-written
+`as const` record (e.g. `AnimKeys` / `FxAnims`) whose frame sequences are built
+from the generated `Frame` constants — and the contract test below proves every
+frame those definitions reference exists in the committed atlases. The typed-key
+guarantee is therefore: **generated** constants for textures, frames, images,
+audio, and fonts; **hand-authored typed constants + contract-test coverage** for
+animation keys. Nothing is a raw inline string either way.
 
 ## Step 5: wire into the build
 
@@ -133,8 +178,37 @@ generated files for immutable caching ([[phaser-build-deploy]]).
 - `assets/src/**` is the source of truth; `public/assets/**` and `src/assets.ts`
   are generated — treat them as build output (re-runnable, not hand-edited).
 - One atlas per render group, one audiosprite per SFX set, BMFont for hot text.
-- A contract test asserts every constant in `src/assets.ts` resolves to an entry
-  in the generated `pack.json`/manifests ([[phaser-testing]]).
+- A **contract test** asserts every frame name the game *derives by convention*
+  (e.g. `battlerWalkFrame(ref, dir, n)`, FX-strip frame lists, per-speaker
+  portrait keys) resolves to a real entry in the committed atlas JSON under
+  `public/assets`. The other constants in `src/assets.ts` (`SceneKeys`,
+  `GameEvent`, `Font`, `Audio`, standalone `Img` entries) are plain generated
+  literals already enforced by TypeScript at every use site, so they don't need
+  a runtime check — only names built at runtime from a pattern can go stale
+  silently without one. This keeps that narrower guarantee honest: a renamed or
+  missing frame fails a headless Vitest assertion instead of rendering a silent
+  black square. The test reads the packed JSON directly — zero Phaser
+  ([[phaser-testing]]):
+
+  ```ts
+  const frames = new Set(Object.keys(
+    JSON.parse(readFileSync("public/assets/atlases/battlers.json", "utf8")).frames));
+  for (const ref of BATTLER_REFS)
+    for (const dir of DIRS) {
+      expect(frames).toContain(battlerIdleFrame(ref, dir));
+      expect(frames).toContain(battlerAttackFrame(ref, dir));
+      for (let n = 0; n < WALK_FRAME_COUNT; n++)
+        expect(frames).toContain(battlerWalkFrame(ref, dir, n));
+    }
+  // ...and one loop per remaining derived family (FX-strip frame lists,
+  // per-speaker portrait keys, …) — the test is only done when EVERY name the
+  // game can derive at runtime has been asserted against the committed atlas.
+  ```
+
+- Ship a `--check` mode on the pack script: it re-packs into a temp staging area
+  and exits non-zero if any committed output under `public/assets` — atlases,
+  standalone images, audio, fonts alike — or `src/assets.ts` is stale, so CI
+  proves the committed artifacts (and every generated key they back) are current.
 - The generated `src/assets.ts` is the single source of asset/scene/event keys —
   the no-raw-string-keys rule depends on it existing.