summer-engine 2.8.1 → 3.0.0

package/library/skills/driving-the-editor-ui/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: driving-the-editor-ui
+description: Use when a task is an editor-workflow step a human would do with the mouse — open Project Settings or a dock, switch the 2D/3D/Script main screen, toggle a panel, clear a dialog that is blocking the editor, read what a dock shows — and when deciding whether a request is UI work or scene work. Drives the editor by NAME through summer_ui_actions, reads it as structure through summer_ui_tree, activates the long tail by path through summer_ui_activate, and treats summer_ui_screenshot as the pixels-last fallback. Preview — the ops ship with a follow-up engine build.
+---
+
+# Driving the Editor UI
+
+## UI work vs scene work — decide first
+
+The editor UI is **not** where scene work happens. Nodes, properties, placement, lighting, materials: `scene-scripting` (`summer_run_script`), the scene tools, `summer_world_snapshot` / `summer_snapshot_diff` / `summer_screenshot` (`verifying-scenes`). The Scene dock and the Inspector are *views* of that data; clicking through them to change a property is slower, less reliable, and unverifiable compared with `summer_set_prop`.
+
+UI ops are for the steps a human does with the mouse that have no scene-level equivalent:
+
+| Ask | Route |
+|---|---|
+| "Open Project Settings" / "open the Import dock" / "toggle the Animation panel" | `summer_ui_actions mode:"invoke"` by name |
+| "Switch to the 3D view" / "go to the Script screen" | `summer_ui_activate path:"main_screen" action:"select_tab" value:"3D"` |
+| "Something is blocking the editor" / tool calls return `modal_open` | the blocking-dialog pattern below |
+| "What does the Inspector show right now?" | `summer_ui_tree root:"dock:inspector"` |
+| "Change the main scene setting" | `summer_project_setting` — a dedicated tool wins over any UI op |
+| "Move the player to (0, 1, 0)" | `summer_set_prop` / `summer_run_script` — scene work, never UI |
+
+## The ladder
+
+1. **Dedicated tool** (`summer_project_setting`, `summer_open_scene`, `summer_select_node`, `summer_save_scene`, …). If one exists, the UI ops are the wrong layer.
+2. **Named action** — `summer_ui_actions mode:"list" filter:"<word>"` to find the exact `name`, then `mode:"invoke" action_name:"<name>"`. The event takes the same path the shortcut key would, so the editor's own handlers run.
+3. **Tree + activate** — `summer_ui_tree` to find a control's `path`, `summer_ui_activate` to press / toggle / select a tab / set text / set a value through the control's own input path.
+4. **Pixels** — `summer_ui_screenshot`, only to look. There is no coordinate click anywhere in this surface: if a thing is visible it is in the tree, and the tree is what activation takes.
+
+Each rung costs more tokens and is less deterministic than the one above it. Do not start at 3 because it feels general.
+
+## The blocking-dialog pattern
+
+An exclusive dialog (Project Settings, a confirmation, an unsaved-changes prompt) makes the root window drop input; every mutating UI op then answers `modal_open` with the `blocking_dialog`, and other editor operations may stall as `still_queued`.
+
+1. `summer_ui_tree root:"dialogs"` → read `blocking`, `blocking_dialog {title, path, class}`, and the dialog's `text` and `buttons` (`kind: ok | cancel | custom`, `enabled`).
+2. Decide with the user in view. `button:"cancel"` is the safe close and the default; `"ok"` or a custom button text confirms whatever the dialog asks — only when that is what the user wants.
+3. `summer_ui_activate action:"dismiss_dialog" path:"<blocking_dialog.path>"` (or `title:"<title>"`).
+4. Read back: the result's `visible_after` must be `false`, and `summer_ui_tree root:"dialogs"` must show `blocking:false`. `visible_after:true` means the dialog re-validated and stayed up — read it again with `root:"dialog:<title>"` instead of retrying blindly.
+
+A dialog the human would have to click through, you also have to click through — nothing here bypasses one.
+
+## Main-screen switching
+
+`spatial_editor/*` actions need the 3D screen; `canvas_item_editor/*` need 2D; the script editor's actions need Script. A `not_handled` result (`invoked:true, handled:false`) usually means the wrong screen is up.
+
+```
+summer_ui_activate path:"main_screen" action:"select_tab" value:"3D"
+→ state.current_tab / state.text read back the selected editor
+```
+
+`value` is the editor name (`2D`, `3D`, `Script`, `Game`, `AssetLib`, case-insensitive) or `index`. `not_selected` means the switch was refused (scene change in progress, hidden editor button) — wait, retry, read back.
+
+## Reading a dock's state
+
+`summer_ui_tree root:"dock:<title|id>"` (`file_system`, `scene_tree`, `inspector`, or any dock title) returns the dock's controls with `text`, `tooltip` (icon-only buttons are named by it), `checked`, `enabled`, `tabs` + `current_tab`, `value/min/max`, `item_count/selected`. Go deeper on one subtree with `root:"path:<path>"` and a larger `depth`/`limit`; `children_truncated:true` plus the real `child_count` tells you where a cut happened.
+
+Paths and auto-names (`@Panel@123`) are stable within a session only. Re-read the tree before activating; never persist a path across sessions.
+
+## The deny-list
+
+The engine refuses, with `denied_action`, anything that ends or replaces the session or deletes without the human's confirmation: `editor/file_quit`, `editor/quit_to_project_list`, `editor/reload_current_project`, `scene_tree/delete_no_confirm`, every `project_manager/*` name — and buttons or menu items whose label quits, reloads the project, or closes the editor. `summer_ui_actions mode:"list"` marks them `denied:true`. Do not attempt them and do not route around them by path; tell the user what was asked and leave that click to them. File-dialog paths that leave the project (`..`, `user://`, `~`, absolute paths outside `res://`) are refused as `denied_path`.
+
+## Verification — read back, never assume
+
+- An invoke succeeded when its **effect** is observable: a dialog appears in `root:"dialogs"`, a dock's `summer_ui_tree` changes, or — for anything scene-level — `summer_snapshot_diff` / `summer_get_scene_tree` show it. `invoked:true` alone proves the event was dispatched, not that anything happened.
+- `summer_ui_activate` returns `state` **after** the action from the same node (`checked`, `current_tab`, `text`, `value`, `freed:true` if the action freed it). Cite it.
+- A screenshot proves appearance only. A control's exact state is in the tree.
+- `engine_lacks_op` means the build predates these ops: nothing was sent. Use the dedicated tools for the outcome, or ask the user to click, and say so.
+
+## Failure taxonomy — what to do
+
+| `failure_reason` | Means | Next |
+|---|---|---|
+| `unknown_action` (+`close_matches`) | no such name | pick one of the matches, or `mode:"list"` with a filter |
+| `denied_action` | safety list | stop; hand the click to the user |
+| `modal_open` (+`blocking_dialog`) | exclusive dialog eats input | blocking-dialog pattern |
+| `not_handled` | dispatched, no receiver | switch main screen / reveal the owning panel, retry |
+| `not_visible` / `disabled` / `obscured` | control exists but cannot take the event | reveal it, satisfy the precondition, or dismiss what covers it |
+| `unsupported_control` (+`supported_actions`) | class not driven this way | use the listed action, or a named action (MenuBar) |
+| `no_activation_path` | no hover and no focus reached the button | the named action instead |
+| `tab_not_found` / `button_not_found` / `ambiguous_dialog` | wrong or ambiguous name | use the listed `tabs` / `buttons` / `candidates` verbatim |
+| `no_renderer` | headless editor, no pixels | `summer_ui_tree`; pixels need a display |
+
+**Related skills:** `scene-scripting` and `verifying-scenes` own the scene loop this skill deliberately stays out of; `verification-before-completion` carries the done-claiming rules; `headless-scripting` is the route when there is no editor UI at all.

