@genex-ai/cli-demo 1.9.3-dev.519 → 1.10.0-dev.521

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.9.3-dev.519",
+  "version": "1.10.0-dev.521",
   "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/skills/genex-ai-image/SKILL.md

@@ -202,7 +202,12 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 ## Options
 
 - `--transparent` — PNG with an alpha channel (mandatory for decals/stickers/logos —
-  anything laid on top of a surface).
+  anything laid on top of a surface). Combines with `--quality` and `--size`, so a
+  hero wordmark can be asked for at `--quality high` and an exact canvas; without
+  `--quality` it runs a mid tier, which is the right default for a small sprite or
+  icon. Not with `--candidates` — this lane runs a background cutout after the
+  generation and that is billed per image, so generate candidates with
+  `--quality`/`--size`, pick one, then cut it with `--clean <url>`.
 - `--aspect <ratio>` — image shape (e.g. `square`, `16:9`, `9:16`); default is square.
 - `--quality <low|medium|high>` — quality preset; higher costs more and takes longer.
 - `--size <WxH>` — exact pixel size (multiples of 16, each side ≤ 3840, aspect ≤ 3:1).

package/templates/skills/genex-tool-audio/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: genex-tool-audio
+description: Generate game audio as mp3 files with `npx genex sfx` (sound effects — impacts, pickups, UI clicks, weapons, ambience), `npx genex music` (one looping instrumental track) and `npx genex voice` (a short spoken line from a cast of archetypes). Files download to ./assets and are yours to ship.
+---
+
+# Genex Tools · Audio
+
+Three lanes, one file format (mp3), one destination (`./assets`).
+
+## Sound effects
+
+```bash
+npx genex sfx "punchy laser zap"
+npx genex sfx "heavy wooden door creaking open" --duration 3
+```
+
+`--duration <sec>` targets a clip length; leave it off and the model decides.
+Generate each sound separately — one prompt, one sound.
+
+## Music
+
+```bash
+npx genex music "brooding orchestral battle loop, seamless, no intro or outro"
+npx genex music "sparse ambient synth pads" --duration 120
+```
+
+ONE looping instrumental track is the shape this lane is built for.
+`--duration` is 10–300 seconds, default 90. Say "seamless loop, no intro or
+outro" in the prompt — a track that opens with a flourish is unusable on repeat.
+
+Reuse the same track quieter for a menu rather than generating a second one, and
+give the player Music and SFX volume sliders: a loop with no volume control is
+the first thing a person turns off by closing the tab.
+
+## Voice
+
+```bash
+npx genex voice "You shall not pass!" --voice gruff
+npx genex voice "Systems nominal." --voice-id <raw-voice-id>
+```
+
+- `--voice <archetype>` — `narrator` (default), `heroine`, `gruff`, `elder`, `robot`, `imp`.
+- `--voice-id <id>` — any raw provider voice id, past the curated cast.
+
+Billed per submitted character and hard-capped at 1000, so split longer copy
+into separate lines. Voice lines are content: keep them short, subtitle them,
+and let the player skip.
+
+## Shared options
+
+`--out-dir <dir>` (default `./assets`) · `--no-download` (URL only) ·
+`--no-wait` (enqueue, pick up with `npx genex wait <id>`).
+
+## Cost
+
+Typical: **5 credits** an sfx · **40** a music track · **10** a voice line.
+Live prices and your balance: `npx genex doctor`.
+
+## Waiting
+
+`--no-wait` returns an id. `npx genex wait <id>` picks it up and never bills;
+**re-running a generate command bills a new asset.**
+
+## Troubleshooting
+
+- **Audio does not play on the first click** — nearly always the audio context, not the file: browsers require it to be created inside a real user gesture, and a sound fired before it exists is lost rather than queued. Create it on the first click or key press, then re-trigger whatever track was already selected.
+- **Out of credits** — the error prints balance, price and refill date. Relay it; don't retry.
+- **Anything else** — `npx genex doctor` reports whether the audio lanes are live on this account.

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

