@genex-ai/cli-demo 0.90.0-dev.227 → 0.92.0-dev.229

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.90.0-dev.227",
+  "version": "0.92.0-dev.229",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/controllers/NOTICE.md

@@ -46,11 +46,13 @@ license (SPDX: `CC0-1.0`). No attribution is required by the license; this
 notice is provided as a courtesy — supporting Quaternius on Patreon is a nice
 way to say thanks.
 
-## Default avatar — CC0 1.0 Universal
+## Fallback avatar — CC0 1.0 Universal
 
-The character controller plays as your VRM avatar. When you have not chosen one
-(or run offline), the bundled default `assets/default-avatar.vrm` is copied to
-`public/assets/avatar.vrm`. It is **Wizzir** from the **100 Avatars** project by
+The player's body is the game's own generated character; a VRM avatar is the
+fallback lane. `genex controller character` copies the bundled default
+`assets/default-avatar.vrm` to `public/assets/avatar.vrm`, which covers local
+dev and load failures when that lane runs. It is **Wizzir** from the
+**100 Avatars** project by
 **Polygonal Mind** (polygonalmind.com), dedicated to the public domain under
 CC0 1.0 Universal (SPDX: `CC0-1.0`). Attribution is a courtesy, not required.
 

package/templates/controllers/character/player-character.ts

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: MIT
+// The player's body, resolved once: the game's OWN generated character when
+// this game has one, the visiting player's profile avatar when it does not.
+//
+// WHY THIS EXISTS: before it, the two lanes were different code — different
+// loader, different CharacterAnimations arguments, and a per-frame call that
+// appeared and disappeared. So the boot path written at hour 0 (the avatar,
+// the only lane that works before a character exists) had to be REWRITTEN at
+// hour 2 when the generated character landed, by an agent low on context with
+// ten things half-done. It wasn't, and games shipped wearing the platform's
+// stock avatar instead of the character they were designed around. ONE shape
+// for both lanes means the character arriving later is a file drop, not an
+// edit — `genex controller character --character <id>` writes the manifest and
+// the next reload picks it up.
+//
+// The generated character is the default for any game where a human body
+// appears on screen (first-person included — remotes, a look-down body, a
+// shadow, a menu portrait). The avatar is the FALLBACK: a declared temporary
+// body while the character renders, or the stand-in when generation genuinely
+// could not happen (out of credits, failed, unverified).
+import * as THREE from "three";
+import * as SkeletonUtils from "three/addons/utils/SkeletonUtils.js";
+import { VRMUtils } from "@pixiv/three-vrm";
+import type { LocomotionProfile } from "./character-animations.ts";
+import { loadCharacterClips } from "./animation-packs.ts";
+import {
+  loadMeshyCharacter,
+  type LoadMeshyCharacterOptions,
+  type MeshyCharacter,
+} from "./meshy/meshy-loader.ts";
+import { loadVrm, loadVrmCloneBase } from "./vrm/vrm-loader.ts";
+
+/** "generated" = this game's own themed character; "avatar" = the fallback. */
+export type PlayerCharacterKind = "generated" | "avatar";
+
+export interface PlayerCharacter {
+  kind: PlayerCharacterKind;
+  /** Renderable root — parent it under `character.root`. */
+  scene: THREE.Group;
+  /** Clips for CharacterAnimations (exact-rig generated clips, or retargeted UAL). */
+  clips: THREE.AnimationClip[];
+  /** Present only in the generated lane; pass straight through to CharacterAnimations. */
+  locomotionProfile?: LocomotionProfile;
+  /** Once per RENDER frame, after physics.step(). Ticks the VRM humanoid + spring
+   *  bones in the fallback lane; a no-op for native rigs. Always call it — that
+   *  is the point: the boot code never changes when the lane does. */
+  update(delta: number): void;
+  dispose(): void;
+}
+
+/** A REMOTE player's body: visual only, so no per-frame update and no physics. */
+export interface RemotePlayerCharacter {
+  kind: PlayerCharacterKind;
+  scene: THREE.Group;
+  clips: THREE.AnimationClip[];
+  locomotionProfile?: LocomotionProfile;
+  /** Detach on 'leave'. GPU resources belong to the shared base, never a clone. */
+  dispose(): void;
+}
+
+export interface LoadPlayerCharacterOptions {
+  /** The visiting player's VRM (`user.avatarUrl` from the embed identity). Fallback lane only. */
+  avatarUrl?: string | null;
+  /** Asset base. Default "./assets/". */
+  base?: string;
+  /** Manifest override. Default `${base}meshy-character.json`. */
+  manifestUrl?: string;
+  /** Passed through to the Meshy loader — the quality kit's decoder-wired loader
+   *  and per-tier model rung ladder (`$genex-threejs-adaptive-quality`). */
+  meshy?: LoadMeshyCharacterOptions;
+}
+
+/**
+ * Does this game have a generated character? A dev server answers HTTP 200 with
+ * `index.html` for ANY unknown path, so `res.ok` is not evidence — the JSON
+ * parse plus the manifest's own identity fields are. False is the quiet,
+ * expected answer for a game that has not generated its character yet.
+ *
+ * Exported for tests: this probe is the whole routing decision.
+ */
+export async function probeGeneratedCharacter(url: string): Promise<boolean> {
+  try {
+    const response = await fetch(url, { cache: "no-store" });
+    if (!response.ok) return false;
+    const manifest = (await response.json()) as { schema?: number; rig?: string } | null;
+    return manifest?.schema === 1 && manifest.rig === "meshy-biped";
+  } catch {
+    return false; // absent, or the dev server's index.html — same meaning here
+  }
+}
+
+// One PARSED base per manifest URL — the clone source for remote players, so N
+// remotes cost ~1 character of GPU memory instead of N (the same trade the VRM
+// lane's loadVrmCloneBase makes). Never animated; clones carry their own mixer.
+const generatedBaseCache = new Map<string, Promise<MeshyCharacter>>();
+// Retargeted fallback clips per (avatar URL + asset base) — retargeting is per
+// humanoid rig, and every clone of one URL shares one base rig.
+const fallbackClipsCache = new Map<string, Promise<THREE.AnimationClip[]>>();
+
+function generatedBase(url: string, options?: LoadMeshyCharacterOptions): Promise<MeshyCharacter> {
+  let cached = generatedBaseCache.get(url);
+  if (!cached) {
+    cached = loadMeshyCharacter(url, options);
+    cached.catch(() => generatedBaseCache.delete(url)); // failures retry next call
+    generatedBaseCache.set(url, cached);
+  }
+  return cached;
+}
+
+/**
+ * The LOCAL player's body. Wire it once at boot and never touch it again:
+ *
+ * ```ts
+ * const player = await loadPlayerCharacter({ avatarUrl: user.avatarUrl });
+ * const fit = capsuleFromModel(player.scene);
+ * character.root.add(player.scene);
+ * player.scene.position.y = fit.modelOffsetY;
+ * const anims = new CharacterAnimations(player.scene, player.clips, {
+ *   locomotionProfile: player.locomotionProfile,
+ * });
+ * // per render frame: anims.update(character, delta); player.update(delta);
+ * ```
+ */
+export async function loadPlayerCharacter(
+  options: LoadPlayerCharacterOptions = {},
+): Promise<PlayerCharacter> {
+  const base = options.base ?? "./assets/";
+  const manifestUrl = options.manifestUrl ?? `${base}meshy-character.json`;
+  const fallbackUrl = `${base}avatar.vrm`;
+
+  if (await probeGeneratedCharacter(manifestUrl)) {
+    try {
+      const native = await loadMeshyCharacter(manifestUrl, options.meshy);
+      return {
+        kind: "generated",
+        scene: native.scene,
+        clips: native.clips,
+        locomotionProfile: native.locomotionProfile,
+        update: (delta) => native.update(delta),
+        dispose: () => native.dispose(),
+      };
+    } catch (error) {
+      // LOUD: this game HAS a character and it failed — a dead R2 URL or a rig
+      // mismatch, not the ordinary "no character yet" path above.
+      console.warn(
+        "[player-character] the generated character failed to load — falling back to the avatar",
+        error,
+      );
+    }
+  }
+
+  const { scene, vrm } = await loadVrm(options.avatarUrl || fallbackUrl).catch(() =>
+    loadVrm(fallbackUrl),
+  );
+  const clips = await loadCharacterClips(vrm, { base });
+  return {
+    kind: "avatar",
+    scene,
+    clips,
+    update: (delta) => vrm.update(delta),
+    dispose: () => VRMUtils.deepDispose(scene),
+  };
+}
+
+/**
+ * A REMOTE player's body. In a game with a generated character EVERY player
+ * wears it — the game should look like the game that was designed, and a mixed
+ * roster (one themed knight plus three stock avatars) is the same incoherence
+ * as capsule-and-cone remotes. Without a generated character each remote keeps
+ * their own `avatarUrl`, which is the right look for a game with no themed cast.
+ *
+ * Visual only: no physics body, no controller, no per-frame update. Clones share
+ * the base's geometry/materials/textures, so `dispose()` detaches — it never
+ * disposes GPU resources the base and every other clone still use.
+ */
+export async function loadRemotePlayerCharacter(
+  options: LoadPlayerCharacterOptions = {},
+): Promise<RemotePlayerCharacter> {
+  const base = options.base ?? "./assets/";
+  const manifestUrl = options.manifestUrl ?? `${base}meshy-character.json`;
+  const fallbackUrl = `${base}avatar.vrm`;
+
+  if (await probeGeneratedCharacter(manifestUrl)) {
+    try {
+      const shared = await generatedBase(manifestUrl, options.meshy);
+      const scene = SkeletonUtils.clone(shared.scene) as THREE.Group;
+      return {
+        kind: "generated",
+        scene,
+        clips: shared.clips,
+        locomotionProfile: shared.locomotionProfile,
+        dispose: () => scene.removeFromParent(),
+      };
+    } catch (error) {
+      console.warn(
+        "[player-character] the generated character failed to load for a remote player — falling back to their avatar",
+        error,
+      );
+    }
+  }
+
+  const requested = options.avatarUrl || fallbackUrl;
+  const url = await loadVrmCloneBase(requested).then(
+    () => requested,
+    () => fallbackUrl,
+  );
+  const shared = await loadVrmCloneBase(url);
+  const clipsKey = `${url}${base}`;
+  let clips = fallbackClipsCache.get(clipsKey);
+  if (!clips) {
+    clips = loadCharacterClips(shared.vrm, { base });
+    clips.catch(() => fallbackClipsCache.delete(clipsKey));
+    fallbackClipsCache.set(clipsKey, clips);
+  }
+  const scene = SkeletonUtils.clone(shared.scene) as THREE.Group;
+  return { kind: "avatar", scene, clips: await clips, dispose: () => scene.removeFromParent() };
+}