package/library/skills/driving-the-editor-ui/resource.yaml

@@ -0,0 +1,46 @@
+id: skill/driving-the-editor-ui
+kind: skill
+version: 1.0.0
+summary: "Drive the editor UI by name: invoke actions, clear blocking dialogs, switch the main screen, read a dock — and route scene work to the scene tools instead."
+use_when:
+  - an editor-workflow step a human would do with the mouse — open the Import dock, switch the 2D/3D/Script main screen, toggle a bottom panel, open an editor dialog by name
+  - a dialog or popup is blocking the editor and tool calls come back modal_open — see it (summer_ui_tree root dialogs) and clear it (summer_ui_activate action dismiss_dialog)
+  - reading what a dock or dialog currently shows as structure (summer_ui_tree) instead of guessing from a screenshot
+  - deciding whether a request is UI work (summer_ui_*) or scene work (summer_run_script, scene tools, perception tools)
+do_not_use_when:
+  - building or changing the scene — nodes, properties, placement, lighting go through scene-scripting and the scene tools; the editor's docks are views of that data
+  - verifying a visual result in the viewport or the running game — verifying-scenes (summer_screenshot, snapshot diff)
+  - quitting or reloading the editor, or deleting without confirmation — denied by the engine; ask the user
+  - "the engine build lacks the UI ops (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op — use the dedicated tools or ask the user to click"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - editor
+    - agent-workflow
+    - verification
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/ui-actions
+    - tool/ui-tree
+    - tool/ui-activate
+    - tool/ui-screenshot
+    - tool/screenshot
+    - tool/project-setting
+    - tool/open-scene
+    - tool/select-node
+    - tool/run-script
+    - tool/get-project-context
+  skills:
+    - skill/scene-scripting
+    - skill/verifying-scenes
+    - skill/verification-before-completion
+    - skill/headless-scripting
+source: official
+license: MIT
+status: preview
+recommended: false

package/{skills/3d-assets → library/skills}/environment-kit/SKILL.md

@@ -25,9 +25,9 @@ The backing tool is `summer_generate_3d`, called multiple times. Each call costs
 
 ## When NOT to use
 
-- A single hero prop (single chest, single throne) → `summer:3d-assets/prop-model`.
-- Open-world terrain (rolling hills, forests) → use a heightmap + scattered organic models from `summer:3d-assets/organic-model`.
-- Repeating flat surfaces only (just walls and floors, no decorative pieces) → `summer:asset-pipeline/asset-strategy` Pipeline 2 (textures + CSG) is cheaper and snaps perfectly to grid.
+- A single hero prop (single chest, single throne) → `prop-model`.
+- Open-world terrain (rolling hills, forests) → use a heightmap + scattered organic models from `organic-model`.
+- Repeating flat surfaces only (just walls and floors, no decorative pieces) → `asset-strategy` Pipeline 2 (textures + CSG) is cheaper and snaps perfectly to grid.
 - Characters or vehicles in the scene — those are separate skills.
 
 ## The style anchor pattern