@@ -0,0 +1,94 @@
+---
+name: genex-tool-character
+description: Generate a rigged, animated 3D character or creature with `npx genex character` and `npx genex creature`, then give it any move in plain words with `npx genex character animate`. Covers the guided concept-to-final flow, the one-shot direct path, the 8-way locomotion set, and searching the ready-made animation library. Files download to ./assets.
+---
+
+# Genex Tools · Character
+
+A rigged humanoid body with animation clips bound to it — the player, an NPC, an
+enemy. The output is a GLB with a skeleton and named clips, loadable anywhere.
+
+For a prop, vehicle or building, use `$genex-tool-model`. For a non-humanoid
+body plan (quadruped, flier, serpent) use that skill's `model rig` lane — this
+one produces biped-shaped bodies.
+
+## The guided flow (three steps, one approval each)
+
+Use this when the character's LOOK matters and a person is choosing it:
+
+```bash
+npx genex character "stylized sci-fi courier, practical layered clothing"
+# → three concept candidates. SHOW them and wait for an explicit pick.
+
+npx genex character preview <concept-id> --candidate 2 --user-approved
+# → a 3D preview of that one, four views. Show it; wait for approval.
+
+npx genex character finalize <preview-id> --user-approved --approve-remesh 10000
+# → the rigged, game-ready character.
+```
+
+Each step needs the previous step's generation id. The approval flags are not
+ceremony: they record that a person actually looked and chose, and each step
+costs credits.
+
+## One shot
+
+When nobody is choosing — a background NPC, a quick test:
+
+```bash
+npx genex character "stylized sci-fi courier" --direct-text
+npx genex creature "hulking bone seraph, upright stance"
+```
+
+`creature` is the same lane with enemy defaults: no approval steps, no player
+controller pack. Biped-shaped bodies only.
+
+## Animating it
+
+Say what the character should DO, in plain words — one clip per verb:
+
+```bash
+npx genex character animate <character-id> "overhead slam" "parry and recover"
+npx genex character animate <character-id> --locomotion          # the 8-way walk + run set
+npx genex character animate <character-id> "victory pose" --video ./take-3.mp4
+npx genex character motions <character-id>                        # what is installed
+```
+
+- `--locomotion` — the full 8-direction walk and run set, 16 clips.
+- `--video <file>` — use your own footage as the reference.
+- `--duration 3-6` — a longer reference for a multi-beat move, so it lands instead of rushing. Bills per second.
+- `--action <id|query>` — pick a ready-made clip from the library instead of generating.
+
+`npx genex creature animate <id> "<verb>"` is the same lane for an enemy.
+
+Free and spend-free: the command prints its PLAN before anything is charged.
+Show that plan to the user when the cost matters.
+
+## The ready-made library
+
+```bash
+npx genex animations search "rifle reload" --limit 10
+```
+
+Free. Search by gameplay intent, then bind a result with `--action <id>`. Always
+look here first — a library clip costs nothing to generate.
+
+## Cost
+
+Typical: **15** concept · **20** preview · **30** finalize · **50** one-shot
+character · **26 per clip** for a generated move · **free** for a library
+search. Live prices and your balance: `npx genex doctor`.
+
+## Waiting
+
+Character stages take SEVERAL MINUTES server-side. Do not sit in a foreground
+wait: pass `--no-wait`, keep building, then `npx genex wait --all` for one
+status line each and `npx genex wait <id>` to pick one up. **Re-running a
+character command bills a NEW character.**
+
+## Troubleshooting
+
+- **A four-legged prompt came back upright** — the rig here is biped-shaped only. Generate the body with `npx genex model` and rig it with `npx genex model rig --type quadruped` (see `$genex-tool-model`), or ship it static and animate in code.
+- **Rigs rest facing +Z.** Set yaw explicitly when you place one, and never mirror a skinned mesh with a negative scale — it inverts the whole thing silently.
+- **Out of credits** — the error prints balance, price and refill date. Relay it; don't retry.
+- **Anything else** — `npx genex doctor`.

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