package/templates/skills/genex-ai-character/SKILL.md

@@ -1,16 +1,39 @@
 ---
 name: genex-ai-character
-description: Generate a controller-ready Meshy humanoid with Genex, search the committed Meshy animation catalog by gameplay intent, add exact same-rig actions, and install the shared physics controller's Meshy-native adapter. Use for the game's themed character — the default whenever the protagonist is visible — or for motion not covered by the VRM + UAL lane.
+description: Generate a controller-ready Meshy humanoid with Genex, search the committed Meshy animation catalog by gameplay intent, add exact same-rig actions, and install the shared physics controller's Meshy-native adapter. Use for the game's own character — the player's body in every game where a human body appears on screen — and for motion the bundled UAL library doesn't cover.
 ---
 
 # Genex AI Character
 
-A themed Meshy character is the DEFAULT for any game whose protagonist is
-visible (third-person, or first-person with co-op/remote players); the
-VRM + UAL controller is the instant placeholder while it builds, and the
-final character only for games with no themed protagonist. Both lanes use
-the same ECCTRL-derived Rapier controller, camera, inputs, crossfades,
-transition rules, and multiplayer authority contract.
+**The game's own generated character IS the player's body.** Not the platform's
+profile avatar — that is the fallback. The rule applies wherever a human body
+appears on screen: third-person obviously, and first-person too, the moment
+co-op or versus remotes, a look-down body, a shadow, a death or spectator
+camera, or a menu portrait shows one. "The camera is in the head" is not an
+exemption; **"no human body ever appears in this game" is.** A game whose
+player is genuinely not a person — a car, a ship, an RTS cursor, a puzzle
+board — generates that object with `npx genex model` instead.
+
+**Start it EARLY** — enqueue the character right after the design interview,
+alongside the Stage-1 HUD concept, not as an afterthought once the world is
+built. Its concept candidates ride the same review beat as the HUD concept, and
+firing at minute 0 means it lands around the v0 preview instead of long after
+it.
+
+Until it lands, the player's body is the profile VRM avatar. That is a fallback
+in two shapes and both are spoken aloud: a **temporary** body while the
+character renders (say so in one plain line — the avatar is fully textured and
+animated, so nothing on screen will look unfinished enough to remind you), or
+the **stand-in** when generation genuinely could not happen (out of credits,
+failed, email unverified) — then record `Player character: VRM — <reason>` in
+DESIGN.md. Never let it become the game's character by default.
+
+Both lanes use the same ECCTRL-derived Rapier controller, camera, inputs,
+crossfades, transition rules, and multiplayer authority contract — and the
+same one-call boot path (`loadPlayerCharacter`, in
+`$genex-threejs-character-controller`), so when the character lands mid-build,
+`npx genex controller character --character <id>` is the whole switch. There is
+no code to rewrite, which is exactly why there is no excuse to skip it.
 
 **Two lanes, two approval shapes:**
 
