@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.8

package/skills/grok-generate2dsprite/SKILL.md

@@ -1,313 +0,0 @@
----
-name: generate2dsprite
-description: >
-  Generate and postprocess 2D game sprites and animation sheets: pixel-art
-  characters, NPCs, creatures, spells, projectiles, impacts, props, summons,
-  and transparent PNG/GIF exports. Use when building browser games that need
-  real sprite sheets (not code-drawn placeholders), matching a map art style,
-  or producing magenta-background sheets for chroma-key cleanup. Triggers on
-  "sprite", "sprite sheet", "animation sheet", "pixel art character", "walk
-  cycle", "attack animation", "projectile sprite", "2D game asset".
-metadata:
-  short-description: "2D sprite sheets: imagine_text_to_image + magenta chroma postprocess"
-user-invocable: false
----
-
-# Generate2dsprite
-
-Use this skill for self-contained 2D sprite or animation assets in the
-**app-builder sandbox** (TanStack Start + browser games).
-
-When a larger game or playable prototype needs sprites, use this skill for the
-visible sprite assets and keep runtime/game assembly separate (wire into Phaser /
-Canvas / DOM after export). Do not replace requested sprite assets with
-code-drawn placeholders.
-
-## App-builder / Grok environment
-
-| Item | Value |
-| --- | --- |
-| Skill dir | `.grok/skills/generate2dsprite/` |
-| Scripts | `python3 .grok/skills/generate2dsprite/scripts/<script>.py …` |
-| Image tools | `imagine_text_to_image` / `imagine_image_to_image` (path-based; see **`imagine`** skill for prompt craft) |
-| Inspect images | `read_file` on the PNG path (not Codex view_image) |
-| Generated image path | `imagine_text_to_image` returns a sandbox `file_path`; copy that path into your run dir before processing |
-| Python deps | Pillow + numpy (preinstalled in the image) |
-| Output home | Prefer `assets/sprites/<name>/` under `/workspace` so the app can import them |
-| Engine target | Browser: Canvas 2D, Phaser, or DOM/`<img>` — not Godot/Unity unless the user asks |
-
-Related skills: **`imagine`** (image tool usage), **`game-asset-core`** (+
-`game-animation-frames` / `game-character-consistency` for QC and engine-ready
-defaults), **`generate2dmap`** (maps/props), **`video2dsprite`** (denser motion
-via `imagine_image_to_video`), **`building-games`** (game loop / integration).
-
-## Parameters
-
-Infer these from the user request:
-
-- `asset_type`: `player` | `npc` | `creature` | `character` | `spell` | `projectile` | `impact` | `prop` | `summon` | `fx`
-- `action`: `single` | `idle` | `cast` | `attack` | `shoot` | `jump` | `hurt` | `combat` | `walk` | `run` | `hover` | `charge` | `projectile` | `impact` | `explode` | `death`
-- `view`: `topdown` | `side` | `3/4`
-- `sheet`: `auto` | `2x2` | `2x3` | `2x4` | `3x3` | `3x4` | `4x4` | `5x5` | `custom_grid` | `strip_1x3` | `strip_1x4`
-- `frames`: `auto` or explicit count
-- `bundle`: `single_asset` | `unit_bundle` | `spell_bundle` | `combat_bundle` | `line_bundle` | `hero_action_bundle` | `engine_atlas`
-- `effect_policy`: `all` | `largest`
-- `anchor`: `center` | `bottom` | `feet`
-- `margin`: `tight` | `normal` | `safe`
-- `art_style`: pixel_art | clean_hd | pixel_inspired | retro_pixel | map_style | project-native
-- `reference`: `none` | `attached_image` | `generated_image` | `local_file`
-- `layout_guide`: `none` | `optional` | `recommended`
-- `prompt`: the user's theme or visual direction
-- `role`: only when the asset is clearly an NPC role
-- `name`: optional output slug
-
-Read [references/modes.md](references/modes.md) when the request is ambiguous.
-
-## Agent Rules
-
-- Decide the asset plan yourself. Do not force the user to spell out sheet size, frame count, or bundle structure when the request already implies them.
-- Do not pack unrelated actions into one raw generated sheet just to satisfy a `4x4`, `5x5`, or custom engine atlas. A raw generated sheet should represent one action family, one continuous sequence, one canonical directional locomotion sheet, or one prop/asset pack.
-- For controllable heroes, main characters, and high-value player assets with multiple actions, generate separate per-action grid sheets first, QC each action, then deterministically assemble the engine-required atlas only after the grids pass visual review.
-- For controllable heroes, main characters, and high-value player body actions, default attack/shoot/cast body sheets to body-only. Do not include large slash arcs, muzzle flashes, projectiles, impact bursts, detached dust, long trails, or wide detached FX in the body sheet. Generate those as separate `fx`, `projectile`, or `impact` sheets and layer them in the game.
-- Only include wide attack FX in the same raw body sheet when the target runtime explicitly supports wider per-action cells plus per-action origin/anchor metadata. Otherwise, a wide FX bbox will force the body to shrink inside the fixed cell.
-- Write the art prompt yourself. Do not default to the prompt-builder script.
-- Use built-in `imagine_text_to_image` for every raw image.
-- Do not create raw sprite art with Three.js, Canvas, SVG, HTML/CSS drawing, PIL shape drawing, procedural geometry, placeholder primitives, or code-rendered screenshots. Runtime code may display finished generated assets, and scripts may make layout guides or postprocess generated images, but requested sprite art must originate from built-in `imagine_text_to_image`.
-- When the user provides or implies a visual reference, pass that reference's sandbox `file_path` to `imagine_image_to_image` (the tool reads the file). Also `read_file` the local reference so you can see it; a path mentioned only inside the prompt is not a visual input.
-- Do not force pixel art when the asset is a map prop for `$generate2dmap` or when the user/project requests a different style. Match the map or reference style first.
-- Use the script only as a deterministic processor: magenta cleanup, frame splitting, component filtering, scaling, alignment, QC metadata, transparent sheet export, and GIF export.
-- Do not use scripts to generate the creative image prompt. If a legacy prompt-builder command exists, treat it as historical compatibility only, not the normal skill workflow.
-- Layout guides are allowed only as deterministic geometry references for image generation. They may show slot count, spacing, centering, and safe padding, but must never define the creative art direction.
-- Treat script flags as execution primitives chosen by the agent, not user-facing hardcoded workflow.
-- If a generated sheet touches cell edges, drifts in scale, or breaks a projectile / impact loop, either reprocess with better primitive settings or regenerate the raw sheet.
-- Do not use raw single-row sheets such as `1x4`, `1x6`, `1x8`, or `1xN` for characters, players, controllable heroes, creatures, NPCs, enemies, summons, animated props, or any asset where a body/subject must stay centered. Single-row raw generation is too likely to drift horizontally and crop inconsistently.
-- For animated body assets, use a multi-row grid by default: 4 frames -> `2x2`, 6 frames -> `2x3`, 8 frames -> `2x4`, 9 frames -> `3x3`, 12 frames -> `3x4` or `4x3`, 16 frames -> `4x4`.
-- If a game engine needs a final single-row strip or mixed atlas, first generate and QC the action as a multi-row grid, then assemble the delivery strip/atlas deterministically.
-- In every animated body grid prompt, require the subject body to stay centered in each cell, full body inside the central 60% to 70% safe area, consistent scale across cells, stable feet/bottom anchor line when applicable, and no limbs, weapons, hair, capes, dust, muzzle flashes, or detached FX crossing cell edges.
-- For hero attack body prompts, explicitly require body height and body scale to match the accepted idle/run sheets, stable feet/bottom anchor, weapon kept close enough to avoid widening the body bbox, and no detached slash arc or screen-space attack effect.
-- For map prop packs, classify props before choosing a grid. Square `2x2`, `3x3`, and `4x4` packs are only for compact props. Do not put platforms, floors, bridges, walls, ladders, gates, doors, long hazards, wide/tall props, collision-bearing objects, or tileset/strip pieces into square prop packs; use one-by-one, `1x3`/`1x4` strips, custom wide cells, or a tileset-like atlas instead.
-- Keep the solid `#FF00FF` background rule unless the user explicitly wants a different processing workflow.
-
-## Workflow
-
-### 1. Infer the asset plan
-
-Pick the smallest useful output.
-
-Examples:
-
-- controllable hero with four directions -> `player` + `player_sheet`
-- side-view controllable hero with idle/run/shoot/jump -> `player` + `hero_action_bundle`
-  - idle grid sheet, usually `2x2` for 4 frames
-  - run grid sheet, usually `2x2` or `2x3` depending on needed frame count
-  - shoot grid sheet with body/weapon only, usually `2x2`
-  - jump grid sheet, usually `2x2`
-  - projectile / muzzle flash as separate assets when needed
-  - optional assembled engine atlas after per-action QC
-- side-view controllable hero with melee attack -> `player` + `hero_action_bundle`
-  - attack body grid sheet, usually `2x2` or `2x3`, body-only
-  - slash arc / weapon trail as a separate `fx` sheet when the attack needs a wide visual effect
-  - impact spark as a separate `impact` sheet when hits need feedback
-- healer overworld NPC -> `npc` + `single_asset` or `unit_bundle`
-- large boss idle loop -> `creature` + `idle` + `3x3`
-- wizard throwing a magic orb -> `spell_bundle`
-  - caster cast sheet
-  - projectile loop
-  - impact burst
-- monster line request -> `line_bundle`
-  - plan 1-3 forms
-  - per form, make the sheets the request actually needs
-
-### 2. Write the prompt manually
-
-Use [references/prompt-rules.md](references/prompt-rules.md).
-
-Choose `art_style` before writing the prompt:
-
-- Use `pixel_art` or `retro_pixel` for classic sprites, 16-bit RPG actors, and requests that explicitly ask for pixel art.
-- Use `clean_hd` for map props or assets intended to match clean hand-painted HD maps.
-- Use `pixel_inspired` only when the user wants a pixel-adjacent look without retro chunkiness.
-- Use `map_style` or `project-native` when an existing map, game, or reference should define the style.
-
-If a reference is involved:
-
-- Wire the reference into the call: pass its sandbox `file_path` to `imagine_image_to_image` — or the path list to `imagine_reference_to_image` for 2+ refs (generated images already have a `file_path`; local files use their sandbox path). Also `read_file` local references so you can see them.
-- State the reference role explicitly: preserve identity/style, create an animation sheet for the same subject, create an evolution/variant, or derive a matching prop/FX.
-- Preserve the stable identity markers from the reference: silhouette, palette, face/eye features, costume marks, major accessories, and material language.
-- Let only the requested action or evolution change. Do not redesign the subject unless the user asks.
-- Still require exact sheet shape, solid magenta background, frame containment, and same scale across frames.
-
-Keep the strict parts:
-
-- solid `#FF00FF` background
-- exact sheet shape
-- same character or asset identity across frames
-- same bounding box and pixel scale across frames
-- explicit containment: nothing may cross cell edges
-
-Mixed-action atlas guardrail:
-
-- Do not ask `imagine_text_to_image` to generate unrelated action rows in one raw sheet, such as `row 1 idle, row 2 run, row 3 shoot, row 4 jump`, for a controllable hero or main character.
-- Do not ask `imagine_text_to_image` to generate raw single-row action strips such as `1x4 idle`, `1x4 run`, `1x4 shoot`, or `1x4 jump` for a controllable hero, character, creature, NPC, enemy, summon, or animated prop.
-- If an engine needs a combined `4x4`, `5x5`, custom atlas, or row-strip delivery format, generate the action grids separately, process and QC them separately, then assemble the delivery atlas deterministically.
-- Exceptions are canonical directional locomotion sheets, one continuous long action sequence, prop packs, tileset-like atlases, and low-stakes compact enemy combat sheets. These still need one coherent prompt and visual QC.
-- Keep projectile, muzzle flash, impact, dust trails, and detached FX in separate sheets unless they are intentionally part of the same action silhouette and remain tightly attached.
-- For controllable heroes and main characters, "tightly attached" is not enough when the effect makes the action bbox much wider or taller than idle/run. Split wide slash arcs, muzzle flashes, long weapon trails, dust clouds, and impact bursts into separate FX sheets by default.
-
-Animated body grid guardrail:
-
-- `1x4` and other raw single-row sheets are not valid defaults for animated bodies. This includes players, controllable heroes, creatures, NPCs, enemies, summons, animated props, and body-attached combat actions.
-- Use `2x2` for 4-frame body actions. This is the default for idle, short attack, shoot body, jump, hurt, hover, and compact side-view walk/run actions.
-- Use `2x3` for 6-frame body actions such as cast, attack, summon, run, charge, or transformation.
-- Use `2x4`, `3x3`, `3x4`, or `4x4` for longer body actions. Prefer a compact grid over a long row.
-- For 4-direction top-down walk, `4x4` can remain a raw generation shape because it is a canonical directional locomotion sheet, not four unrelated action rows.
-- If final runtime needs a row strip, assemble it after QC from the processed multi-row grid frames.
-- Keep the character centered in every cell. The body centerline should stay near the cell center, feet/bottom anchor should stay on the same y-position when visible, and the subject should occupy only the central safe area with generous magenta padding.
-- For attack, shoot, cast, charge, and other body actions, the body height should stay close to the accepted idle/run body height. If a fixed-cell runtime is being used, reject body-action output when the body appears more than about 10-15% smaller than idle/run, even if `edge_touch_frames` is empty.
-
-Map prop pack guardrail:
-
-- Use square `2x2`, `3x3`, and `4x4` raw prop packs only for compact props such as rocks, shrubs, barrels, crates, lamps, small signs, pots, debris, and small ornaments.
-- Do not use square prop packs for wide or collision-critical map objects: floors, platforms, ledges, terrain chunks, bridges, wall runs, ladders, roads, rails, pipes, long spike traps, gates, doors, buildings, large trees, checkpoints, exits, or build pads.
-- Use one-by-one generation for unique, large, important, tall, irregular, or collision-aligned props.
-- Use `1x3` or `1x4` strips for repeatable platform/floor assets, with left cap, middle repeat, right cap, and optional slope/corner/end variant.
-- Use custom wide cells for multiple similar wide objects. The grid must state explicit non-square cell dimensions and must not mix compact props with platform/terrain objects.
-- If a square prop pack fails due to edge touch or bad cropping, do not solve it by relaxing QC. Reclassify the object and regenerate with a more suitable sheet shape.
-
-If a layout guide is useful, generate one before calling built-in `imagine_text_to_image`:
-
-```bash
-python3 .grok/skills/generate2dsprite/scripts/make_layout_guide.py \
-  --rows <rows> \
-  --cols <cols> \
-  --cell-width 384 \
-  --cell-height 384 \
-  --output <run-dir>/references/<rows>x<cols>-layout-guide.png
-```
-
-Then pass the guide PNG's sandbox path to `imagine_image_to_image` — a guide that is only "visible in conversation" never reaches the image model. Also `read_file` it so you can see the geometry. Tell `imagine_image_to_image` to use it only for invisible slot count, spacing, centering, and safe padding. The output must not reproduce guide boxes, safe-area rectangles, center marks, labels, borders, or guide background.
-
-Use layout guides deliberately:
-
-- recommended for `prop_pack_3x3`, `prop_pack_4x4`, tileset-like atlases, fixed multi-row animation grids, and non-directional 16-frame action sequences such as casting, summoning, charging, death, or transformation
-- optional for `3x3` large idle and high-value showcase loops when previous generations drift in scale or spacing
-- not the default for `4x4` four-direction walk sheets, because the guide can make directional poses too conservative; use it only after an unguided run fails layout or edge safety
-
-### 3. Generate the raw image
-
-Use built-in `imagine_text_to_image`.
-
-Do not use Three.js, Canvas, SVG, HTML/CSS, PIL drawing, or other code-generated art as the raw sprite source. These are acceptable only for runtime display, debug overlays, deterministic layout guides, or postprocessing already-generated images.
-
-After generation:
-
-- keep the returned sandbox `file_path`
-- copy that file into the working output folder as `raw-sheet.png` (or similar)
-- keep the original generated image in place
-- to run a further Imagine edit on a **postprocessed** PNG, pass that PNG's sandbox path to `imagine_image_to_image`
-
-### 4. Postprocess locally
-
-Run the processor on the raw image:
-
-```bash
-# --target is ONLY: player | npc | creature | asset
-# Map character/spell/projectile/prop/summon/fx → --target asset (or player/npc/creature).
-# --mode must be a known grid mode (idle/walk/attack/shoot/jump/…) OR pass both --rows and --cols.
-python3 .grok/skills/generate2dsprite/scripts/generate2dsprite.py process \
-  --input <run-dir>/raw-sheet.png \
-  --target <player|npc|creature|asset> \
-  --mode <idle|walk|run|attack|shoot|jump|cast|hurt|projectile|impact|fx|player_sheet|…> \
-  --output-dir <run-dir> \
-  --shared-scale \
-  --align feet
-# Custom grid example:
-#   --mode sheet --rows 2 --cols 3 --label-prefix frame
-```
-
-List valid targets/modes: `python3 …/generate2dsprite.py list-options`
-
-The processor is intentionally low-level. The agent chooses:
-
-- `rows` / `cols`
-- `fit_scale`
-- `align`
-- `shared_scale`
-- `component_mode`
-- `component_padding`
-- `edge_touch` rejection strategy
-
-Use the processor to gather QC metadata, not to make aesthetic decisions for you.
-
-For hero action bundles, process each action grid as its own sheet before any final atlas assembly. Use `component_mode=largest` for body-only hero grids. Use `component_mode=all` only for projectile, impact, aura, slash FX, or intentionally detached FX sheets, not for fixed-cell hero body attacks that need stable body scale.
-
-### 5. QC the result
-
-Check:
-
-- did any frame touch the cell edge
-- did any frame resize differently than intended
-- did detached effects become noise
-- does the sheet still read as one coherent animation
-- for hero/player body actions, does the body height match the accepted idle/run scale within roughly 10-15%
-- for fixed-cell runtimes, did a wide weapon trail or FX arc shrink the body inside the cell
-
-If not, rerun with different processor settings or regenerate the raw sheet.
-
-### 6. Return the right bundle
-
-For a single sheet, expect:
-
-- `raw-sheet.png`
-- `raw-sheet-clean.png`
-- `sheet-transparent.png`
-- frame PNGs
-- `animation.gif`
-- `prompt-used.txt`
-- `pipeline-meta.json`
-
-For `player_sheet`, expect:
-
-- transparent 4x4 sheet
-- 16 frame PNGs
-- direction strips
-- 4 direction GIFs
-
-For `spell_bundle` or `unit_bundle`, create one folder per asset in the bundle.
-
-For `hero_action_bundle`, expect:
-
-- one raw and processed sheet per action
-- per-action frame PNGs and GIFs for visual QC
-- separate projectile / muzzle / slash / impact assets when the hero shoots, casts, or uses wide melee effects
-- optional assembled `engine-atlas-transparent.png` only after per-action QC passes
-
-## Defaults
-
-- `idle`
-  - small or medium actor -> `2x2`
-  - large creature or boss -> `3x3`
-- `cast` -> prefer `2x3`
-- `projectile` -> prefer `2x2` for short animated loops; use row strips only when the engine specifically requires a strip, and assemble that strip after QC when practical
-- `impact` / `explode` -> prefer `2x2`
-- `walk`
-  - topdown actor -> `4x4` for four-direction walk
-  - side-view asset -> `2x2`
-- controllable hero or main player with multiple actions -> `hero_action_bundle`
-  - generate one action per raw multi-row grid sheet, not as a raw `1x4` strip
-  - attack/shoot/cast body sheets are body-only by default; wide slash arcs, muzzle flashes, projectiles, trails, dust, and hit impacts are separate FX/projectile/impact sheets
-  - default 4-frame action grid is `2x2`
-  - use `2x3` for 6-frame actions and `2x4`, `3x3`, `3x4`, or `4x4` for longer actions
-  - do not generate a mixed-action raw `4x4`, `5x5`, or custom atlas
-  - assemble the final atlas only as a deterministic delivery step if the game requires it
-- `4x4`, `5x5`, and custom grids
-  - use as raw generation only for one coherent long action sequence, canonical directional locomotion, prop packs, or tileset-like atlases
-  - use as delivery atlases for mixed actions only after separate action sheets pass QC
-- use `shared_scale` by default for any multi-frame asset where frame-to-frame consistency matters
-- use `largest` component mode for hero/player body grids; use `all` for separate FX/projectile/impact sheets
-
-## Resources
-
-- `references/modes.md`: asset, action, bundle, and sheet selection
-- `references/prompt-rules.md`: manual prompt patterns and containment rules
-- `scripts/generate2dsprite.py`: postprocess primitive for cleanup, extraction, alignment, QC, and GIF export