@@ -0,0 +1,60 @@
+---
+name: genex-tool-image
+description: Generate a real image (PNG/JPEG) from a text prompt with `npx genex image` — posters, signs, logos, sprites, icons, card and item art, loading screens, decals, art for in-game screens. Pass `--transparent` for an alpha channel, `--edit` to modify an existing image, `--remove-bg` to cut a background. The file downloads to ./assets and is yours.
+---
+
+# Genex Tools · Image
+
+Wherever the project needs a picture, this is the tool. Any style, any subject,
+any aspect. It is also the tool for editing an image you already have.
+
+## Run
+
+```bash
+npx genex image "hand-painted wooden tavern sign, weathered iron brackets"
+npx genex image "chalk graffiti tag" --transparent    # alpha channel — sprites, icons, logos
+```
+
+Blocks until ready, saves the file, and prints where it went:
+
+```
+✓ Done — 1 file saved to your project:
+  assets/hand-painted-wooden-tavern-sign-a1b2c3d4.png  (1.2 MB)
+  source of record (provenance, not hosting): https://assets.genex.technology/...
+```
+
+Wire the **local path**. The URL is provenance — never fetch it at runtime.
+
+## Options
+
+- `--transparent` — real alpha channel. Use for sprites, icons, logos, decals, anything that sits on top of the game rather than inside a frame. Combines with `--quality` and `--size`: a hero wordmark can ask for `--quality high` on an exact canvas, while a plain sprite is fine on the default mid tier. Not with `--candidates` — this lane cuts the background after generating and that is billed per image, so generate candidates with `--quality`/`--size`, pick one, then cut it with `--clean <url>`.
+- `--edit <path|url>` — modify THIS image with the prompt. Takes a local file (≤4 MB) or a previous generation's URL, so a reference screenshot goes straight into the chain.
+- `--inpaint <mask>` — with `--edit`, a PNG mask whose TRANSPARENT hole is the region to change. Targets where the edit lands; the whole image still re-renders and alpha is destroyed, so re-run `--remove-bg` afterwards if you need it.
+- `--remove-bg` — cut the background after generating or editing.
+- `--bg-mode <sprite|glyph|sheet|matte>` — which removal model. `matte` gives soft alpha for hair, glow and smoke edges.
+- `--clean <url>` — remove the background of an existing image, no generation.
+- `--upscale <url>` — 2× an existing image.
+- `--aspect <ratio>` · `--size <WxH>` · `--quality <low|medium|high>` — framing and fidelity.
+- `--candidates <2-4>` — several variants in ONE call, so you pick instead of re-rolling. Needs `--quality` or `--size`.
+- `--open` — also open it in a browser, for something the user must look at and approve.
+- `--out-dir <dir>` — where the file lands (default `./assets`).
+- `--no-download` — print the URL only, save nothing.
+- `--no-wait` — enqueue and return; pick it up later with `npx genex wait <id>`.
+
+## Cost
+
+Typical: **8 credits** per image (`--candidates` bills per variant). Live prices
+and your balance: `npx genex doctor`.
+
+## Waiting
+
+`--no-wait` returns a generation id immediately. Attach to it with
+`npx genex wait <id>` — that never bills. **Re-running the image command creates
+(and bills) a NEW image**, so never use it to "check on" one that is running.
+
+## Troubleshooting
+
+- **Out of credits** — the error prints your balance, the price, and when credits refill. Say that plainly to the user; don't retry.
+- **"Email not verified"** — the printed link unlocks the free credits; generation works right after.
+- **Anything else** — `npx genex doctor` reports sign-in, credits, and whether the image lane is live on this account.
+- A prompt that keeps producing the wrong thing is a prompt problem, not a lane problem — name the subject, the medium and the framing concretely ("vintage travel poster, screen-printed, three flat colours"), rather than adding adjectives.