@@ -146,44 +169,64 @@ Catalog entries are metadata-reviewed. Inspect the preview before choosing a
 specialty action. Only provider-declared `InPlace` loops or measured overrides
 may fill locomotion slots automatically.
 
-## Custom animations — `genex motion`
+## Custom animations — `genex character animate "<verb>"`
 
 Catalog search is ALWAYS the first stop — its stock actions cover most verbs
-with no GPU spend. When the catalog genuinely lacks the motion (a bespoke
-weapon-hold locomotion set, a signature move, a boss telegraph), `genex
-motion` generates it from text on the platform GPU service and compiles it
-locally into a rig-independent set:
+with no spend. When the catalog genuinely lacks the motion (a signature move, a
+boss telegraph, a full 8-way movement set), say what the character should DO in
+plain words and the platform generates it for this character's own rig:
 
 ```bash
-npx genex motion gen "soldier rifle low-ready idle, fully upright, head held high" --takes 4 --no-wait
-npx genex motion verify takes/            # objective gates — local, free, reproducible
-npx genex motion compile takes/rifle-idle.npz --out src/motion/rifle.json
-npx genex motion install --set rifle      # vendored runtime + the proven rifle starter set
+npx genex character animate <character-id> "overhead slam" "parry and recover" --no-wait
+npx genex character animate <character-id> --locomotion --no-wait
+npx genex character animate <character-id> "victory pose" --video ./take-3.mp4
 ```
 