@@ -144,8 +144,8 @@ Check the AABB. If the wall is 1.85m tall when you asked for 3m, scale it in the
 
 ## Edge cases
 
-- **Curved or organic kit (cave, alien hive).** Modular geometry resists snapping. Generate longer pieces (4m walls, transition tiles) and accept some overlap. Or switch to procedural — `summer:level-design` can scatter cave pieces with rotation jitter.
-- **Outdoor kit (cliffs, ruins, forest path).** Use the kit pattern but accept rotation/jitter at placement time. Mesh edges should fade naturally rather than snap cleanly. Pair with `summer:3d-assets/organic-model` for foliage scatter.
+- **Curved or organic kit (cave, alien hive).** Modular geometry resists snapping. Generate longer pieces (4m walls, transition tiles) and accept some overlap. Or switch to procedural — `design-level` can scatter cave pieces with rotation jitter.
+- **Outdoor kit (cliffs, ruins, forest path).** Use the kit pattern but accept rotation/jitter at placement time. Mesh edges should fade naturally rather than snap cleanly. Pair with `organic-model` for foliage scatter.
 - **Sci-fi kit (corridors, doors, terminals).** The style suffix becomes critical — `clean panels, soft cyan emissive trim, brushed metal, white background, isolated object`. Hard surfaces drift more than organic ones; review every piece.
 - **The user wants to add a piece later.** The locked suffix lives in the kit's notes (drop it in `assets/kits/dungeon/STYLE.md` if the user wants persistence). Reuse it verbatim for any addition — never re-derive.
 
@@ -164,12 +164,12 @@ After the kit is staged:
 
 > Dungeon kit ready: `res://assets/kits/dungeon/` with wall, floor, pillar, door, corner, arch on a 2m snap grid. Display scene at `res://assets/kits/dungeon/kit_dungeon.tscn`.
 >
-> Next: hand off to the level-design step — instantiate kit pieces into `level_01.tscn`, snap to the 2m grid, dress with props (`summer:3d-assets/prop-model`) and foliage (`summer:3d-assets/organic-model`). For lighting, see `summer:3d-lighting`.
+> Next: hand off to the level-design step — instantiate kit pieces into `level_01.tscn`, snap to the 2m grid, dress with props (`prop-model`) and foliage (`organic-model`). For lighting, see `3d-lighting`.
 
 ## See also
 
-- `summer:3d-assets/prop-model` — for the chests, statues, and decorative props that dress the kit.
-- `summer:3d-assets/organic-model` — for foliage and rocks that break up modular repetition.
-- `summer:asset-pipeline/asset-strategy` — Pipeline 2 (textures + CSG) is the cheaper alternative when pieces are flat.
-- `summer:scene-composition` — how to organize the kit scene and the level scenes that consume it.
-- `summer:3d-lighting` — interior kit pieces typically need warm point lights at sconce positions.
+- `prop-model` — for the chests, statues, and decorative props that dress the kit.
+- `organic-model` — for foliage and rocks that break up modular repetition.
+- `asset-strategy` — Pipeline 2 (textures + CSG) is the cheaper alternative when pieces are flat.
+- `scene-composition` — how to organize the kit scene and the level scenes that consume it.
+- `3d-lighting` — interior kit pieces typically need warm point lights at sconce positions.

package/library/skills/environment-kit/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/environment-kit
+kind: skill
+version: 1.0.3
+summary: Generate a modular environment kit — wall pieces, floor tiles, pillars, doors, arches, corners — snap-together meshes sharing one visual style.
+use_when:
+  - generating a modular environment kit of snap-together pieces that form a level — dungeon kit, modular walls, interior pieces
+  - building a dungeon, interior, or town kit from repeatable pieces that snap together in one style
+facets:
+  lifecycle:
+    - build
+  domains:
+    - 3d
+    - assets
+  modalities:
+    - 3d-models
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/organic-model
+    - skill/prop-model
+    - skill/asset-strategy
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/3d-assets/environment-kit

package/{skills/deployment → library/skills}/export-and-ship/SKILL.md

@@ -275,7 +275,7 @@ To enable another target, prove one of these before returning to step 2:
 
 On Apple Silicon, `binary_format/architecture="arm64"` is the natural guess, and it fails leaving a **0-byte `.app` that looks like success**. Only `"universal"` ships.
 
-See `summer:headless-scripting` for the wider pattern this is one instance of.
+See `headless-scripting` for the wider pattern this is one instance of.
 
 If the user is on a CI system (GitHub Actions etc), this is the right place to point them at a cross-compile workflow — Godot can export Windows + Linux from a Linux runner.
 
@@ -346,7 +346,7 @@ Use this as a one-shot grep before any export:
 
 ## Collaborative protocol
 
-This skill produces release artifacts. Always ask before each build is invoked. Group platforms — "I'm about to build Windows + Mac + Linux release configs into `build/`. OK?". See `../../../references/collaborative-protocol.md`.
+This skill produces release artifacts. Always ask before each build is invoked. Group platforms — "I'm about to build Windows + Mac + Linux release configs into `build/`. OK?". See `../../references/collaborative-protocol/collaborative-protocol.md`.
 
 ## Want a working starter?
 
@@ -354,10 +354,10 @@ No template — this is a workflow. Each project's export config and store asset
 
 ## See also
 
