summer-engine 2.8.2 → 3.1.0

package/library/skills/scene-scripting/resource.yaml

@@ -0,0 +1,58 @@
+id: skill/scene-scripting
+kind: skill
+version: 1.1.1
+summary: One GDScript in the live editor (summer_run_script) builds scenes, 2D levels, HUDs and gameplay wiring instead of CRUD chains; verify with diff + screenshot.
+use_when:
+  - a scene change needs 3+ related ops or any computed placement — scattering, grids, rings, procedural meshes, geometry helpers, terrain, lighting rigs, keyframe animation, shader FX
+  - a 2D level (tilemap paint, bodies, camera limits, parallax), an animated sprite, a HUD or Control tree, a persisted signal connection, an attached script, a prefab, input actions, an autoload, or the main scene should be built in one script
+  - an API property/method name must be verified with summer_api_docs before scripting
+  - a cold project-wide batch job belongs in summer_run_editor_script
+do_not_use_when:
+  - a single property tweak — summer_set_prop is cheaper
+  - one signal, one input binding, or one project setting — summer_connect_signal, summer_input_map_bind, summer_project_setting are one call each and ship today
+  - "the engine build lacks RunSceneScript (Summer Engine 0.5.66 or newer; older engines return engine_lacks_op) — RunEditorScript and RunVerification DO ship today, so fall back to summer_run_editor_script or the scene tools"
+  - "the 2D/UI/gameplay-code ctx helpers (Summer Engine 0.5.66 or newer) are missing on the engine — the skill's fallback table names what works everywhere"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - scripting
+    - 2d
+    - ui
+    - agent-workflow
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/run-script
+    - tool/run-editor-script
+    - tool/api-docs
+    - tool/world-snapshot
+    - tool/snapshot-diff
+    - tool/screenshot
+    - tool/connect-signal
+    - tool/input-map-bind
+    - tool/project-setting
+    - tool/write-file
+    - tool/get-script-errors
+  skills:
+    - skill/verifying-scenes
+    - skill/headless-scripting
+    - skill/scene-composition
+    - skill/character-animation-wiring
+    - skill/ui-basics
+    - skill/gdscript-patterns
+    - skill/sprite-sheet
+    - skill/verification-before-completion
+  templates:
+    - template/2d-platformer
+source: official
+license: MIT
+status: preview
+recommended: true
+aliases:
+  - skills/workflow/scene-scripting

package/{skills/level-design → library/skills}/scene-to-level/SKILL.md

@@ -26,33 +26,32 @@ Use it when the user shows you a screenshot or concept image and says "build thi
         │   └── route to TERRAIN + 2D ASSETS path
         ├─ 3D third-person / first-person
         │   └── route to 3D ASSETS path (out of scope for this skill —
-        │       use summer:3d-assets/ subskills directly)
+        │       use `asset-strategy` directly)
         └─ UI-only screen (menu, HUD)
             └── route to UI ASSETS path (just plan-asset-pack)
 
 2. For each visible element, route to the right sub-pipeline:
 
-   TERRAIN  → summer:2d-assets/tileable-texture
+   TERRAIN  → tileable-texture
               (auto-tiling Wang / 47-tile sheet; CURRENTLY a placeholder
               that generates a single tile — full auto-tile work is
-              tracked in publicsummerengine/Docs/assetCreation/
-              TERRAIN_AUTOTILE_IDEA.md and not yet built)
+              not yet built)
 
    PROPS / DECOR / LIGHTING / NATURE / WATER / BUILDINGS / UI / VFX
        ── If user has time for individual generation, prefer:
-       │   summer:2d-assets/create-asset-sheet (Plan + Generate Pack
+       │   create-asset-sheet (Plan + Generate Pack
        │   mode at /studio/plan-asset-pack — higher quality, each asset
        │   gets full model attention)
        └── If user wants fast / exploratory:
-           summer:2d-assets/create-asset-sheet (Slice from a sheet at
+           create-asset-sheet (Slice from a sheet at
            /studio/create-tileset — one sheet, autoslice, cheaper)
 
-   CHARACTERS → summer:2d-assets/character-portrait first for the static
-                frame, then summer:2d-assets/sprite-sheet for animation
+   CHARACTERS → character-portrait first for the static
+                frame, then sprite-sheet for animation
 
 3. Once assets exist, USE-WIDGET-ASSET on any UI / panel / bar /
    toggle pack files to wire them as NinePatchRect / TextureProgressBar
-   / etc. (see summer:2d-assets/use-widget-asset)
+   / etc. (see use-widget-asset)
 
 4. Compose the scene:
    - summer_create_scene(path=..., rootName=..., allow_temporary_scene_mutation=true).
@@ -81,10 +80,10 @@ Use it when the user shows you a screenshot or concept image and says "build thi
 
 ## When NOT to use
 
-- The user wants a **single asset** → `summer:2d-assets/pixel-art` or a leaf skill directly.
-- The user wants to **design** a level from scratch (gameplay beats, pacing, encounters) → `summer:level-design/design-level`. This skill is post-design — it implements a known visual target.
-- The user wants a **3D level** → use `summer:3d-assets/` subskills directly; the orchestration for 3D scenes isn't in this skill yet.
-- The user wants a **playable prototype with mechanics already** → mechanics aren't in scope. This skill produces the *visuals*; the mechanic skills (e.g. `summer:gameplay-mechanics/design-mechanic`) handle behavior.
+- The user wants a **single asset** → `pixel-art` or a leaf skill directly.
+- The user wants to **design** a level from scratch (gameplay beats, pacing, encounters) → `design-level`. This skill is post-design — it implements a known visual target.
+- The user wants a **3D level** → use `asset-strategy` directly; the orchestration for 3D scenes isn't in this skill yet.
+- The user wants a **playable prototype with mechanics already** → mechanics aren't in scope. This skill produces the *visuals*; the mechanic skills (e.g. `design-mechanic`) handle behavior.
 
 ## Required up-front
 
@@ -117,7 +116,7 @@ User shows you a screenshot of a Japanese village with multiple islands, water b
 3. **Plan the buildings pack**: 5 distinct buildings (small house, barn, shop, pagoda, watchtower).
 4. **Generate terrain**: today, single grass tile + single water tile + edge variant placeholders. Full Wang-tile auto-tiling is the TERRAIN_AUTOTILE_IDEA.md unbuilt path.
 5. **Plan the UI pack** via the planner with theme "isometric voxel game UI: bottom palette, toolbar with Place/Erase/Pan/Save/Reset, asset category tabs, instruction panel."
-6. **For each UI slice that's a panel / button**, use `summer:2d-assets/use-widget-asset` to wire as NinePatchRect.
+6. **For each UI slice that's a panel / button**, use `use-widget-asset` to wire as NinePatchRect.
 7. **Compose**: TileMap for terrain; Sprite2D placement matching the reference; Control nodes for the UI.
 8. **Validate + hand off**.
 
@@ -125,7 +124,7 @@ Total wall-clock: maybe 30 min for the asset packs (parallel), another 15 for sc
 
 ## What this skill explicitly defers
 
-- **3D scene assembly.** Out of scope; use `summer:3d-assets/` directly until a 3D variant of this orchestrator exists.
-- **Auto-tiling terrain.** The pipeline node exists in the decision tree but the leaf skill that implements it is not built — see `publicsummerengine/Docs/assetCreation/TERRAIN_AUTOTILE_IDEA.md`.
-- **Animation orchestration.** Per-character `summer:2d-assets/sprite-sheet` is invoked manually; no auto-pairing of characters with their animation pipelines yet.
+- **3D scene assembly.** Out of scope; use `asset-strategy` directly until a 3D variant of this orchestrator exists.
+- **Auto-tiling terrain.** The pipeline node exists in the decision tree but the leaf skill that implements it is not built.
+- **Animation orchestration.** Per-character `sprite-sheet` is invoked manually; no auto-pairing of characters with their animation pipelines yet.
 - **Gameplay code.** Player movement, interactions, win conditions — those are level-design + gameplay-mechanics skills, not this one.

package/library/skills/scene-to-level/resource.yaml

@@ -0,0 +1,33 @@
+id: skill/scene-to-level
+kind: skill
+version: 1.0.3
+summary: Go from a scene reference image or concept art to a playable scene — orchestrates concept, asset pack, terrain, composition, and scene assembly.
+use_when:
+  - going from a scene reference image or concept art to a playable Summer Engine scene populated with the right assets and terrain
+  - the user shares concept art or a reference screenshot and wants that location built as a playable scene
+facets:
+  lifecycle:
+    - build
+  domains:
+    - level-design
+    - game-design
+  modalities:
+    - scenes
+    - assets
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/character-portrait
+    - skill/create-asset-sheet
+    - skill/pixel-art
+    - skill/sprite-sheet
+    - skill/tileable-texture
+    - skill/use-widget-asset
+    - skill/design-mechanic
+    - skill/design-level
+source: official
+license: MIT
+status: stable
+aliases:
+  - skills/level-design/scene-to-level

package/library/skills/setup-multiplayer/resource.yaml

@@ -0,0 +1,28 @@
+id: skill/setup-multiplayer
+kind: skill
+version: 1.0.4
+summary: Add multiplayer to an existing game — LAN/online co-op, PvP, lobbies — via MultiplayerAPI, MultiplayerSpawner, and MultiplayerSynchronizer.
+use_when:
+  - "adding multiplayer to an existing Summer game: co-op LAN, co-op online, competitive PvP, or a lobby"
+  - a solo game needs LAN co-op, online co-op, versus play, or a lobby added
+facets:
+  lifecycle:
+    - build
+  domains:
+    - multiplayer
+    - scripting
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/peer-to-peer-multiplayer
+    - skill/host-authoritative-state
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/multiplayer-and-networking/setup-multiplayer

package/library/skills/skill-create/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: skill-create
+description: Use when a contributor wants to add a new skill to the Summer library. Bootstraps the canonical folder (library/skills/<slug>/ with resource.yaml and SKILL.md), frontmatter, and stub sections. Trigger on "create skill", "add skill", "new skill", "skill-create".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: workflow
+allowed-tools: Read Write Glob Grep Bash
+---
+
+# /skill-create: bootstrap a new library skill
+
+Works inside a checkout of the summer-engine agent repository (the one with `library/` and `registry/`). Outside it, capture the lesson with `gameskill` in the game project instead.
+
+## Steps
+
+### 1. Get the basics
+
+Ask the user:
+- **Slug** (kebab-case, 64 chars or fewer, flat: no category folders). Example: `state-machine-patterns`.
+- **Domain facets**: pick from the vocabulary in `registry/schemas/domains.json` (read it, do not guess). Example: `scripting`, `gameplay`.
+- **One-sentence summary** and a "Use when ..." description for the frontmatter.
+- **Template-id** (optional). Look it up in `library/templates/<id>/resource.yaml`.
+
+### 2. Create the folder
+
+May I create `library/skills/<slug>/` with this structure?
+
+```
+library/skills/<slug>/
+  resource.yaml      routing metadata (schema: registry/schemas/resource.schema.json + skill.schema.json)
+  SKILL.md           the skill body
+  references/        optional, populate as needed
+```
+
+### 3. Write resource.yaml (template)
+
+```yaml
+id: skill/<slug>
+kind: skill
+version: 1.0.0
+summary: <one sentence, what and when>
+use_when:
+  - <situation the router should match>
+  - <second situation>
+do_not_use_when:
+  - <situation that belongs to a neighbouring skill>
+facets:
+  lifecycle: [build]
+  domains: [<domain>]
+  modalities: [<scripts | scenes | assets | docs>]
+compatibility:
+  engine: ">=4.6"
+related:
+  skills: [skill/<neighbour>]
+source: official
+license: MIT
+status: preview
+recommended: false
+```
+
+`status: preview` until the skill has been exercised against a live engine; flip to `stable` in the same change as the evidence.
+
+### 4. Write SKILL.md (template)
+
+```markdown
+---
+name: <slug>
+description: Use when <situation>. Lead with the trigger phrases.
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: <domain>
+template-id: <optional>
+allowed-tools: Read Grep <summer_* tools this skill uses>
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# <Title> for Summer Engine
+
+<One paragraph: why this exists, who needs it.>
+
+## Steps
+
+### 1. <First step>
+
+**Preferred (Summer MCP):**
+
+\`\`\`
+summer_<tool>(...)
+\`\`\`
+
+**Fallback (no MCP, edit `<file>` directly):**
+
+\`\`\`
+<raw text/code>
+\`\`\`
+
+May I <action>?
+
+## Common mistakes
+
+- <mistake, with a one-line fix>
+
+## Want a working starter?
+
+`summer create <template-id> my-game` (see `summer list templates` for the slugs)
+
+## See also
+
+- `godot-version` and `gd-style` in `library/references/`
+- (related skills by bare slug)
+```
+
+Keep SKILL.md under 500 lines; push shared detail into `library/references/`. Cross-reference other skills by bare slug, never by path or `@` link.
+
+### 5. Generate and validate
+
+Nothing is registered by hand. Run:
+
+```bash
+npm run generate:registry
+npm run validate:library
+npm test
+```
+
+`generate:registry` rewrites `registry/generated/` and every plugin manifest from `library/`; `validate:library` checks the schema, facets, related links and capability lint; the test suite checks manifest parity. Commit the generated files with the skill.
+
+### 6. Run /skill-test
+
+Confirm the structural checks pass and, if the skill drives tools, that the routing eval still finds it (`npm run eval:routing`).
+
+## Collaborative protocol
+
+This skill writes files. Always ask before each write step.
+
+## See also
+
+- `collaborative-protocol` in `library/references/`
+- `skill-test`, `skill-improve`, `gameskill`

package/library/skills/skill-create/resource.yaml

@@ -0,0 +1,25 @@
+id: skill/skill-create
+kind: skill
+version: 1.0.3
+summary: Bootstrap a new Summer library skill (library/skills/<slug>/ with resource.yaml and SKILL.md), frontmatter, and stub sections.
+use_when:
+  - a contributor wants to add a new skill to the Summer library
+  - scaffolding a new library skill folder with canonical structure, frontmatter, and stub sections
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - meta
+  modalities:
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/skill-test
+source: official
+license: MIT
+status: stable
+aliases:
+  - skills/workflow/skill-create

package/{skills/workflow → library/skills}/skill-improve/SKILL.md

@@ -62,8 +62,8 @@ For each Case, score:
 Output:
 
 ```
-Case 1 (Happy):     baseline 4/6  proposed 6/6  ✓ ship proposed
-Case 2 (Failure):   baseline 3/4  proposed 4/4  ✓ ship proposed
+Case 1 (Happy):     baseline 4/6  proposed 6/6  yes ship proposed
+Case 2 (Failure):   baseline 3/4  proposed 4/4  yes ship proposed
 Case 3 (Edge):      baseline 3/3  proposed 3/3  = no change
 ```
 

package/library/skills/skill-improve/resource.yaml

@@ -0,0 +1,25 @@
+id: skill/skill-improve
+kind: skill
+version: 1.0.3
+summary: Upgrade an underperforming Summer skill — run it against a behavioral spec with and without changes via a parallel-eval harness; ship the winner.
+use_when:
+  - a contributor wants to upgrade a Summer skill that is underperforming or to fix a regression
+  - comparing a skill with and without a change against a behavioral spec before shipping the winner
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - meta
+  modalities:
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/skill-test
+source: official
+license: MIT
+status: stable
+aliases:
+  - skills/workflow/skill-improve

package/{skills/workflow → library/skills}/skill-test/SKILL.md

@@ -21,9 +21,9 @@ For a single skill at `skills/<category>/<name>/`, run these checks:
    - At least one `summer_*` MCP tool example.
    - At least one file-edit fallback block (e.g., raw `.tscn` snippet) OR an explicit "no fallback for this — Summer MCP required" note.
 4. **Collaborative protocol.** If the skill triggers user-visible writes, body must contain at least one of: `May I`, `I'm about to`, `Continue?`, `OK?`, `Proceed?`. Skills that only inspect/read are exempt.
-5. **Template-id resolved.** If the skill's frontmatter declares `template-id: <id>`, that id must exist in `../../../references/template-registry.md`.
+5. **Template-id resolved.** If the skill's frontmatter declares `template-id: <id>`, that id must exist in the template registry: `library/templates/<id>/resource.yaml` (see `library/templates/README.md`).
 6. **Tests/spec.md present.** Every skill in a non-`_meta` category must have `tests/spec.md` with at least one `## Case` heading.
-7. **Relative links resolve.** Every `](../references/...)`, `](../../references/...)`, `](./references/...)`, and `](./examples/...)` link must point at an existing file (FAIL if broken). Forward references in `## See also` to other SKILL.md files (e.g., `[design-mechanic](../../gameplay-mechanics/design-mechanic/SKILL.md)`) are allowed to dangle and only WARN if the target is missing — the catalog evolves and skills should be free to point at planned skills.
+7. **Relative links resolve.** Every `](../references/...)`, `](../../references/...)`, `](./references/...)`, and `](./examples/...)` link must point at an existing file (FAIL if broken). Forward references in `## See also` to other SKILL.md files (e.g., `[design-mechanic](../design-mechanic/SKILL.md)`) are allowed to dangle and only WARN if the target is missing — the catalog evolves and skills should be free to point at planned skills.
 
 Output:
 
@@ -80,7 +80,7 @@ This skill is **read-only**. It never writes. No "May I" needed.
 
 ## See also
 
-- `../../../references/collaborative-protocol.md`
-- `../../../references/template-registry.md`
+- `../../references/collaborative-protocol/collaborative-protocol.md`
+- the template registry: `library/templates/<id>/resource.yaml` (see `library/templates/README.md`)
 - `tests/runner.md`
 - `tests/specs/` — per-skill behavioral specs

package/library/skills/skill-test/resource.yaml

@@ -0,0 +1,26 @@
+id: skill/skill-test
+kind: skill
+version: 1.0.4
+summary: Lint a Summer skill before commit, audit the whole library, or check a behavioral spec assertion — static structural rules plus behavioral specs.
+use_when:
+  - a contributor wants to lint a Summer skill before commit, audit the whole library, or check a behavioral spec assertion
+  - running the structural lint and behavioral spec assertions for one skill or the whole library
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - meta
+  modalities:
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/skill-create
+    - skill/skill-improve
+source: official
+license: MIT
+status: stable
+aliases:
+  - skills/workflow/skill-test

package/library/skills/skintokens-auto-rigging/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: skintokens-auto-rigging
+description: "Use when auto-rigging a static GLB mesh offline with skin-tokens.cpp (LocalAI's C++/GGML port of VAST-AI SkinTokens/TokenRig) in SummerEngine's art pipeline: generate a skeleton and skin weights on CPU/Vulkan, then import the rigged GLB into Godot 4."
+license: MIT
+category: art-pipeline
+tags:
+  - rigging
+  - skinning
+  - assets
+  - glb
+  - ai-tooling
+  - godot4
+confidence: extracted
+---
+
+# Auto-Rigging Static Meshes with skin-tokens.cpp (SkinTokens/TokenRig) in SummerEngine
+
+## Tool review verdict
+
+Not a "slop tool made by a solodev": it is published under the **localai-org** GitHub organization by Richard Palethorpe (LocalAI maintainer), is an Apache-2.0 C++23/GGML port of VAST-AI's MIT-licensed **SkinTokens/TokenRig** research model (arXiv:2602.04805), ships a flat C11 API, an ASan/UBSan libFuzzer build, CPU/Vulkan numerical-parity test suites against the upstream reference, and a Go/WebGL demo. Weights are a verified, non-retrained GGUF conversion (~1.25 GB F16) on Hugging Face.
+
+Honest limitations to plan around:
+
+- The fully automatic `rig` command (unconstrained skeleton generation) is **explicitly experimental** — the policy can produce unsuitable bone topologies.
+- The author's own demo shows **open issues combining the output with kimodo.cpp skeletal animations**.
+- Generation recomputes the Qwen3 graph without a KV cache and **may take several minutes** per mesh; dense decoder queries are capped at 16K vertices per graph (chunked beyond that).
+- Results are strongest on shapes resembling the training distribution (humanoids; trained on ArticulationXL 2.0, VRoid Hub, ModelsResource).
+
+**Recommendation:** worth adopting as an *offline asset-prep* tool in the art pipeline, primarily the `skin` command (weights for an existing skeleton). Treat `rig`-generated skeletons as drafts that need artist review before animation use.
+
+## Outcome
+
+Static `.glb` meshes (e.g. AI-generated or scanned characters/creatures) become rigged, skinned `.glb` assets that Godot 4 imports natively as `Skeleton3D` + skinned `MeshInstance3D`, ready for `AnimationPlayer`/retargeted animation — without manual weight painting.
+
+## When to Use
+
+- You receive an unrigged character/creature mesh and need a fast first-pass rig or skin weights.
+- You have an existing armature (e.g. a mocap/Kimodo-style skeleton GLB) and only need learned skin weights for a mesh (`skin` command — the reliable path).
+- Batch-rigging many props/characters where hand-painting weights is not cost-effective.
+
+## When NOT to Use
+
+- Hero characters needing production-quality, art-directed deformation — plan for manual weight cleanup after auto-rigging.
+- Non-triangle meshes (tool accepts arbitrary triangle meshes only; triangulate first).
+- Shapes far from the training distribution (expect weaker results; run `--geometric` diagnostic to compare).
+- Runtime/in-engine rigging — this is an offline CLI/library step, not a Godot plugin.
+
+## Core Principle
+
+TokenRig models the whole rig — skeleton hierarchy followed by discrete skin-weight tokens (SkinTokens, an FSQ-CVAE vocabulary) — as one autoregressive sequence generated from a Michelangelo point-cloud encoding of the mesh (Qwen3-0.6B backbone, GRPO-refined). skin-tokens.cpp re-runs this stack through GGML on CPU or Vulkan and exports a standard skinned glTF/GLB with a one-frame rest pose, so it opens as a conventional rigged asset in any engine.
+
+## Pipeline shape (SummerEngine)
+
+```
+static character.glb
+      │
+      ▼
+[skin-tokens-cli]  rig | skin   (offline, CPU or Vulkan, minutes per mesh)
+      │
+      ▼
+character-rigged.glb   (skeleton + skin weights + rest pose, skinned glTF)
+      │
+      ▼
+Godot 4 import  →  character-rigged.glb (scene)
+      └── Skeleton3D
+            └── MeshInstance3D (skinned, Skin resource)
+      └── AnimationPlayer / retargeted animations
+```
+
+Keep raw static meshes and rigged outputs as separate files under the asset folder convention, e.g. `assets/chars/<name>/source.glb` and `assets/chars/<name>/rigged.glb`, so re-rigging never destroys source art.
+
+## Setup (once)
+
+1. Build the CLI (Linux; C++23 toolchain, CMake ≥ 3.25, Ninja, nlohmann-json, Vulkan unless disabled):
+   ```bash
+   git clone https://github.com/localai-org/skin-tokens.cpp
+   cd skin-tokens.cpp
+   git submodule update --init --recursive
+   cmake -S . -B build/release -G Ninja -DCMAKE_BUILD_TYPE=Release   # add -DSKINTOKENS_ENABLE_VULKAN=OFF if no Vulkan
+   cmake --build build/release -j
+   cmake --install build/release --prefix ./dist
+   ctest --test-dir build/release --output-on-failure
+   ./build/release/bin/skintokens-cli inspect models/SkinTokens-GGUF/F16   # sanity check after weights download
+   ```
+2. Download the F16 GGUF bundle (keep the 3 files together; runtime checks their embedded identities):
+   ```bash
+   hf download LocalAI-io/SkinTokens-GGUF --include "F16/*" --local-dir models/SkinTokens-GGUF
+   ```
+   (~1.25 GB: mesh-encoder 57.8 MB + tokenrig 948.6 MB + skin-vae 244 MB. Use F32 only for numerical-parity work.)
+
+## Implementation Steps
+
+### 1. Auto-rig a static mesh (draft skeleton + weights)
+
+```bash
+./build/release/bin/skintokens-cli rig models/SkinTokens-GGUF/F16 \
+  character.glb character-rigged.glb --device vulkan --postprocess
+```
+
+- `--postprocess` applies upstream's surface-locality heuristic (smoother, local influences); omit it only to preserve raw learned weights.
+- Output stores a one-frame rest pose; inspect the skeleton topology before animating (experimental mode — see Failure Modes).
+- Use `--geometric` as a non-learned baseline diagnostic when results look wrong.
+
+### 2. Re-weight against an existing skeleton (preferred when an armature exists)
+
+```bash
+# One rigged GLB supplies both geometry and skeleton (old weights ignored):
+./build/release/bin/skintokens-cli skin models/SkinTokens-GGUF/F16 \
+  character-rigged.glb character-rigged.glb character-reweighted.glb \
+  --device vulkan --fit none
+
+# Or separate mesh + animated skeleton GLBs (e.g. Kimodo animation output):
+./build/release/bin/skintokens-cli skin models/SkinTokens-GGUF/F16 \
+  character.glb motion.glb animated.glb --device vulkan --fit global
+```
+
+Fit modes:
+
+| `--fit` | When | Behavior |
+|---|---|---|
+| `global` (default) | Mesh and skeleton in different coordinates | One uniform scale + translation matching vertical extent and centre; preserves relative joint positions and bone-length ratios |
+| `none` | Both files already share coordinates | No alignment transform |
+| `articulated` | Recognized humanoid arm chains; **experimental** | Picks whichever of rest pose / first animation frame actually runs inside the arms (bind pose == frame zero → playback starts without warping); falls back to analytic two-bone IK toward conservative mesh targets, preserving arm segment lengths |
+
+### 3. Import into Godot 4
+
+Drop the rigged `.glb` into the project; Godot's glTF importer creates the scene automatically:
+
+- `Skeleton3D` with bones and a skinned `MeshInstance3D` (Skin resource), rest pose included.
+- Check in the Import dock: mesh, skeleton, and (if supplied) animations present.
+- If the source GLB contains animations and the hierarchy matches, Godot imports them into `AnimationPlayer`; otherwise use Godot 4's retargeting (`SkeletonProfileHumanoid`) to map animations onto the generated skeleton.
+- glTF round-trip note from upstream: on Blender export of results, a `glTF_not_exported` node may need removing (only relevant if the pipeline goes through Blender).
+
+### 4. Optional editor tooling (typed GDScript)
+
+An EditorScript/utility wrapper to rig assets from inside Godot:
+
+```gdscript
+@tool
+extends EditorScript
+
+const CLI := "/opt/skin-tokens.cpp/build/release/bin/skintokens-cli"
+const MODEL_DIR := "/opt/skin-tokens.cpp/models/SkinTokens-GGUF/F16"
+
+func _run() -> void:
+	var src := "res://assets/chars/goblin/source.glb"
+	var dst := "res://assets/chars/goblin/rigged.glb"
+	var args: PackedStringArray = [
+		"rig", MODEL_DIR,
+		ProjectSettings.globalize_path(src),
+		ProjectSettings.globalize_path(dst),
+		"--device", "vulkan", "--postprocess",
+	]
+	var output: Array = []
+	var err := OS.execute(CLI, args, output, true, false)
+	if err != 0:
+		push_error("skin-tokens-cli failed (%d): %s" % [err, "\n".join(output)))
+		return
+	print("Rigged: ", dst)
+	# Reimport so the new GLB appears in the FileSystem dock.
+	EditorInterface.get_resource_filesystem().scan()
+```
+
+For embedding in a tool/asset server, prefer the flat C11 API (`skintokens.h`): `st_model_load` → `st_rig_file` / `st_skin_files` / `st_inspect_glb_file`, with caller-owned error buffers; C++ exceptions never cross the ABI.
+
+## Tunables
+
+| Parameter | Meaning | Guidance |
+|---|---|---|
+| `--device` | `cpu` or `vulkan` | Vulkan if available; CPU works but slower. F16 for normal inference |
+| `--postprocess` | Surface-locality weight smoothing | On for game characters; off only to keep raw weights |
+| `--fit` | Skeleton↔mesh alignment (`global`, `none`, `articulated`) | `global` default for separate files; `none` when coordinates match; `articulated` experimental humanoid-arm fix |
+| `--geometric` | Non-learned diagnostic rigging | Compare against learned output when results look wrong |
+| F16 vs F32 bundle | Precision | F16 (~1.25 GB) normal; F32 parity work only |
+| Vertex budget | Dense decoder queries capped at 16K verts/graph, chunked beyond | Very dense meshes are handled in chunks; expect longer runs |
+
+## Failure Modes & Gotchas
+
+- **Unsuitable skeleton topology** from `rig` (experimental policy) — always have an artist inspect bones before animating; re-run or fall back to a template skeleton + `skin`.
+- **Animation combination issues**: the author reports unresolved problems combining skin-tokens.cpp rigs with kimodo.cpp skeletal animations (visible at the end of the demo video). Verify any animation transfer manually.
+- **Warped first frame** when the supplied skeleton's pose doesn't match the mesh: use `--fit global` (or `articulated` for humanoid arms) so bind pose aligns with the mesh; `--fit none` only when coordinates already match.
+- **Out-of-distribution shapes** degrade quality silently — no error is raised. Spot-check deformation visually.
+- **Runtime**: several minutes per mesh (no KV cache); do not put this in a per-frame or hot-reload path — batch offline.
+- **Bundle integrity**: the three GGUF files of a bundle must stay together; load fails identity checks otherwise.
+- **Vulkan precision**: slightly looser numerics than CPU (7.1e-4 hidden state / 1.4e-3 logits relative L2 vs 8.1e-6 CPU F32); visually equivalent but use F32+CPU for parity debugging.
+- **Upstream GPU path** (Python VAST-AI repo) needs an NVIDIA GPU ≥ 14 GB — use the C++ port instead for CPU/Vulkan machines.
+
+## Verification
+
+Not summerengine-verified. To validate in SummerEngine:
+
+1. `skintokens-cli inspect models/SkinTokens-GGUF/F16` succeeds after build + weights download.
+2. Rig a known test mesh (`rig … --postprocess`) and open the output in the Godot editor: `Skeleton3D` with sensible bone hierarchy + skinned `MeshInstance3D`, no import errors.
+3. Pose one bone in the editor; confirm the surface deforms smoothly without bleeding across disconnected parts.
+4. `skin` path: feed a mesh + animated skeleton GLB with `--fit global`; play the animation in Godot and confirm frame zero does not warp the mesh.
+5. Re-run ctest / parity binaries if the CLI is rebuilt or GGML is updated.
+
+## Confidence
+
+`extracted` — All tool behavior, commands, flags, sizes, numerics, and caveats come from the retrieved GitHub README, Hugging Face model card, upstream VAST-AI repo, and the author's X announcement (including the self-reported kimodo.cpp animation issue). The Godot 4 import mapping and GDScript wrapper are adaptations, not from the sources.