-Billing is per take (default 4 per request); everything after `gen` is local.
-Unlike catalog clips (exact-rig only), compiled motion sets retarget onto
-Meshy/Mixamo GLB rigs and VRM avatars alike — the vendored `src/motion/rigs.js`
-carries both verified retarget formulas, and it is the game's file to tune.
-Read [references/motion.md](references/motion.md) BEFORE your first
-`motion gen`: it carries the prompt wording ladder, the take-naming contract
-that drives compilation, the rig limits (finger-less hands cannot curl around
-a grip), and the full wiring. Wording mistakes cost paid takes.
+One clip per verb. You never choose the method — the platform routes each verb
+(reuse a shared-library motion, generate movement, act it out on video first, or
+generate from a description) and prints the plan BEFORE anything is charged.
+
+**Show the plan to the user and let them change it before you continue.** That
+is the one stop in this lane; everything after it runs in the background while
+you keep building.
+
+Read [references/motion-generation.md](references/motion-generation.md) before
+the first run: it carries what makes a good verb, which verbs this cannot do,
+and the footage requirements for `--video`.
+
+`--locomotion` generates the full 8-way walk + run set (16 clips) — the
+directional slots the shipped controller resolves but the stock pack leaves
+empty, so a strafe stops being a faked forward walk. For an enemy that just
+follows a path, `--lean` keeps it to forward walk + run.
+
+Animate an enemy the same way — `genex creature animate <id> "<verb>"`. A
+creature is already a character underneath; the alias exists so you don't have
+to know that.
 
 ## Add actions and refresh the game
 
 ```bash
 npx genex character animate <character-id> --action <action-id>
 npx genex character animate <character-id> --action <first-id> --action <second-id> --no-wait
+npx genex character motions <character-id>     # what is installed right now
 npx genex controller character --character <character-id>
 ```
 