-- `../../../references/mcp-tools-reference.md` — full MCP tool list
-- `../../../references/godot-version.md` — Summer compatibility and
+- `../../references/mcp-tools-reference/mcp-tools-reference.md` — full MCP tool list
+- `../../references/godot-version/godot-version.md` — Summer compatibility and
   export-template versioning
-- `../../../references/collaborative-protocol.md` — "May I write" pattern
+- `../../references/collaborative-protocol/collaborative-protocol.md` — "May I write" pattern
 - `deployment/export-presets/SKILL.md` — preset config deep dive
 - `deployment/web-html5-export/SKILL.md` — HTML5-specific traps
 - `deployment/steam-uploader/SKILL.md` — `steamcmd` + GodotSteam (when shipped)

package/library/skills/export-and-ship/resource.yaml

@@ -0,0 +1,32 @@
+id: skill/export-and-ship
+kind: skill
+version: 1.0.3
+summary: "Assess and prepare a game export: inventory installed templates and targets, validate release assets and config, produce supported builds after approval."
+use_when:
+  - the user wants to assess or prepare a Summer game export — Steam, itch, HTML5, iOS, Android targets as available in the installed build
+  - the user says 'publish my game', 'release it', or 'ship a build to players' — produce the build they will upload
+do_not_use_when:
+  - publishing, uploading, hosting, or submitting a game — this skill only produces local builds
+facets:
+  lifecycle:
+    - launch
+  domains:
+    - deployment
+    - project
+  modalities:
+    - project
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/debug
+    - skill/tune-performance
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/deployment/export-and-ship
+lint_exceptions:
+  - url-allowlist
+lint_exception_reason: godotsteam.com is a read-only documentation link for the GodotSteam integration the export flow references.

