summer-engine 2.3.0 → 2.5.0

package/skills/2d-assets/instantiate-asset-pack/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: instantiate-asset-pack
+description: Use when the user wants to import or spawn an entire asset pack (the multi-slice ArtAsset produced by `create-asset-sheet`) into the current scene — not a single slice, the whole pack. Reads the pack's per-slice metadata (zOrder, isComposite, parentSliceIndex, widget, bbox), groups composites, sorts children by paint order, and emits the Sprite2D / Node2D / NinePatchRect ops to lay it out correctly. Trigger on "import the X pack", "spawn the UI from pack Y", "bring in that asset sheet", "add the panel from the pack".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 2d-assets
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_get_scene_tree summer_import_from_url
+paths: ["assets/**", "art/**", "ui/**", "scenes/**"]
+---
+
+# instantiate-asset-pack — Instantiate Asset Pack into Scene
+
+A pack ArtAsset (produced by `summer:2d-assets/create-asset-sheet`) is a bundle of cropped slice PNGs with per-slice metadata. This skill is the runtime side: given a pack, lay its slices into the current scene as a correctly-grouped, correctly-layered set of nodes.
+
+For wiring individual widget slices (9-slice panels, progress bars, toggles), this skill delegates to `summer:2d-assets/use-widget-asset`. This skill handles the pack-level layout: grouping composites, paint order, spatial offset, naming.
+
+## When to use
+
+- "Import the dungeon UI pack."
+- "Spawn the settings panel from that asset sheet I just made."
+- "Bring the whole biome pack into this scene."
+- "Add the card frame composite from pack X."
+- User has a pack ArtAsset in their library and wants it placed in the scene, not just imported as files.
+
+## When NOT to use
+
+- User wants a single slice → import it directly as a `Sprite2D` (or `summer:2d-assets/use-widget-asset` if it's a UI widget).
+- User wants to **generate** a new pack → `summer:2d-assets/create-asset-sheet`.
+- User wants to apply a slice as a material/texture on a 3D mesh → not the pack flow; see `asset_pipeline.json`.
+
+## Pack JSON shape
+
+Full schema: `publicsummerengine/public/knowledge/asset_pack_schema.json`.
+
+The per-slice fields this skill cares about:
+
+| Field | Used for |
+|---|---|
+| `name` | Node name |
+| `url` | Texture path (after `summer_import_from_url`) |
+| `bbox` | Spatial offset of composite children relative to parent |
+| `zOrder` | `z_index` on the Sprite2D; sort children by this ascending |
+| `isComposite` | Filter out parent slices (flat previews, not runtime assets) |
+| `parentSliceIndex` | Group children to their composite parent |
+| `pairWith` | Toggle ON/OFF pair link |
+| `widget` | Wrap in NinePatchRect / TextureProgressBar via `use-widget-asset` |
+| `category` | Decide wrapper type — `ui` → Control tree, else Node2D/Sprite2D |
+
+Legacy fallback: `slice.zOrder ?? slice.layerIndex ?? packFileIndex`, `slice.isComposite ?? slice.isReference ?? false`. `packFileIndex` is the iteration counter when looping `packFiles[]`, not a stored field.
+
+## Standalone child slice
+
+A standalone slice has no `parentSliceIndex` and isn't a composite parent. Spawn as a single `Sprite2D`:
+
+1. Import the slice URL via `summer_import_from_url` to get a `res://` path.
+2. `summer_add_node` — type `Sprite2D`, name `slice.name`.
+3. `summer_set_prop` — `texture = res://...`.
+4. If `slice.zOrder` is set, `summer_set_prop` — `z_index = slice.zOrder`.
+
+If the slice has a `widget` field, hand off to `summer:2d-assets/use-widget-asset` after step 1.
+
+## Composite parent + children
+
+A composite parent (`isComposite: true`) is the flat preview the wizard made of the assembled panel. **Do not spawn it.** Its children — slices whose `parentSliceIndex` points back at it — are the real runtime assets.
+
+Recipe:
+
+1. **Skip the parent.** Filter out `isComposite: true` slices unless the user asked for the flat preview.
+2. **Group children.** Collect every slice whose `parentSliceIndex` matches this parent's index.
+3. **Sort children by `zOrder` ascending.** Lower zOrder renders behind. Use the legacy fallback chain.
+4. **Spawn a `Node2D` parent** named after the composite parent's `name` (e.g. `settings_panel`).
+5. **For each child, in sorted order:**
+   - Import `child.url` → `res://` path.
+   - `summer_add_node` `Sprite2D` under the Node2D, name = `child.name`.
+   - `summer_set_prop` — `texture = res://...`.
+   - `summer_set_prop` — `z_index = child.zOrder`.
+   - `summer_set_prop` — `position = Vector2(child.bbox.x - parent.bbox.x, child.bbox.y - parent.bbox.y)`.
+6. **Apply widget post-processing** to any child with a `widget` field — see next section.
+
+## Widget post-processing
+
+When a child slice has `widget.kind` set, the bare Sprite2D is not the right node. Replace or wrap it per the widget mapping:
+
+| widget.kind | Node | Mapping |
+|---|---|---|
+| `panel`, `button` | `NinePatchRect` | `frameMargins[0..3]` → `patch_margin_left/top/right/bottom` |
+| `progress_bar` | `TextureProgressBar` | `fillRect` → `stretch_margin_*`; `orientation` → `fill_mode` |
+| `slider` | `HSlider`/`VSlider` + `NinePatchRect` track | track uses `frameMargins`; slider sits on top |
+| `toggle` | `TextureRect` | Swap `texture` between this slice and `packFiles[pairWith].url` |
+
+Delegate the actual wiring (percentage-to-pixel conversion, node-specific props) to `summer:2d-assets/use-widget-asset`. This skill places the node; that skill configures the geometry.
+
+## Naming convention
+
+- `slice.name` is canonical. The wizard's classifier produces snake_case names (`play_button`, `health_bar_fill`, `settings_panel`). Use as the node name verbatim.
+- If the user said "name them with prefix X" (e.g. "prefix everything with `hud_`"), prepend: `hud_play_button`.
+- Composite parent's `name` becomes the `Node2D` wrapper name.
+- If a name collides with an existing node in the scene, suffix `_1`, `_2`, etc. Do not silently overwrite.
+
+## Examples
+
+### Example 1 — Standalone slice import
+
+Pack has one non-composite slice, `crate_wooden`, no widget metadata. Place it at scene origin:
+
+```json
+{
+  "ops": [
+    {
+      "op": "AddNode",
+      "parent": ".",
+      "type": "Sprite2D",
+      "name": "crate_wooden"
+    },
+    {
+      "op": "SetProp",
+      "path": "./crate_wooden",
+      "key": "texture",
+      "value": "res://assets/images/crate_wooden.png"
+    },
+    {
+      "op": "SetProp",
+      "path": "./crate_wooden",
+      "key": "position",
+      "value": "Vector2(0, 0)"
+    },
+    { "op": "SaveScene" }
+  ]
+}
+```
+
+### Example 2 — Composite panel with three children
+
+Pack has a composite parent `settings_panel` (filtered out) plus three children:
+
+- `panel_bg` — zOrder 0, bbox offset (0, 0), widget.kind = `panel`, frameMargins present
+- `apply_button` — zOrder 1, bbox offset (40, 120), widget.kind = `button`, frameMargins present
+- `close_icon` — zOrder 2, bbox offset (220, 8), no widget
+
+```json
+{
+  "ops": [
+    {
+      "op": "AddNode",
+      "parent": ".",
+      "type": "Node2D",
+      "name": "settings_panel"
+    },
+    {
+      "op": "AddNode",
+      "parent": "./settings_panel",
+      "type": "NinePatchRect",
+      "name": "panel_bg"
+    },
+    {
+      "op": "SetProp",
+      "path": "./settings_panel/panel_bg",
+      "key": "texture",
+      "value": "res://assets/images/panel_bg.png"
+    },
+    {
+      "op": "SetProp",
+      "path": "./settings_panel/panel_bg",
+      "key": "z_index",
+      "value": 0
+    },
+    {
+      "op": "SetProp",
+      "path": "./settings_panel/panel_bg",
+      "key": "position",
+      "value": "Vector2(0, 0)"
+    },
+    {
+      "op": "AddNode",
+      "parent": "./settings_panel",
+      "type": "NinePatchRect",
+      "name": "apply_button"
+    },
+    {
+      "op": "SetProp",
+      "path": "./settings_panel/apply_button",
+      "key": "texture",
+      "value": "res://assets/images/apply_button.png"
+    },
+    {
+      "op": "SetProp",
+      "path": "./settings_panel/apply_button",
+      "key": "z_index",
+      "value": 1
+    },
+    {
+      "op": "SetProp",
+      "path": "./settings_panel/apply_button",
+      "key": "position",
+      "value": "Vector2(40, 120)"
+    },
+    {
+      "op": "AddNode",
+      "parent": "./settings_panel",
+      "type": "Sprite2D",
+      "name": "close_icon"
+    },
+    {
+      "op": "SetProp",
+      "path": "./settings_panel/close_icon",
+      "key": "texture",
+      "value": "res://assets/images/close_icon.png"
+    },
+    {
+      "op": "SetProp",
+      "path": "./settings_panel/close_icon",
+      "key": "z_index",
+      "value": 2
+    },
+    {
+      "op": "SetProp",
+      "path": "./settings_panel/close_icon",
+      "key": "position",
+      "value": "Vector2(220, 8)"
+    },
+    { "op": "SaveScene" }
+  ]
+}
+```
+
+After this, hand `panel_bg` and `apply_button` to `summer:2d-assets/use-widget-asset` to set `patch_margin_*` from their `widget.frameMargins`.
+
+Note the ops format: `position` is the **Godot string** `"Vector2(0, 0)"`, not a JSON object. `z_index` is a bare integer. This is the format Summer Engine expects — see the publicsummerengine CLAUDE.md.
+
+## Failure modes
+
+- **Old pack with no `zOrder`.** Fall back to `slice.zOrder ?? slice.layerIndex ?? packFileIndex`. `packFileIndex` is the iteration counter when looping `packFiles[]` (not a persisted field). If even `layerIndex` is missing (very old pack), iteration order is the only signal — accept it.
+- **Old pack with no `isComposite`.** Fall back to `slice.isComposite ?? slice.isReference ?? false`. If both are missing on every slice, treat the whole pack as standalone — no compositing, every slice spawns at origin as its own Sprite2D.
+- **Composite parent with no children in the pack.** The composite preview is the only thing the user has — render the parent as a regular Sprite2D (do not filter it out in this case).
+- **Child references a parent that's missing.** Treat the child as standalone. Spawn at `Vector2(0, 0)` with its own `zOrder`.
+- **Widget with no `frameMargins`.** The vision detector said `kind: 'panel'` but didn't emit margins. Render as `TextureRect` (or `Sprite2D` if outside a Control tree) and skip 9-slice. Do not invent margins.
+- **Name collision in scene.** Suffix `_1`, `_2`, etc. Never overwrite an existing node.
+- **Slice URL fails to import.** `summer_import_from_url` returns an error — skip that slice, log a warning, continue with the rest. Do not abort the whole pack.
+
+## Related skills
+
+- `summer:2d-assets/create-asset-sheet` — production side; how the pack was made.
+- `summer:2d-assets/use-widget-asset` — wiring an individual widget slice (NinePatchRect, TextureProgressBar geometry).
+- `asset_pipeline.json` — broader find-or-generate -> import -> apply flow.

package/skills/2d-assets/pixel-art/SKILL.md

@@ -177,4 +177,4 @@ After the asset is wired:
 - `summer:2d-assets/sprite-sheet` — animated pixel frames.
 - `summer:2d-assets/character-portrait` — high-res counterpart.
 - `summer:asset-pipeline/asset-strategy` — meta-router.
-- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `references/mcp-tools-reference.md` — `summer_generate_image` schema.

package/skills/2d-assets/skybox-panorama/SKILL.md

@@ -204,4 +204,4 @@ After the sky is wired:
 - `summer:2d-assets/tileable-texture` — ground/floor counterpart.
 - `summer:scene-composition` — WorldEnvironment placement and configuration.
 - `summer:asset-pipeline/asset-strategy` — meta-router.
-- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `references/mcp-tools-reference.md` — `summer_generate_image` schema.

package/skills/2d-assets/sprite-sheet/SKILL.md

@@ -236,4 +236,4 @@ After the animation is wired:
 - `summer:2d-assets/character-portrait` — base portrait for higher-res characters.
 - `summer:animation/generate-motion` — 3D-skeletal counterpart.
 - `summer:audio/sound-effect` — frame-synced SFX.
-- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `references/mcp-tools-reference.md` — `summer_generate_image` schema.

package/skills/2d-assets/tileable-texture/SKILL.md

@@ -202,4 +202,4 @@ After the texture is wired:
 - `summer:asset-pipeline/asset-strategy` — meta-router and 3D pipeline.
 - `summer:2d-assets/skybox-panorama` — sky/environment counterpart.
 - `summer:scene-composition` — applying textures to CSG and MeshInstance3D.
-- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `references/mcp-tools-reference.md` — `summer_generate_image` schema.

package/skills/2d-assets/ui-graphics/SKILL.md

@@ -207,4 +207,4 @@ After the UI graphic is wired:
 - `summer:2d-assets/character-portrait` — for in-UI character images.
 - `summer:2d-assets/pixel-art` — pixel-style UI.
 - `summer:scene-composition` — Theme and Control hierarchy.
-- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `references/mcp-tools-reference.md` — `summer_generate_image` schema.

package/skills/2d-assets/use-widget-asset/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: use-widget-asset
+description: Use when consuming a widget slice (panel, button, slider, progress bar, or toggle pair) from a `create-asset-sheet` pack into a Godot scene. The pack's metadata.sliceMeta carries 9-slice margins, fill rects, and on/off pair links per slice — this skill explains how to wire those into NinePatchRect / TextureProgressBar / TextureRect so the asset behaves like a real UI control instead of a static texture.
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 2d-assets
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_get_scene_tree
+paths: ["assets/**", "art/**", "ui/**", "scenes/**"]
+---
+
+# use-widget-asset — Wire a sliced widget into a real Godot control
+
+When the `create-asset-sheet` wizard sees a stretchable UI element (a panel, a slider, a progress bar, a toggle), it returns more than a flat PNG. It returns geometry: **9-slice frame margins** for stretchable rectangles, and a **fill rect** for value-driven widgets. It also pairs ON/OFF toggle slices via `pairWith`. This skill is the runtime side: how to read that metadata and wire the asset into the right Godot node.
+
+If a slice has no widget metadata, treat it as a static texture (`TextureRect`) and skip this skill.
+
+## Shape support (read first)
+
+The single rule that governs everything below:
+
+> **9-slice for any AABB-fitting stretchable widget. Static texture for everything else.**
+
+Concrete:
+
+| Shape | Approach | Why |
+|---|---|---|
+| Rectangle (panel, button, bar, frame) | `NinePatchRect` with `frameMargins` | 4 corners stay fixed, 4 edges stretch on one axis, center stretches both. Standard 9-slice. |
+| Rounded rectangle | `NinePatchRect` with `frameMargins` | Corner radii live inside the fixed corner cells. Identical to plain rectangle. |
+| Circle / ellipse (round button, gem) | Static `TextureRect`, scale uniformly | No edge to stretch — the shape has no "interior to grow." |
+| Diamond / hexagon (badge) | Either ship at multiple sizes OR static texture, scale uniformly | 9-slice would distort the angled corners. SDF would solve it but is overkill for this pipeline. |
+| Diagonal banner | `NinePatchRect`, accept some distortion | Slopes sit in the fixed corner cells; horizontal middle stretches. Looks fine if not stretched aggressively. |
+| Organic shape (scroll, ribbon, painted sash) | Static `TextureRect` | Not stretchable in any direction. Regenerate at the target size if you need a different one. |
+
+The wizard's vision detector only emits `widget` metadata for the 5 kinds it knows how to slice (slider, progress_bar, toggle, panel, button). Anything else lands as a static `category: ui` slice with no `widget` field — fall through to "render as TextureRect" and skip the rest of this skill.
+
+## What the pack hands you
+
+The wizard saves the pack as a single ArtAsset with:
+
+```
+isPack: true
+packFiles: [{ url, name, type: "image/png" }, ...]
+metadata.sliceBboxes: { "0": {x,y,w,h}, "1": ... }  // source-sheet coords
+metadata.sliceMeta:   { "0": { category, widget?, pairWith?, parentSliceIndex? }, ... }
+```
+
+`widget` looks like:
+
+```
+{
+  kind: "slider" | "progress_bar" | "toggle" | "panel" | "button",
+  frameMargins: [leftPct, topPct, rightPct, bottomPct],   // optional
+  fillRect:    [xPct, yPct, wPct, hPct],                  // optional
+  orientation: "horizontal" | "vertical",                 // optional
+  pairCandidate: boolean                                  // optional
+}
+```
+
+Margins and rect are **percentages of the SLICE's own pixel dimensions** (not the source sheet). Convert to pixels with `Math.round(pct * sliceWidth / 100)` before applying to a Godot node.
+
+## Decision tree
+
+```
+kind?
+  ├─ "panel" or "button"
+  │     └─ NinePatchRect, set patch_margin_* from frameMargins
+  ├─ "slider"
+  │     └─ HSlider/VSlider with two TextureRects underneath: track + fill
+  ├─ "progress_bar"
+  │     └─ TextureProgressBar with texture_under = 9-slice frame,
+  │        texture_progress = cropped fill region
+  └─ "toggle"
+        └─ TextureRect that swaps texture between on/off via pairWith
+```
+
+## Recipes
+
+### 1. Panel — NinePatchRect
+
+```gdscript
+extends NinePatchRect
+
+@export var slice_url: String
+@export var frame_margins: Array  # [L, T, R, B] in percentage
+@export var slice_size: Vector2   # the slice's pixel dimensions
+
+func _ready():
+    texture = load(slice_url)
+    var w = slice_size.x
+    var h = slice_size.y
+    patch_margin_left   = int(round(frame_margins[0] * w / 100.0))
+    patch_margin_top    = int(round(frame_margins[1] * h / 100.0))
+    patch_margin_right  = int(round(frame_margins[2] * w / 100.0))
+    patch_margin_bottom = int(round(frame_margins[3] * h / 100.0))
+```
+
+When the NinePatchRect is sized larger than the source, corners stay fixed, edges stretch on one axis, center stretches both. This is exactly the behavior the wizard's widget detection assumes.
+
+### 2. Progress bar — TextureProgressBar (fill_mode = FILL_LEFT_TO_RIGHT)
+
+```gdscript
+extends TextureProgressBar
+
+@export var slice_url: String          # The full bar (frame + fill at 100%)
+@export var fill_rect: Array           # [x, y, w, h] in percentage
+@export var orientation: String = "horizontal"
+
+func _ready():
+    var tex = load(slice_url)
+    # The base / "under" texture is the same image — Godot will mask it
+    # to whatever value 0-100 we set.
+    texture_under  = tex
+    texture_progress = tex
+    fill_mode = TextureProgressBar.FILL_LEFT_TO_RIGHT if orientation == "horizontal" else TextureProgressBar.FILL_TOP_TO_BOTTOM
+    # The fill rect tells Godot which sub-region of the texture is the
+    # bar fill (vs the frame). Texture_progress_offset + stretch_margin_*
+    # form the inset.
+    var sw = tex.get_width()
+    var sh = tex.get_height()
+    var fx = int(round(fill_rect[0] * sw / 100.0))
+    var fy = int(round(fill_rect[1] * sh / 100.0))
+    var fw = int(round(fill_rect[2] * sw / 100.0))
+    var fh = int(round(fill_rect[3] * sh / 100.0))
+    stretch_margin_left   = fx
+    stretch_margin_top    = fy
+    stretch_margin_right  = sw - (fx + fw)
+    stretch_margin_bottom = sh - (fy + fh)
+```
+
+Set `value` from 0 to 100 to drive the bar.
+
+### 3. Slider — HSlider with TextureRect overlays
+
+`Slider` in Godot is a behavioral node (drag input + value range); it doesn't ship visuals on its own. Combine it with two `TextureRect`s underneath: one for the track (the slice texture, optionally as NinePatchRect for stretch) and one for the knob (a separate small slice cut from the slider's `fillRect` end).
+
+Simplest wiring: NinePatchRect for the track using `frameMargins`, an HSlider on top with `flat = true` and `theme_override_styles/grabber_area = null`, and a child `TextureRect` for the knob positioned via `slider.ratio`.
+
+### 4. Toggle — TextureRect that swaps texture via pairWith
+
+```gdscript
+extends TextureRect
+
+@export var on_url: String   # The slice with name ending in "_on"
+@export var off_url: String  # The pair's URL (sliceMeta.pairWith)
+
+var _state := false
+
+func set_state(on: bool) -> void:
+    _state = on
+    texture = load(on_url if on else off_url)
+
+func _ready():
+    texture = load(off_url)
+```
+
+In the pack, find the pair: `sliceMeta[currentIndex].pairWith` gives the other slice's index; look it up in `packFiles[pairIndex].url`.
+
+## Cut-offs and re-renders
+
+If the detected `frameMargins` are obviously wrong (the dashed overlay in the wizard's lightbox shows the center area clipping into a corner ornament), the user should hit **Recreate (HD)** on that slice. FLUX will regenerate it cleanly — but the *margins themselves* don't get re-detected after upscale. Margins live on the original detection. The user can also manually edit them in code via the `patch_margin_*` properties after instantiating.
+
+## Composite panels with sub-elements
+
+When a slice has `parentSliceIndex` set, it came from a **Break-down** pass — the parent is a composite (settings panel, card frame) and this slice is one of its sub-elements (Apply button, slider, toggle). Use either:
+
+- The whole parent as a single `NinePatchRect` for the frame, OR
+- Instantiate each sub-element individually positioned where the original panel had them (the parent's `sliceBboxes[parentSliceIndex]` gives the source-sheet rect; each sub-slice's relative position within it is recoverable from its own bbox).
+
+Pick based on whether your game needs the panel to stretch as one unit or whether each control needs independent interaction.
+
+See **Composite Panels (Sliced Further)** below for the canonical fields the wizard now emits (`isComposite`, `zOrder`) and the consume recipe.
+
+## Composite Panels (Sliced Further)
+
+The wizard's Break-down pass produces two new per-slice fields the runtime must understand:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `isComposite` | boolean | True on the **parent** slice — the flat preview image of the assembled panel. NOT a runtime asset. Filter it out on import unless the caller explicitly wants the preview thumbnail. |
+| `zOrder` | number | Back-to-front paint order on children. Lower = behind. Matches Godot `z_index`, Unity `sortingOrder`, CSS `z-index`. |
+| `parentSliceIndex` | number | Set on each child, points at the composite parent. Used to group children. |
+
+The full schema lives at `publicsummerengine/public/knowledge/asset_pack_schema.json`. Read it once if you need to know every field.
+
+### Consume recipe
+
+1. **Filter out composite parents.** Drop any slice with `isComposite: true` unless the caller specifically asked for the flat preview.
+2. **Group by `parentSliceIndex`.** Slices that share a `parentSliceIndex` belong to the same composite group. Slices without it are standalone.
+3. **Sort each group by `zOrder` ascending.** Lower values render behind higher values. This determines paint order.
+4. **Spawn `Node2D` parent + `Sprite2D` children.** Name the parent after the original composite parent's slice name. For each child:
+   - `name = child.name`
+   - `texture = imported res:// path`
+   - `z_index = child.zOrder`
+   - `position = Vector2(child.bbox.x - parent.bbox.x, child.bbox.y - parent.bbox.y)` — offset relative to the parent's source-sheet rect.
+5. **Apply widget post-processing.** If any child has a `widget` field, wrap or replace its `Sprite2D` with the appropriate Control node per the recipes above (panel → `NinePatchRect`, progress_bar → `TextureProgressBar`, etc.).
+
+For the full instantiation flow (op JSON, examples), use `summer:2d-assets/instantiate-asset-pack`.
+
+### Legacy compatibility
+
+Older packs (saved before the rename) used different field names. Always fall back:
+
+```
+const zOrder      = slice.zOrder      ?? slice.layerIndex   ?? packFileIndex;
+const isComposite = slice.isComposite ?? slice.isReference  ?? false;
+```
+
+`packFileIndex` is the slice's iteration position in `packFiles[]` (the loop counter, not a persisted field). On packs with no `zOrder` and no `layerIndex` at all, iteration order is the only signal you get — accept it and move on.
+
+Check `metadata.schemaVersion` on the pack: `null` (or absent) = legacy, `1` = current. New packs from the wizard always set it.
+
+## What this skill does NOT cover
+
+- Auto-tiling terrain (Wang / 47-tile). Different format entirely — see `summer:2d-assets/tileable-texture`.
+- Animated UI (button press-down sprites, hover glow). The wizard captures static frames; for animation see `summer:2d-assets/sprite-sheet`.
+- Non-AABB widgets in the 9-slice path. See the **Shape support** table at the top — for circles, hexagons, organic shapes, fall through to `TextureRect` and skip 9-slice entirely.

package/skills/3d-assets/character-model/SKILL.md

@@ -222,4 +222,4 @@ After the rigged character is wired:
 - `summer:asset-pipeline/asset-strategy` — meta-router; this skill is the canonical drill-down of its "Image-to-3D for characters" path.
 - `summer:3d-assets/prop-model` — for non-character props.
 - `summer:scene-composition` — for the CharacterBody3D + Mesh + Collider parent pattern.
-- `_shared/mcp-tools-reference.md` — full parameter schemas for `summer_generate_3d`, `summer_generate_image`, and `summer_generate_motion`.
+- `references/mcp-tools-reference.md` — full parameter schemas for `summer_generate_3d`, `summer_generate_image`, and `summer_generate_motion`.

package/skills/3d-assets/organic-model/SKILL.md

@@ -189,4 +189,4 @@ After the organic models are scattered:
 - `summer:3d-assets/environment-kit` — pair with this skill: kit pieces give the architecture, organic gives the natural softness.
 - `summer:asset-pipeline/asset-strategy` — meta-router; ground textures and skyboxes go to Pipeline 2 / panoramic gen.
 - `summer:scene-composition` — MultiMeshInstance3D scatter pattern.
-- `_shared/mcp-tools-reference.md` — `summer_generate_3d` schema.
+- `references/mcp-tools-reference.md` — `summer_generate_3d` schema.

package/skills/3d-assets/prop-model/SKILL.md

@@ -130,4 +130,4 @@ After the prop is wired:
 - `summer:asset-pipeline/asset-strategy` — the meta-router that decides between this skill and Pipeline 2 (textures).
 - `summer:3d-assets/character-model` — for humanoids.
 - `summer:3d-assets/environment-kit` — for style-locked sets.
-- `_shared/mcp-tools-reference.md` — `summer_generate_3d` parameter schema.
+- `references/mcp-tools-reference.md` — `summer_generate_3d` parameter schema.

package/skills/3d-assets/vehicle-model/SKILL.md

@@ -199,4 +199,4 @@ After the vehicle is wired:
 - `summer:3d-assets/prop-model` — for separable parts (rotors, decals as decals, modular kit pieces).
 - `summer:asset-pipeline/asset-strategy` — meta-router.
 - `summer:character-controllers` — for player-driven vehicle input wiring.
-- `_shared/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.
+- `references/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.

package/skills/README.md

@@ -7,32 +7,45 @@ When an agent is asked to make a game in Summer Engine, this is what it reads to
 ## Layout
 
 ```
-skills/
-├── README.md                  # this file
-├── catalog.yaml               # canonical registry (name, category, status, template-id)
-├── _shared/                   # cross-skill references every skill can link
+summer-cli/
+├── .claude-plugin/plugin.json    # the registry (skills: array). Sibling Codex/Cursor manifests mirror it.
+├── references/                   # cross-skill shared docs (sibling of skills/)
 │   ├── godot-version.md
 │   ├── mcp-tools-reference.md
 │   ├── collaborative-protocol.md
 │   ├── template-registry.md
+│   ├── summer-folder.md
 │   └── gd-style.md
-├── _meta/
-│   ├── skill-test/            # static + behavioral linter
-│   ├── skill-create/          # bootstrap a new skill
-│   └── skill-improve/         # eval-harness iteration
-├── _tests/
-│   ├── runner.md              # how /skill-test works
-│   └── specs/                 # behavioral specs per skill
-└── <category>/<skill>/
-    ├── SKILL.md               # < 500 lines, frontmatter + body
-    ├── references/            # loaded on demand
-    ├── examples/              # working snippets
-    └── tests/spec.md          # behavioral spec
+├── tests/
+│   ├── runner.md                 # how /skill-test works
+│   └── specs/                    # behavioral specs per skill
+└── skills/
+    ├── README.md                 # this file
+    ├── workflow/                 # process skills (brainstorming, debugging, planning, etc.)
+    │   ├── using-summer/
+    │   ├── skill-create/
+    │   ├── skill-improve/
+    │   ├── skill-test/
+    │   ├── brainstorming/
+    │   ├── investigating-bugs/
+    │   ├── verification-before-completion/
+    │   ├── writing-plans/
+    │   ├── dispatching-parallel-agents/
+    │   ├── writing-skills/
+    │   ├── playtesting-a-feature/
+    │   ├── debugging-game-feel/
+    │   └── diagnosing-perf-regressions/
+    └── <category>/<skill>/       # gamedev domain skills
+        ├── SKILL.md              # < 500 lines, frontmatter + body
+        ├── reference.md          # optional, loaded on demand
+        └── examples/             # optional, working snippets
 ```
 
-## Categories (20)
+## Categories (21)
 
-`character-controllers`, `gameplay-mechanics`, `scripting-patterns`, `scene-and-project`, `rendering-and-lighting`, `shaders`, `visual-effects`, `post-processing`, `animation`, `audio`, `physics`, `multiplayer-and-networking`, `ai-and-npcs`, `level-design`, `performance`, `ui-and-ux`, `asset-pipeline`, `input-and-controls`, `debugging`, `deployment`.
+`workflow` (process discipline) plus 20 gamedev domains: `character-controllers`, `gameplay-mechanics`, `scripting-patterns`, `scene-and-project`, `rendering-and-lighting`, `shaders`, `visual-effects`, `post-processing`, `animation`, `audio`, `physics`, `multiplayer-and-networking`, `ai-and-npcs`, `level-design`, `performance`, `ui-and-ux`, `asset-pipeline`, `input-and-controls`, `debugging`, `deployment`.
+
+Folder structure is for humans only — Claude resolves skills as `summer:<skill-name>` regardless of category nesting.
 
 ## Standard
 
@@ -45,7 +58,7 @@ description: <when-to-use, key trigger phrases first>
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: <one of the 20>
-template-id: <optional, resolved against _shared/template-registry.md>
+template-id: <optional, resolved against references/template-registry.md>
 allowed-tools: Read Grep summer_add_node summer_set_prop ...
 paths: ["**/*.gd", "**/*.tscn"]
 ---
@@ -57,7 +70,7 @@ Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
 
 1. **SKILL.md ≤ 500 lines.** Push detail into `references/`. Progressive disclosure.
 2. **MCP-preferred + file-edit-fallback.** Every code-touching skill must show both paths so the skill works without Summer MCP installed.
-3. **Collaborative protocol.** "May I write…?" before any user-visible mutation. See `_shared/collaborative-protocol.md`.
+3. **Collaborative protocol.** "May I write…?" before any user-visible mutation. See `references/collaborative-protocol.md`.
 4. **Template cross-link.** When a working starter exists, link via `template-id` and the section "Want a working starter?".
 5. **Test spec.** Every non-`_meta` skill ships `tests/spec.md` with at least one Test Case.
 
@@ -67,7 +80,7 @@ Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
 /skill-create
 ```
 
-(See `_meta/skill-create/SKILL.md`.)
+(See `workflow/skill-create/SKILL.md`.)
 
 ## Testing
 
@@ -78,17 +91,11 @@ Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
 /skill-improve <name>        # parallel-eval harness for iteration
 ```
 
-(See `_meta/skill-test/SKILL.md` and `_tests/runner.md`.)
-
-## Roadmap
-
-Status legend in `catalog.yaml`:
+(See `workflow/skill-test/SKILL.md` and `tests/runner.md`.)
 
-- **HAVE** — ships today.
-- **NEXT** — next wave, in active development.
-- **LATER** — on roadmap.
+## What ships today
 
-Currently: **7 HAVE / ~50 NEXT / ~30 LATER ≈ 85 skills across 20 categories**. Subagents fill content category by category.
+The `skills:` array in `.claude-plugin/plugin.json` is the registry — what ships, ships there. New skills are added via `/skill-create` (see `workflow/skill-create/SKILL.md`).
 
 ## See also