+`--action` picks an existing catalog clip; a free-text verb generates one. Both
+land in the same manifest and play through the same state machine.
+
 Ambiguous text queries print ranked candidates instead of silently spending
 credits. Already-installed actions return without another debit. After an
 animation job completes, rerun `genex controller character --character <id>`
 to refresh `public/assets/meshy-character.json`; existing controller source is
 preserved unless `--force` is explicitly used.
 
+Six slots belong to the reviewed controller pack and cannot be replaced —
+`idle.default`, `walk.forward`, `run.forward`, `crouch.forward`, `crouch.idle`,
+`jump.full`. A generated locomotion set fills the other fourteen directions; the
+plan says so before you spend anything. A character built without the pack
+(every `genex creature`) takes all sixteen.
+
 Meshy manifests bypass browser cache, so newly installed actions must work
 after preview without asking the player to disable cache.
 
@@ -231,4 +274,27 @@ durations, nominal speeds, trajectories, and gameplay requirements.
 For multiplayer, only the owning client advances the dynamic body and publishes
 its pose plus compact animation state. Remote characters are visual-only: they
 interpolate the owner's transform and replay the matching clip progress. Never
-run a motion driver or a second physics controller for a remote player.
+run a motion driver or a second physics controller for a remote player. In a
+game with a generated character, every remote wears it — one
+`loadRemotePlayerCharacter` call, one shared parsed base, N cheap clones.
+
+## Troubleshooting
+
+- **"Not authorized"** — run `npx genex init` first (in the project — it resolves this project's own CLI) (it writes your `GENEX_TOKEN`).
+- **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
+  this character stage. Tell the user the facts the CLI printed: their balance, this
+  stage's cost, and when their credits refill. Then keep the player on the profile
+  VRM avatar (the fallback lane — no code change, it is already what the game
+  loads), tell them in one plain line that the game is wearing the platform avatar
+  because the character couldn't be generated, record
+  `Player character: VRM — out of credits` in DESIGN.md, and mark the spot with
+  `// TODO(genex): regenerate when credits refill`. Do not stop the session over
+  this, and do not hand-build a stand-in humanoid.
+- **"Email not verified" (`email_verification_required`)** — generation credits
+  unlock after the account's email is verified. Give the user the verify link the
+  CLI printed, wait for them to confirm, then re-run the command.
+- **The character is stuck mid-lane** — each stage is a separate generation. `npx
+  genex wait --all` prints one line per job; a failed `preview` or `finalize` is
+  re-run from the id of the stage before it, never from the beginning.
+- **The rig or a pose is bad** — reject and regenerate. Never repair limbs at
+  runtime; validation never rewrites limb animation.

package/templates/skills/genex-ai-character/references/motion-generation.md

@@ -0,0 +1,125 @@
+# Generating character motion
+
+`npx genex character animate <character-id> "<verb>"` — one clip per verb, on
+this character's own rig. Read this before the first run; it is short, and the
+first two sections are where the credits go.
+
+```bash
+npx genex character animate <id> "overhead slam" --no-wait
+npx genex character animate <id> --locomotion --no-wait
+npx genex character animate <id> "leap the gap and roll on landing" --duration 6
+npx genex character animate <id> "victory pose" --video ./take-3.mp4
+npx genex character motions <id>
+npx genex creature animate <id> "wind-up ground pound" --no-wait
+```
+
+You do not choose how a verb is made. The platform prints a plan first — which
+verbs it will reuse, generate, or act out on video, and one total. **Show the
+plan to the user.** That is the single stop in this lane; after it, everything
+runs in the background while you keep building. Collect it later with
+`genex wait --all`.
+
+## Write the verb like a stage direction
+
+The generator turns your words into a body performance, so name the BODY, not
+the intent. "Overhead slam" is a motion; "attack" is a category.
+
+| instead of | write |
+| --- | --- |
+| `attack` | `heavy two-handed overhead slam, ending in a low crouch` |
+| `hurt` | `stagger back two steps from a chest impact, arms flailing` |
+| `win` | `plant both feet, raise one fist overhead, chest out` |
+| `die` | `drop to the knees, then fall forward onto the chest` |
+
+Three things make a verb generate well:
+
+- **Name the beats.** A wind-up, a committed main beat, a recovery. A motion with
+  one beat reads as a twitch.
+- **Say where the weight goes.** "Sinks into the knees as it lands" is the single
+  most useful phrase you can add — without it you tend to get a bow from the
+  waist where you wanted a crouch.
+- **Keep it one person, standing, on the floor.** No props that define the pose,
+  no partner, no furniture.
+
+## What this cannot do
+
+Do not spend on these — pick a different approach instead:
+
+- **Fingers and fine manipulation** — picking a lock, typing, a trigger squeeze,
+  threading a needle. Generated rigs have no finger bones, so the hand simply
+  will not do it. Fake it with a prop animation or a cut.
+- **Two characters interacting** — a handshake, a grapple, a carry. Only one body
+  is generated. Animate each side separately and time them in code.
+- **Anything a prop defines** — swinging on a rope, climbing a specific ladder,
+  sitting in a specific chair. The clip does not know your geometry; drive those
+  with `$genex-threejs-procedural-animation` instead.
+- **Non-bipeds** — quadrupeds, fliers, blobs. See `$genex-threejs-creatures`;
+  those stay static models plus procedural motion.
+
+## Room to land the beats: `--duration`
+
+Some verbs are made by generating a short reference video of a performer and
+converting THAT into motion — the plan says which ones ("acted out on video").
+The footage is a hard ceiling on the animation, and the default 3 seconds is a
+tight fit for anything with more than one beat: a performer given too little
+time rushes, and a rushed wind-up-slam-recover comes back as a bow.
+
+`--duration 3|4|5|6` gives those verbs more room. Use it when the verb you wrote
+genuinely has three beats — a leap with a landing roll, a stagger that recovers,
+a combo. Leave it alone for a single action; longer is not better, it is just
+longer, and it costs more.
+
+It only reaches verbs the platform routes to video, and the plan tells you
+whether it applied. It cannot change footage you supplied with `--video` —
+that clip already has a length.
+
+## Movement: `--locomotion`
+
+Generates the full 8-way walk + run set — 16 clips. This fills the directional
+slots the shipped controller already resolves (`walk.forward-left`,
+`run.back-right`, and so on) but that the stock pack leaves empty, so strafing
+stops being a forward walk played sideways.
+
+Six slots belong to the reviewed controller pack and cannot be replaced:
+`idle.default`, `walk.forward`, `run.forward`, `crouch.forward`, `crouch.idle`,
+`jump.full`. A generated set fills the other fourteen; the plan says which. A
+character built without the pack — every `genex creature` — takes all sixteen.
+
+For an enemy that follows a path, `--lean` generates forward walk + run only.
+Enemies have no controller state machine driving a direction picker, so the
+other six directions would never play. Ask for the full set when a boss
+genuinely circles the player.
+
+## Your own footage: `--video`
+
+`--video ./clip.mp4` converts a real performance instead of a generated one.
+The footage is a hard ceiling on the result — nothing can add weight the
+performer never committed — so it has to meet the extractor's requirements:
+
+- **Exactly one person**, alone in frame.
+- **Whole body visible**, head to feet, for the entire clip. A limb that leaves
+  the frame is a gap that cannot be recovered.
+- **Locked-off camera.** No pan, no zoom, no handheld drift, no cuts.
+- **Plain contrasting background**, and clothing in distinct solid colors — no
+  long coat, cape, or skirt over the legs.
+- **Even lighting.** Heavy shadows or a silhouette degrade the extraction.
+- **2–60 seconds.** `.mp4` or `.mov`.
+
+Phone recordings work. So do screen captures and gameplay clips.
+
+The video is checked against these rules before anything is converted, and a
+failure tells you which requirement broke and roughly when — re-shoot against
+that note rather than re-running the same file.
+
+## After the clips land
+
+```bash
+npx genex controller character --character <character-id>
+```
+
+Then play the game and watch the motion on the real character. Numbers and a
+completed job prove the clip installed; only your eyes prove it reads right.
+
+A clip that plays as a T-pose or does not play at all means it did not bind —
+check `genex character motions <id>` to see what is actually installed. Do not
+"fix" it with runtime bone corrections; regenerate it.

package/templates/skills/genex-ai-image/SKILL.md

@@ -213,7 +213,11 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
   still re-renders and alpha is destroyed either way: after any masked edit,
   re-run `--clean`/re-extraction downstream. A targeting scope, not a pixel
   freeze.
-- `--clean <url>` — ML background removal of THAT image only (prompt recorded, unused).
+- `--clean <url>` — ML background removal of THAT image only (prompt recorded,
+  unused). **For an image that HAS a background.** Running it over a
+  `--transparent` result re-keys edges that were already correct and can spray
+  colour speckle across the rim and into the art — `ui trim`/`extract`/`audit`
+  refuse that output, and nothing repairs it but going back to the original.
 - `--upscale <url>` — 2x utility upscale of THAT image (prompt recorded,
   unused; ~2-credit class). Use before printing/large billboards, not by
   default.

package/templates/skills/genex-ai-menu/SKILL.md

@@ -373,12 +373,20 @@ not):
 - **Logotype (default yes):**
   `npx genex image "the word 'EMBERFALL' as an ornate engraved game logo, <style brief>" --transparent`
   — the wordmark alone on a transparent background, in the brief's display