package/library/skills/fabricating-assets/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: fabricating-assets
+description: Use when an asset needs Blender's mesh tooling rather than generation or a library download — a modular kit with exact dimensions and snapping, VFX meshes (shatter fragments, curve sweeps, LOD chains), or decimating/UV-unwrapping/baking a generated model — and you are about to write a bpy script for summer_fabricate_3d. Covers the route decision (fabricate vs generate vs import), the bpy rules that survive glTF export, the script -> import -> snapshot -> screenshot loop, every failure_reason and what to do about it, and the licensing shape (the user's own Blender, never bundled).
+---
+
+# Fabricating Assets
+
+## Overview
+
+`summer_fabricate_3d` runs a Blender Python (bpy) script you write in the **user's own installed Blender**, headless and supervised by the engine, validates the `.glb` the script's objects were exported to, moves it under `res://`, waits for the import, and (optionally) instantiates it into the open scene with `target_size` normalization. One call: script → glb → import → scene.
+
+It exists for a narrow slice of assets: the mesh-processing mid-tier that the engine does not have (exact booleans, bevels, UV unwrap, decimate, remesh, curve sweeps, fracture) and that generation and libraries serve badly. Everywhere else it is the wrong tool — route first.
+
+Three facts shape every use:
+
+1. **It is optional and detect-never-bundle.** Summer does not ship, download, or install Blender. If the machine has none, the result is a structured `blender_not_found` with the fix, and the decision to install belongs to the user.
+2. **It is blind until import.** There is no viewport while the script runs. Perception comes back only through the result (`objects`, `dimensions`, `warnings`, `skipped`) and then through the normal scene loop (`summer_snapshot_diff` + `summer_screenshot`).
+3. **One fabrication at a time per editor.** A second call while one is in flight fails with `busy`. Wait for the result; never fire in parallel.
+
+## Route first — fabricate, generate, or import?
+
+| Asset class | First route | Second | Why |
+|---|---|---|---|
+| Blockout / placeholder | `scene-scripting` primitives or CSG | fabricate | Must be instant and in-scene; no process spawn is justified |
+| Generic hard-surface prop ("a barrel") | `summer_search_assets` → `summer_import_asset` (`prop-model`) | `summer_generate_3d` | The free library plus `target_size` beats paid generation and a 2-minute wait, in a consistent style |
+| Bespoke prop ("the artifact from our GDD") | `summer_generate_3d` | fabricate | Image-to-3D is exactly what generation is for; fabricate when exact dimensions or parametric variants matter |
+| **Modular kit** (walls, pipes, fences, rails that snap) | **fabricate** | library kit (`environment-kit`) | Generation cannot hold dimensions and style across 30 pieces; array + boolean + bevel + one material is the classic kit workflow |
+| Characters (rigged, animated) | `summer_generate_3d` (`character-model`) | library | Scripted organic modelling is the documented failure mode; fabrication has no path to competitive organics blind |
+| Environments / terrain | in-engine terrain + library set dressing | generation for landmarks | Terrain wants interactive tools; dressing wants scatter |
+| Materials / textures / skies | library (`summer_import_hdri`, texture packs) | generation | Fabricate only to bake a procedural material to images |
+| **VFX meshes** (shatter pieces, trails, sweeps, LOD chains) | **fabricate** | in-engine | Bisect/fracture, curve sweeps, decimate are one-liners in bpy and absent in the engine |
+| **Post-processing a generated model** (decimate / UV / bake) | **fabricate** | — | The fix for generation's documented weaknesses; no other route exists |
+| UI | library + 2D image generation | — | 3D tooling is irrelevant |
+
+Fabricate wins in exactly three rows. If the request is not one of them, stop here and use `asset-strategy` to pick the specialist skill.
+
+## Prerequisite — the user's Blender
+
+The engine looks for Blender 4.2 LTS or newer in this order:
+
+1. `blender_path` passed in the call (only when the user named a path — never guess one);
+2. the `SUMMER_BLENDER_BIN` environment variable of the editor process;
+3. Editor Settings → FileSystem → Import → Blender → Blender Path (`filesystem/import/blender/blender_path`, the same setting `.blend` import uses);
+4. `PATH`, the platform's well-known install locations, and `~/.summer/tools/blender-<version>/`.
+
+When none resolves, the result is `failure_reason: blender_not_found` with `tried` (every path checked) and a prescriptive `error`. Relay it as a one-line decision: "Fabrication needs Blender (4.2 LTS or newer) on this machine. Install it from the official Blender download page, or point `SUMMER_BLENDER_BIN` at an existing executable and restart the editor. Or I can generate the asset or import one from the free library instead." Then do what the user chooses. Do not install software on their behalf, and do not retry the call hoping the answer changes.
+
+The `blender_version` in every successful result is a fact, not a suggestion: bpy APIs change across majors, and models skew toward older bpy from training data. When a `script_error` names a missing attribute or operator, check it against the version that actually ran.
+
+## The script contract
+
+`source` is plain bpy code. It runs in a factory-startup Blender (no user add-ons, no preferences, online access off) with an **empty** scene — no default cube, light, or camera — and these names already bound: `bpy`, `bmesh`, `mathutils`, `math`, `Vector`, `Matrix`, `Euler`.
+
+The script must **create mesh objects and leave them linked in the scene**. Nothing else. The engine's bootstrap then collects, audits, exports, and validates:
+
+- **Do not export, do not save, do not quit.** `bpy.ops.export_scene.gltf`, `bpy.ops.wm.save_mainfile`, `bpy.ops.wm.quit_blender` in your script break the contract and the run.
+- **What exports:** `MESH`, `CURVE`, `SURFACE`, `META`, `FONT` objects become meshes; `EMPTY` and `ARMATURE` keep hierarchy and skins; cameras, lights, probes and speakers are dropped.
+- **Hidden means helper.** An object hidden in the viewport or disabled for render is treated as a boolean cutter or guide: it is *not* exported and is listed in `skipped`. Use this deliberately for cutters; check `skipped` when a piece is missing.
+- **Modifiers are applied at export** (`export_apply`), including Geometry Nodes — the scene stays non-destructive, so do not `modifier_apply` by hand unless you need the result for a later step (a boolean whose output feeds a second boolean, for instance). Consequence: **shape keys are dropped** when modifiers exist; a `warning` says so.
+- **Only a Principled BSDF surface survives glTF.** Any other shader (Emission-only, Diffuse, custom node group) exports grey or black — a `warning` names the material. Build materials as Principled BSDF with constant values or Image Texture inputs.
+- **Procedural Base Color is baked for you** (Cycles, 2K cap, capped material count; meshes without UVs get a Smart UV Project first) and reported in `baked`. **Procedural Metallic / Roughness / Normal / Emission / Alpha are NOT baked** — set constants, or bake them to an Image Texture in your script; the `warnings` list tells you which channel was left procedural.
+- **Axis and units:** model in Blender's native Z-up, in metres; the export converts to the engine's +Y-up (`dimensions` in the result is already +Y-up). A 2 m wall segment is `dimensions.y ≈ 2`.
+- **Naming:** object names become node names in the imported scene. Name every object and material (`obj.name = "Wall_2m_A"`). The `name` argument names the `.glb` (`res://assets/fabricated/<name>.glb` unless `out_path` says otherwise) and the instantiated node; it is sanitized to `[A-Za-z0-9_-]`.
+- **Determinism:** seed anything random (`random.seed(7)`, noise textures with fixed seeds). A re-run must produce the same mesh so the loop below converges.
+- **No network.** Blender's online access is off; scripts that fetch anything fail. Reference images and existing models come from the project on disk (below).
+
+### Minimal template
+
+```python
+# Kit piece: 2 m wall segment with a door cutout, bevelled, one material.
+import bmesh
+
+def make_box(name, size, location):
+    bpy.ops.mesh.primitive_cube_add(size=1, location=location)
+    obj = bpy.context.active_object
+    obj.name = name
+    obj.scale = size
+    bpy.ops.object.transform_apply(scale=True)
+    return obj
+
+wall = make_box("Wall_2m_Door", (2.0, 0.2, 3.0), (0, 0, 1.5))
+
+cutter = make_box("DoorCutter", (1.0, 0.4, 2.1), (0, 0, 1.05))
+cutter.hide_set(True)          # hidden = helper: used by the boolean, never exported
+cutter.hide_render = True
+
+cut = wall.modifiers.new("Door", "BOOLEAN")
+cut.operation = "DIFFERENCE"
+cut.object = cutter
+cut.solver = "EXACT"
+
+bevel = wall.modifiers.new("Bevel", "BEVEL")
+bevel.width = 0.02
+bevel.segments = 2
+
+mat = bpy.data.materials.new("KitStone")
+mat.use_nodes = True
+bsdf = mat.node_tree.nodes["Principled BSDF"]
+bsdf.inputs["Base Color"].default_value = (0.55, 0.52, 0.48, 1.0)
+bsdf.inputs["Roughness"].default_value = 0.85
+wall.data.materials.append(mat)
+```
+
+Call it with `name: "wall_2m_door"`, `import_to_scene: {parent: "./Kit"}`, no `target_size` (the piece is already modelled at 2 × 0.2 × 3 m — a kit that snaps must keep its authored dimensions).
+
+## The loop
+
+1. `summer_get_project_context` — confirm the engine is up and which project is bound; read `projectPath` if the script needs a file from the project.
+2. `summer_world_snapshot` — the BEFORE baseline; keep `snapshot_id`.
+3. `summer_fabricate_3d` — `source`, `name`, `import_to_scene: {parent, position?}`, and `target_size` only when the asset is *not* dimension-authored (a hero prop whose size you are normalizing, not a kit piece). Default `max_seconds` 120 covers boot + script + bake + export for ordinary pieces; raise it (up to 600) for exact booleans on dense meshes or several bakes.
+4. **Read the result before looking at anything else.** `ok` and `ran`; `objects[]` (each with `vertices`, `faces`, `triangles`, `materials`, `modifiers`) against what you meant to build; `dimensions` in +Y-up metres against the spec; `skipped` for pieces that vanished because they were hidden; `warnings` for grey-material and unbaked-channel problems; `baked` for what the bootstrap did to your materials; `output` for your own `print()`s. A non-zero `exit_code` after a validated export is a warning, not a failure — the artifact is what was verified.
+5. `summer_snapshot_diff from_id:<the id>` — the structural receipt: exactly one new subtree under `parent` named `<name>`, nothing else changed.
+6. `summer_screenshot` — look at it. `target:"scene" framing:"camera"` when materials or lighting matter; a preset framing for silhouette and scale checks.
+7. Iterate on the script and re-run with the same `name` — the `.glb` is overwritten in place (`overwrote_existing: true`), and the previously instantiated node is still in the scene: remove it with `summer_remove_node` before re-importing to scene, or import without `import_to_scene` and let the existing instance pick up the new file.
+8. `summer_save_scene` once the piece is right. Instantiation is one undo action in the open scene, not a save — an unsaved instance is lost when the editor closes.
+
+Never claim a visual result without step 6. The full perception discipline is `verifying-scenes`.
+
+### Post-processing a generated model
+
+Generation delivers dense triangulated geometry with poor UVs. Fabrication is the fix:
+
+```python
+import os
+src = os.path.join(PROJECT_DIR, "assets", "generated", "goblin_statue.glb")   # PROJECT_DIR from summer_get_project_context.projectPath
+bpy.ops.import_scene.gltf(filepath=src)
+meshes = [o for o in bpy.context.scene.objects if o.type == "MESH"]
+for o in meshes:
+    bpy.context.view_layer.objects.active = o
+    o.select_set(True)
+    dec = o.modifiers.new("Decimate", "DECIMATE")
+    dec.ratio = 0.25
+    bpy.ops.object.mode_set(mode="EDIT")
+    bpy.ops.mesh.select_all(action="SELECT")
+    bpy.ops.uv.smart_project(angle_limit=math.radians(66), island_margin=0.02)
+    bpy.ops.object.mode_set(mode="OBJECT")
+```
+
+Substitute the real absolute project path for `PROJECT_DIR` (a string literal built from `summer_get_project_context` → `projectPath`); scripts have no `res://`. Write the result to a *new* `out_path` (`res://assets/generated/goblin_statue_lod1.glb`) so the original stays for comparison, and compare `objects[].triangles` before and after in the result.
+
+### Shatter fragments without add-ons
+
+Factory startup disables add-ons, so cell-fracture operators are not available. Cut with `bmesh.ops.bisect_plane` in a loop over random planes, `bmesh.ops.split_edges` / separate by loose parts, and name each fragment `Shard_00`, `Shard_01`, … — the imported scene then carries one `MeshInstance3D` per shard, ready for a `RigidBody3D` wrap in a `summer_run_script` pass.
+
+## Failure taxonomy — read `failure_reason`, then act
+
+| `failure_reason` | What happened | Do |
+|---|---|---|
+| `engine_lacks_op` | This engine build predates FabricateMesh (nothing was sent) | Route to `summer_generate_3d`, `summer_search_assets` / `summer_import_asset`, or `summer_run_script` blockout geometry; tell the user an engine update enables fabrication |
+| `blender_not_found` | No usable Blender executable (see `tried`) | Relay the one-line decision above; never guess a path or install anything |
+| `blender_launch_failed` | The executable exists but did not start (permissions, broken install, wrong architecture) | Show the `error` and `output` tail to the user; a different `blender_path` or a reinstall is their call |
+| `script_error` | Your bpy raised (`traceback_tail`, `script_line`, `blender_version`) | Fix the named line against the reported version; `script_line` maps to your `source` |
+| `timeout` | The child exceeded `max_seconds` (echoed) and was killed; nothing was imported | Raise the budget (≤ 600), or split — one piece per call, fewer bakes, coarser booleans |
+| `export_empty` | The script left no exportable object | Everything hidden? Not linked to a collection? Wrong type (a light, a camera)? Check `skipped` |
+| `export_failed` / `export_missing` | The exporter failed or wrote nothing | Read `errors` — usually a material or modifier the exporter cannot handle; simplify |
+| `bootstrap_error` | The engine's own bootstrap failed (not your script) | Report it verbatim as a bug; do not work around it |
+| `import_failed` | The `.glb` is at `out_path` but the editor did not import it | Read the importer's message with `summer_get_console`; often a zero-face mesh or an oversized texture. Fix and re-run, or `summer_instantiate_scene` the file after a manual rescan |
+| `instantiate_failed` | Imported fine; instantiation into the open scene failed (bad `parent`, no scene open) | The asset is in the project — open the right scene and `summer_instantiate_scene` it with `target_size` |
+| `busy` | Another fabrication is in flight | Wait for that result; never parallelize |
+| `cancelled` / `shutdown` | The run was cancelled or the editor closed | Re-run when the editor is back |
+| `rejected_identity` | The engine switched projects mid-run | `summer_get_project_context` to rebind, then decide whether to re-run |
+| `bad_args` | Malformed `out_path`, `target_size`, or empty `source` | Fix the argument; nothing was sent |
+
+Every failure leaves the project untouched except `import_failed` / `instantiate_failed`, which are honest about the `.glb` they did write. A `no_rewind_point: true` on any result means no SummerGit checkpoint exists for the run — say so before doing more destructive work.
+
+## Licensing and attribution
+
+- **Blender is the user's.** Summer runs the executable they installed as a separate process and talks to it only through arguments, files, and the exit code. Nothing in Summer links against Blender or imports bpy; the small export bootstrap the engine writes to a scratch directory is a separately licensed GPL file precisely because it does. Do not move project logic into bpy scripts expecting it to stay proprietary.
+- **Output is unencumbered.** Meshes made with Blender belong to the user; the `.glb` in their project carries no Blender licence obligation.
+- **Scripts you write here are created on the user's machine and never distributed by Summer.** If you adapt a bpy snippet from elsewhere, respect its licence — prefer your own code or CC0 sources, and record the origin in `.summer/memory/decisions/` when it matters for the project.
+- **Trademark.** "Blender" is a trademark of the Blender Foundation. Refer to it factually as the dependency ("requires Blender"); never describe the feature as powered by, built on, or branded with Blender, and never use its logo. Summer's name for this capability is *mesh fabrication*.
+- Imported library assets keep their own licences (`summer_search_assets` results carry `licenseType`); fabrication does not change that.
+
+## Red Flags — STOP
+
+| Red flag | Reality |
+|---|---|
+| Fabricating a barrel, a crate, a chair | Library first, generation second. Fabricate is for kits, VFX meshes, and post-processing |
+| Fabricating a character or creature | Scripted organic modelling is the documented failure mode; `summer_generate_3d` with rigging |
+| A script that calls `export_scene.gltf`, saves, or quits | Breaks the contract; the bootstrap exports |
+| A material that is not a Principled BSDF | Exports grey; the `warnings` list said so |
+| Procedural roughness or normal maps left unbaked | Not baked automatically — set constants or bake in the script |
+| `target_size` on a kit piece | Destroys the authored dimensions the kit snaps on |
+| Two fabrications in flight | `busy`; one at a time per editor |
+| Guessing a `blender_path` | Only the user knows where their Blender is; use the resolution order |
+| Installing Blender for the user | Never. Relay the decision |
+| Claiming the piece looks right without a screenshot | The fabricator is blind; only step 6 sees |
+| A hidden object that was supposed to export | Hidden means helper; unhide it or check `skipped` |
+| Retrying the same script after `timeout` | Raise the budget or split the job; the same oversized script times out again |
+
+**Related skills:**
+- `asset-strategy` — the route decision for every "I need a [thing]".
+- `environment-kit`, `prop-model`, `character-model` — the generation and library specialists fabrication defers to.
+- `scene-scripting` — in-scene geometry, placement loops, and wrapping fabricated pieces in bodies and collisions.
+- `verifying-scenes` and `verification-before-completion` — the evidence discipline after import.