package/skills/grok-generate2dsprite/SOURCE.md

@@ -1,6 +0,0 @@
-# Source
-
-Vendored from [agent-sprite-forge](https://github.com/0x0funky/agent-sprite-forge) (`53dce6055984c610d833e77887939cbd0fb1c92b`).
-MIT License — see `LICENSE`.
-
-Adapted for Grok Build / app-builder sandbox (image tool paths, `read_file` for image inspection, workspace-relative script paths).

package/skills/grok-generate2dsprite/agentsam.skill.json

@@ -1,25 +0,0 @@
-{
-  "schema": "agentsam.skill.v1",
-  "id": "grok-generate2dsprite",
-  "name": "Grok \u00b7 generate2dsprite",
-  "description": "2D sprite sheets: imagine_text_to_image + magenta chroma postprocess",
-  "icon": "skill",
-  "slash": {
-    "suggested": "/grok-generate2dsprite"
-  },
-  "instructions": {
-    "source": "local_file",
-    "ref": "SKILL.md"
-  },
-  "execution": {
-    "mode": "turn",
-    "tools": [],
-    "operations": [],
-    "capabilities": []
-  },
-  "provenance": {
-    "source": "apps/local-studio/.grok/skills",
-    "vendor": "grok",
-    "status": "imported"
-  }
-}

package/skills/grok-generate2dsprite/references/modes.md

@@ -1,124 +0,0 @@
-# Modes
-
-Use this file when the user's wording leaves room for multiple valid asset plans.
-
-## Asset Types
-
-- `player`: controllable overworld hero
-- `npc`: role-readable town or field character
-- `creature`: monster, beast, spirit, boss, summon
-- `character`: side-view or non-overworld humanoid unit that is not specifically a player or NPC
-- `spell`: castable magic or skill sequence
-- `projectile`: loopable traveling object such as orb, arrow, fireball, bullet, beam segment
-- `impact`: hit burst, explosion, contact FX
-- `prop`: item, weapon, shrine object, pickup, deployable
-- `summon`: conjured unit or creature entrance asset
-- `fx`: generic visual effect sheet
-
-## Actions
-
-- `single`: one static sprite
-- `idle`: looped breathing / stance / aura cycle
-- `cast`: spell or skill wind-up / release
-- `attack`: attack-only body animation; for controllable heroes/main characters, wide slash arcs and hit FX should be separate `fx`/`impact` sheets
-- `shoot`: ranged attack body action; projectile and muzzle flash should usually be separate assets
-- `jump`: airborne takeoff / rise / fall / landing action
-- `hurt`: damage reaction
-- `combat`: combined attack + hurt sheet
-- `walk`: travel loop
-- `run`: faster travel loop
-- `hover`: airborne idle / travel loop
-- `charge`: power-up or dash prep
-- `projectile`: loopable travel motion
-- `impact`: contact burst
-- `explode`: stronger impact or destruction burst
-- `death`: defeat / vanish / collapse sequence
-
-## Bundle Presets
-
-- `single_asset`: one sprite or one sheet
-- `unit_bundle`
-  - default: `idle` + `combat`
-  - optional: `walk`
-- `spell_bundle`
-  - default: `cast` + `projectile` + `impact`
-- `combat_bundle`
-  - default: `idle` + `attack` + `hurt`
-- `line_bundle`
-  - default: 1-3 forms
-  - per form, choose only the needed sheets
-- `hero_action_bundle`
-  - default: one sheet per action, often `idle` + `run` + `attack` or `shoot` + `jump`
-  - keep projectiles, muzzle flashes, slash arcs, weapon trails, impacts, and dust as separate assets unless the runtime supports wider per-action cells plus explicit origins
-  - body action sheets should preserve idle/run body scale; split wide FX rather than letting it shrink the body in a fixed cell
-  - assemble an engine atlas only after each action passes QC
-- `engine_atlas`
-  - delivery format only when it combines unrelated actions
-  - build from processed action sheets, not from one mixed-action raw image
-
-## Sheet Presets
-
-- `1x4`
-  - projectiles
-  - simple looping FX
-- `2x2`
-  - standard idle
-  - attack / hurt / impact
-  - compact side-view walk
-- `2x3`
-  - cast sequences
-  - death sequences
-  - slightly richer combat actions
-- `3x3`
-  - large creature idle
-  - boss aura loops
-  - high-value showcase idles
-- `4x4`
-  - topdown 4-direction player walk sheet
-  - non-directional 16-frame action sequence when the user asks for richer casting, summoning, charging, transformation, or death animation
-- `5x5` or `custom_grid`
-  - use as raw generation only for one coherent long action sequence, prop packs, tileset-like atlases, or another single action family
-  - use as a delivery atlas for mixed actions only after separate action sheets have been generated and QC'd
-
-## Agent-First Mapping Hints
-
-- `"make a 4-direction main hero"` -> `player` + `player_sheet`
-- `"make a side-view hero with idle, run, shoot, and jump"` -> `player` + `hero_action_bundle`; generate one action sheet per action and keep projectile/impact assets separate
-- `"make a side-view hero melee attack"` -> `player` + `hero_action_bundle`; generate a body-only attack grid and separate slash/impact FX when the attack needs a wide arc
-- `"make a healer npc"` -> `npc` + `single_asset`, `role=healer`
-- `"make a healer npc walk sheet"` -> `npc` + `walk`
-- `"make a boss idle"` -> `creature` + `idle`; prefer `3x3`
-- `"make a wizard throwing a magic orb"` -> `spell_bundle`
-- `"make a fireball projectile"` -> `projectile` + `projectile`; prefer `1x4`
-- `"make a hit explosion"` -> `impact` + `impact`; prefer `2x2`
-- `"make a summon entrance"` -> `summon` + `cast` or `impact`
-- `"make a full fire samurai creature line"` -> `line_bundle`; plan 1-3 forms, then choose sheets per form
-
-## Legacy Compatibility
-
-Keep these mappings working:
-
-- `player_sheet`: 4-direction overworld walk
-- `player_walk`: 2x2 down-facing walk
-- `npc_walk`: 2x2 down-facing walk
-- `combat`: 2x2 attack + hurt
-- `evolution`: legacy concept sheet
-
-## Processor Defaults
-
-- use `shared_scale=true` for any multi-frame sheet unless inconsistent scale is intentional
-- use `align=bottom` or `feet` for grounded actors
-- use `align=center` for floating effects, projectiles, and detached FX
-- use `component_mode=largest` when raw sheets contain detached sparkles or edge debris
-- use `component_mode=all` when detached effects are an intentional part of the asset silhouette
-- for body-only controllable hero actions, use `component_mode=largest`; for projectile, impact, aura, slash FX, or intentionally detached FX sheets, use `component_mode=all`
-- reject fixed-cell hero/player body actions when the body visibly shrinks compared with the accepted idle/run scale; split the wide FX or use a runtime with wider per-action cells and explicit origins
-- use a layout guide for prop packs, tileset-like atlases, fixed atlas rows, and non-directional 16-frame VFX-heavy action sequences; avoid making it the default for 4-direction walk sheets
-
-## Output Shape
-
-- any sheet mode: transparent sheet + per-frame PNGs + GIF
-- `player_sheet`: plus direction strips and four GIFs
-- `single_asset`: cleaned transparent PNG
-- `hero_action_bundle`: per-action folders, per-action GIFs, separate projectile/impact assets when needed, and optional assembled engine atlas
-- bundles: one output folder per asset inside the bundle root