package/templates/skills/genex-tool-model/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: genex-tool-model
+description: Generate a 3D model (GLB) from a text prompt or a reference image with `npx genex model` — props, vehicles, weapons, furniture, environment pieces, anything the scene needs as geometry. Also splits a model into named parts, rigs any mesh across 7 body plans, and retargets ready-made animation clips onto that rig. Files download to ./assets.
+---
+
+# Genex Tools · Model
+
+Props, vehicles, weapons, buildings, set dressing — anything the scene needs as
+real geometry. Output is a standard GLB that loads in any engine.
+
+For a character or creature with a skeleton and animations, use
+`$genex-tool-character` instead; this lane is for objects.
+
+## Run
+
+```bash
+npx genex model "weathered wooden barrel with rusted iron bands"
+npx genex model --image ./reference-photo.jpg       # build it FROM an image; prompt optional
+```
+
+Blocks until ready, saves the GLB into `./assets`, and prints the path. Wire the
+local path; the URL printed beside it is provenance, not hosting.
+
+## Mesh lanes
+
+Each takes the **generation id** of a previous model — never a URL.
+
+```bash
+npx genex model segment <model-id> --granularity balanced
+npx genex model rig <model-id> --type quadruped
+npx genex model animate <rig-id> --preset walk,run
+```
+
+- **`segment`** — one GLB whose parts carry NAMES, so you can address them: doors, turrets, magazines, destructibles. `--granularity simple|balanced|detailed`.
+- **`rig`** — a skeleton for any mesh, across 7 body plans: `biped`, `quadruped`, `hexapod`, `octopod`, `avian`, `serpentine`, `aquatic`. The plan is auto-detected; `--type` picks it. A mesh that cannot be rigged is refused and refunded before the paid step.
+- **`animate`** — retarget ready-made clips onto a rig, billed per clip. biped: `idle|walk|run|dive|climb|jump|slash|shoot|hurt|fall|turn`; quadruped/hexapod/octopod: `walk`; serpentine/aquatic: `march`.
+
+## Options
+
+- `--image <path|url>` — build the model from a reference image (local file ≤ 4 MB, or a previous generation's URL). The prompt becomes optional.
+- `--out-dir <dir>` — where the file lands (default `./assets`).
+- `--no-download` — print the URL only.
+- `--no-wait` — enqueue and return; pick it up with `npx genex wait <id>`.
+
+## Cost
+
+Typical: **25 credits** a model · **30** segment · **20** rig · **8 per clip**
+for animate. Live prices and your balance: `npx genex doctor`.
+
+## Waiting
+
+Models take the longest of any lane. `--no-wait` is the normal way to run
+several at once: enqueue them all, keep building, then `npx genex wait --all`
+for one status line each, and `npx genex wait <id>` to pick one up.
+**Re-running the model command bills a NEW model** — never use it as a status
+check.
+
+## Troubleshooting
+
+- **Out of credits** — the error prints the balance, the price and the refill date. Relay it; don't retry.
+- **The rig was refused** — that mesh has no usable skeleton for any body plan. It is refunded. Ship it static, or animate it in code.
+- **Repeated failures in this folder** — the CLI says so after the second one. That pattern is the lane, not your prompt: build the piece in code or move on, and tell the user in one plain line.
+- **Anything else** — `npx genex doctor`.

package/templates/skills/genex-tool-texture/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: genex-tool-texture
+description: Generate a tiling PBR texture set with `npx genex texture` — ground, floors, walls, rock, bark, metal, fabric, any repeating surface. Produces several maps (base colour, normal, roughness and friends) as separate files in ./assets, and `--terrain` makes the result seamless for large ground planes.
+---
+
+# Genex Tools · Texture
+
+A repeating SURFACE, as a set of PBR maps. Use this for anything a material
+covers: ground, floors, walls, cliffs, bark, hull plating, cloth.
+
+For a single flat picture — a poster, a sign, a sprite — use `$genex-tool-image`
+instead. That is one image; this is a tiling material.
+
+## Run
+
+```bash
+npx genex texture "mossy cracked cobblestone"
+npx genex texture "dry cracked riverbed clay" --terrain    # seamless, for ground planes
+```
+
+Saves EVERY map into `./assets` as its own file, one line each, labelled by role:
+
+```
+✓ Done — 3 files saved to your project:
+  assets/mossy-cracked-cobblestone-a1b2c3d4-basecolor.png  (2.1 MB)
+  assets/mossy-cracked-cobblestone-a1b2c3d4-normal.png     (1.8 MB)
+  assets/mossy-cracked-cobblestone-a1b2c3d4-roughness.png  (900 KB)
+```
+
+Load each map into the matching material slot and set the wrapping mode to
+repeat — the file names carry the role, so the mapping is unambiguous.
+
+## Options
+
+- `--terrain` — a seamless tiling surface, for ground and large planes. Use it whenever the texture repeats across something big.
+- `--out-dir <dir>` — where the files land (default `./assets`).
+- `--no-download` — print the URLs only.
+- `--no-wait` — enqueue and return; pick it up with `npx genex wait <id>`.
+
+## Cost
+
+Typical: **3 credits** for the whole set — the cheapest lane. Live prices and
+your balance: `npx genex doctor`.
+
+## Waiting
+
+`--no-wait` returns an id; `npx genex wait <id>` picks it up and never bills.
+**Re-running the texture command bills a NEW set.**
+
+## Troubleshooting
+
+- **The surface shows a visible repeating grid** — the CLI measures the seam automatically and warns when it is bad. Re-generate with `--terrain`, or scale the repeat down so the tile is smaller on screen. A repeating grid across a floor is the single most visible "asset flip" tell there is, so treat that warning as work.
+- **Out of credits** — the error prints balance, price and refill date. Relay it; don't retry.
+- **Anything else** — `npx genex doctor`.

package/templates/skills/genex-tool-video/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: genex-tool-video
+description: Generate a short video (mp4) from a text prompt with `npx genex video` — menu backdrops, cutscene beats, animated logos, in-game screens, seamless ambient loops like fog, embers, rain or flowing water. Can animate from a still frame you already have, and loop seamlessly. The file downloads to ./assets.
+---
+
+# Genex Tools · Video
+
+Short motion clips: a menu backdrop, a cutscene beat, an animated wordmark, an
+in-game screen, or an ambient loop (fog, embers, drifting dust, water).
+
+## Run
+
+```bash
+npx genex video "slow drifting fog over wet cobblestones, embers rising"
+npx genex video "candle flame flickering in the dark" --loop
+```
+
+Blocks until ready, saves the mp4 into `./assets`, and prints the path. Wire the
+local path — a shipped build must never fetch the URL at runtime.
+
+## Animating a still
+
+The strongest results come from conditioning on an image you already approved,
+so the video inherits art you have already agreed on rather than reinventing it:
+
+```bash
+npx genex image "misty citadel at dusk, cinematic wide shot" --aspect 16:9
+npx genex video "camera drifts slowly forward, banners stirring" --frame ./assets/misty-citadel-....png
+```
+
+- `--frame <path|url>` — animate FROM this frame back to itself, i.e. a seamless loop. Local file (≤ 4 MB) or a previous generation's URL.
+- `--first-frame <url>` / `--last-frame <url>` — a two-frame motion between them.
+
+## Options
+
+- `--duration <sec>` — target clip length.
+- `--loop` — a seamless loop.
+- `--resolution <720p|1080p>` — default 1080p. `720p` halves the cost, for clips where fidelity genuinely does not matter. Loop clips ignore it.
+- `--open` — also open it in a browser, for something the user must approve.
+- `--out-dir <dir>` — where the file lands (default `./assets`).
+- `--no-download` — print the URL only.
+- `--no-wait` — enqueue and return; pick it up with `npx genex wait <id>`.
+
+## Cost
+
+Typical: **20 credits** per video. Live prices and your balance:
+`npx genex doctor`.
+
+## Waiting
+
+Video is minutes, not seconds. Prefer `--no-wait` and pick the result up with
+`npx genex wait <id>` while you build something else. **Re-running the video
+command bills a NEW clip** — it is never a way to check on one already running.
+
+## Troubleshooting
+
+- **It failed** — video fails server-side more often than any other lane, and every attempt is minutes. The CLI counts failures in this folder and tells you when to stop: after the second, use a still image instead and say so in one plain line. A third attempt bills the same and returns the same.
+- **Out of credits** — the error prints balance, price and refill date. Relay it; don't retry.
+- **Anything else** — `npx genex doctor` reports sign-in, credits, and whether the video lane is live.

package/templates/skills/genex-tool-workflow/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: genex-tool-workflow
+description: How Genex Tools works across every lane — `npx genex doctor` to check sign-in, credits and which generation lanes are live; `npx genex wait` to pick up assets enqueued with `--no-wait`; where files land and how to wire them; what things cost and how credits work. Read this before running several generations, and whenever a command fails.
+---
+
+# Genex Tools · Workflow
+
+The rules that apply to every lane. The per-lane cards are
+`$genex-tool-model`, `$genex-tool-image`, `$genex-tool-video`,
+`$genex-tool-texture`, `$genex-tool-audio`, `$genex-tool-character`.
+
+## Check before you promise
+
+```bash
+npx genex doctor
+```
+
+Reports, in one screen: workspace, Node version, CLI version, who you are signed
+in as, credit balance and refill date, and **which generation lanes are actually
+live on this account**. Exit code 0 means all clear, 1 means something needs
+fixing.
+
+Run it when a command fails, and before telling the user what you can generate —
+it is the only live source for prices, balance and lane status. `--json` gives
+the same facts machine-readably.
+
+## Where files go
+
+Every finished generation downloads into `./assets` and the command prints the
+local path. **Wire that path.** The URL printed beside it is provenance — where
+the asset came from — not hosting: never fetch it at runtime, and never ship a
+build that depends on it. The files are the user's, to move, rename, commit or
+process further.
+
+`--out-dir <dir>` puts them somewhere else. `--no-download` prints the URL and
+saves nothing.
+
+## Running several at once
+
+This is the normal way to work, and the one rule that matters:
+
+```bash
+npx genex model "rusted fuel drum" --no-wait      # → prints a generation id
+npx genex image "faded hazard decal" --no-wait
+# …keep building…
+npx genex wait --all                              # one status line per generation
+npx genex wait <id>                               # pick one up (and download it)
+```
+
+- `--no-wait` enqueues and returns immediately with an id.
+- `npx genex wait <id>` attaches to that generation, waits, and saves the file. It **never** creates or bills anything, and is safe to re-run.
+- `npx genex wait --all` prints one line per generation from this folder — done, running, queued, failed. Never blocks, never bills.
+
+**Never re-run a generate command to check on one that is already running.**
+That starts, and bills, a second asset. `wait` is the only status check.
+
+Before you finish a piece of work, run `npx genex wait --all` and wire in
+everything that landed. A paid generation nobody wired in is the most common way
+credits get wasted.
+
+## Credits
+
+One balance across everything. Typical prices: texture 3 · sfx 5 · image 8 ·
+voice 10 · rig 20 · model 25 · music 40 · video 20 · character 50 · a generated
+animation clip 26. **Live prices: `npx genex doctor`** — they are set
+server-side and these are only typical.
+
+- A FAILED generation is refunded automatically. You never pay for something that did not arrive.
+- Out of credits is a plain refusal that prints your balance, the price, and the date credits refill. Relay those facts to the user and carry on with something else — do not retry.
+- A library animation search (`npx genex animations search`) costs nothing, and neither does `wait`, `doctor`, or the plan a character animate prints before charging.
+
+## Signing in
+
+```bash
+npx genex auth              # connect this machine
+npx genex auth --force      # switch accounts
+```
+
+It prints a short link and a code; the user approves on any device. If it ends
+"not approved yet", run `npx genex auth` again — it resumes the SAME code rather
+than minting a confusing second one. Nothing is lost by waiting.
+
+## Warnings are work
+
+Every warning line the CLI prints — a texture seam, a repeated lane failure, an
+unwired generation — is an actual defect it measured. Act on it or say out loud
+why you are not. Treating them as noise is how a game ships with a visibly
+tiling floor and three paid assets nobody loaded.
+
+## What is not here
+
+Hosting, publishing, multiplayer, remixing and custom domains are the Genex
+platform, not this toolkit — those commands are refused in this folder by
+design, and the refusal says where they live. This workspace generates assets
+for a game you build and ship yourself.