package/library/skills/fabricating-assets/resource.yaml

@@ -0,0 +1,52 @@
+id: skill/fabricating-assets
+kind: skill
+version: 1.0.0
+summary: Fabricate meshes with a bpy script in the user's own Blender (summer_fabricate_3d) — kits with exact dimensions, VFX meshes, post-processing generated models.
+use_when:
+  - writing a Blender Python (bpy) script for summer_fabricate_3d and deciding whether fabrication, generation, or the free library is the right route for an asset
+  - a parametric hard-surface set with exact dimensions, booleans, bevels, and shared materials that must stay consistent across many pieces
+  - VFX meshes — shatter fragments, curve sweeps, trails, LOD chains — or decimating, UV-unwrapping, and baking a generated model before it goes into the scene
+  - a fabrication failed (blender_not_found, script_error, export_empty, import_failed, busy, timeout) and the result needs to be read correctly
+do_not_use_when:
+  - a generic prop — search the free library first (summer_search_assets, prop-model), then generate (summer_generate_3d)
+  - a character or any organic shape — character-model / organic-model; scripted organic modelling is the documented failure mode
+  - a blockout or placeholder — scene-scripting primitives/CSG are instant and in-scene
+  - "the engine build lacks FabricateMesh (Summer Engine 0.5.66 or newer); older engines return engine_lacks_op — route to summer_generate_3d / summer_search_assets / summer_run_script instead"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - 3d
+    - assets
+    - scripting
+    - agent-workflow
+  modalities:
+    - 3d-models
+    - scripts
+    - assets
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/fabricate-3d
+    - tool/generate-3d
+    - tool/search-assets
+    - tool/import-asset
+    - tool/instantiate-scene
+    - tool/get-project-context
+    - tool/world-snapshot
+    - tool/snapshot-diff
+    - tool/screenshot
+    - tool/get-console
+  skills:
+    - skill/asset-strategy
+    - skill/environment-kit
+    - skill/prop-model
+    - skill/character-model
+    - skill/scene-scripting
+    - skill/verifying-scenes
+    - skill/verification-before-completion
+source: official
+license: MIT
+status: preview
+recommended: false