-  register, no extra text or scenery. Clean with `--bg-mode glyph` if letter
-  counters get eaten, trim with `npx genex ui trim`. Then VERIFY it is
-  actually transparent — view the trimmed PNG over a bright test background;
-  background removal sometimes leaves an opaque disc or plate behind the
-  mark, and that plate ships as a hole punched in your key art. If any
-  background remains, re-run the clean. Short names (one or two
+  register, no extra text or scenery. Then trim with `npx genex ui trim`.
+  **`--transparent` already returns a finished cutout — a `--clean` pass is a
+  REPAIR for a defect you can see, never routine polish.** Re-clean ONLY if
+  the letter counters came out filled: `--bg-mode glyph` for hard flat
+  shapes, `--bg-mode matte` for soft metallic, chromed, or glowing edges
+  (most ornate wordmarks are soft edges — `glyph` is the wrong cutter for
+  them). Then VERIFY over a bright test background, looking for BOTH
+  failures: **(1)** an opaque disc or plate behind the mark — that plate
+  ships as a hole punched in your key art; **(2)** coloured speckle or a
+  rainbow rim along the letter edges — that means the clean pass DAMAGED the
+  art, so go back to the `--transparent` original and ship that. Running a
+  background remover over an image that was already transparent re-keys every
+  edge it should have left alone; `ui trim`/`extract`/`audit` now refuse that
+  output outright, and nothing downstream repairs it. Short names (one or two
   words) come out best. Wire it as the menu title AND the loader mark; the
   DOM keeps an accessible text fallback (`aria-label` or visually-hidden
   text).

package/templates/skills/genex-ai-skybox/SKILL.md

@@ -23,12 +23,25 @@ towers, or any object painted into the sky render at infinite distance: they
 never get closer as the player moves, they sit at the wrong parallax against
 the real 3D world, and they read as broken the moment the camera strafes.
 Structures belong in the scene as geometry (`npx genex model`); the sky
-carries atmosphere — light, weather, clouds, haze, stars. The CLI enforces
-this: every skybox prompt gets an environment-only suffix appended (you'll
-see `↳ environment-only guard applied` and the full final prompt is stored
-with the generation). If you genuinely need content baked into the sky —
-e.g. a space station panorama for a scene with no world geometry — pass
-`--raw` to send your prompt exactly as written.
+carries atmosphere — light, weather, clouds, haze, stars.
+
+**Writing "no cathedral" does not rescue a prompt that also says "cathedral".**
+Image models are steered by the nouns they ARE given; a ban loses to any
+positive mention of the same thing in the same prompt. A real pilot asked for
+a *"cinematic dark anime gothic atmosphere, ruined cathedral courtyard mood,
+**no buildings or structures**"* — and got a full gothic cathedral with a
+courtyard balustrade and a baked ground plane. Five negations in that prompt,
+zero effect. So never name a structure in a skybox prompt **even to exclude
+it**: describe only light, colour, cloud, weather and time of day.
+
+The CLI enforces this both ways. It appends a closed-positive environment
+clause to every prompt (you'll see `↳ environment-only guard applied`; the
+full final prompt is stored with the generation), and it **refuses outright,
+before spending any credits**, when the prompt itself names a structure or
+object. Landforms are fine — "golden hour over misty mountains", "a distant
+sea horizon", "towering cumulonimbus" all pass. If you genuinely need content
+baked into the sky — e.g. a space station panorama for a scene with no world
+geometry — pass `--raw` to send your prompt exactly as written.
 
 ## Run