package/{skills/animation → library/skills}/facial-and-lipsync/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
 user-invocable: false
-allowed-tools: Read Grep Edit Write summer_search_assets summer_inspect_resource summer_inspect_node summer_generate_audio summer_generate_motion summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_get_script_errors
+allowed-tools: Read Grep Edit Write summer_search_assets summer_inspect_resource summer_inspect_node summer_generate_audio summer_generate_motion summer_run_script summer_add_node summer_set_prop summer_set_resource_property summer_save_scene summer_get_script_errors
 paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 ---
 
@@ -31,7 +31,7 @@ The 2026 production stack:
 
 ## When NOT to use this skill
 
-- Character has no face / no BlendShapes (helmeted soldier, robot, mascot). Hard-skip to body language via `summer:animation/generate-motion`.
+- Character has no face / no BlendShapes (helmeted soldier, robot, mascot). Hard-skip to body language via `generate-motion`.
 - The dialogue is written but not yet voiced — generate audio first via `summer_generate_audio({capability: "text_to_speech", ...})`. Lipsync without audio has nothing to sync to.
 - Pre-rendered cinematic from external DCC. Lipsync is in the rendered video, not the engine.
 
@@ -169,7 +169,18 @@ This is a plain `Animation` resource authored in code — no editor required.
 reloads with every track and track type intact (verified on the shipped 4.6.1
 binary with value, blend-shape and method tracks in one resource). Any advice
 that says animation tracks or keyframes can only be authored in the editor GUI
-is wrong.
+is wrong. The bake function also runs unchanged inside a `summer_run_script`
+body against the live editor — often more convenient than the headless lane
+because the result lands in the open scene's library and the run is
+transactional.
+
+For QUICK facial keys that don't need a viseme timeline (a roar, a wince, an
+eyebrow raise), animation-tier engines collapse the whole bake into `ctx.animate` with
+a `"blend_shapes/<name>"` property path (value tracks, verified working) — one
+call per shape, same `anim_name` appends tracks to one clip. Recipe in
+`character-animation-wiring`. The Rhubarb bake loop above
+stays the right tool for full audio-synced viseme timelines — 15 tracks with
+per-cue keys is exactly what the loop is for.
 
 If you used the Whisper/ARPAbet cloud fallback instead of Rhubarb, swap `bake_from_rhubarb` for a variant that consumes `{ phoneme, start, duration }` triples and applies the ARPAbet → viseme table from the Reference card.
 
@@ -258,7 +269,7 @@ If the user has a CMUDict-style phoneme list and wants to map manually, this is
 ### Quality bar
 
 - ~12 phonemes/sec is normal English speech; the bake produces ~25 keyframes/sec across all tracks. Below 60fps playback on weak hardware: enable `BlendShape track interpolation = NEAREST` (loses smoothness, gains 30% perf). Reserve for mobile / very crowded crowd scenes.
-- Lipsync alone is ~70% of "alive". Add idle blink + idle micro-head-bob (`summer:animation/procedural-animation`) and you're at ~95%. The remaining 5% is brow articulation tied to dialogue sentiment, which is bespoke per scene.
+- Lipsync alone is ~70% of "alive". Add idle blink + idle micro-head-bob (`procedural-animation`) and you're at ~95%. The remaining 5% is brow articulation tied to dialogue sentiment, which is bespoke per scene.
 
 ## Anti-patterns
 
@@ -285,15 +296,16 @@ production speech recognition or photoreal lip sync.
 
 ## Handoff
 
-- For voice generation upstream, `summer:audio/generate-voice` (which wraps `summer_generate_audio({capability: "text_to_speech", ...})`).
-- For dialogue scripts and conversation flow, `summer:ai-and-npcs/design-npc`.
-- For the AnimationTree this layer composes into, `summer:animation/animation-tree`.
-- For idle blinks, saccades, and head-tracking that complement lipsync, `summer:animation/procedural-animation`.
+- For voice generation upstream, `voice-line` (which wraps `summer_generate_audio({capability: "text_to_speech", ...})`).
+- For dialogue scripts and conversation flow, `design-npc`.
+- For the AnimationTree this layer composes into, `animation-tree`.
+- For idle blinks, saccades, and head-tracking that complement lipsync, `procedural-animation`.
 - For full performance capture (face + body together), out of scope — see Meshy's mocap docs or external pipelines.
 
 ## See also
 
-- `summer:audio/generate-voice` — TTS upstream of this skill.
-- `summer:animation/animation-tree` — wire the lipsync OneShot into the character's tree.
-- `summer:animation/procedural-animation` — eye blinks, saccades, head idle.
+- `voice-line` — TTS upstream of this skill.
+- `character-animation-wiring` — the blend-shape `ctx.animate` mechanism, plus the body wiring this face layer sits on.
+- `animation-tree` — wire the lipsync OneShot into the character's tree.
+- `procedural-animation` — eye blinks, saccades, head idle.
 - Rhubarb Lip Sync — https://github.com/DanielSWolf/rhubarb-lip-sync (external tool; phoneme extraction).