@genex-ai/cli-demo 1.31.2 → 1.32.0-dev.653

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

@@ -21,6 +21,17 @@ npx genex model --image ./reference-photo.jpg       # build it FROM an image; pr
 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.
 
+## Bring your own mesh
+
+```bash
+npx genex model import ./hero-cart.glb           # free — a file you already have becomes a model of yours
+```
+
+`.glb` only, ≤ 64 MB (export a `.gltf`/FBX as one binary `.glb` first). The
+import is free and checked before it completes; after it, `segment`, `rig`,
+`animate` and `character import` all take its id. **Never rebuild a mesh the
+user hands you** — import it.
+
 ## Mesh lanes
 
 Each takes the **generation id** of a previous model — never a URL.
@@ -31,29 +42,44 @@ 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`.
+- **`segment`** — one GLB split into addressable parts: doors, turrets, magazines, destructibles. `--granularity simple|balanced|detailed`. The parts are named by index (`tripo_part_0`, `tripo_part_1`, …), not by what they are — find the one you want by its bounds (the sails are the part with the widest extent, the door the lowest thin one), then keep that index in your manifest.
 - **`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.
+- **Quality knobs** (Tripo H3.1, each priced in the quote — pick per asset, say it in one line): `--texture standard|detailed|none` (detailed default, +10 over standard; none = geometry only), `--geometry detailed` (+20, hero pieces only), `--quad` (+5, for meshes you will edit; face limit ≤150000), `--low-poly` (+10, game-ready topology for props in numbers — it holds `--face-limit` to 1000-20000, 500-10000 with `--quad`; omit the flag to take 20000; it runs a post-process after the mesh, so allow up to 30 minutes), `--parts` (+20, named parts at generation), `--face-limit <n>` (1000-2000000, default 150000; see `--low-poly` for its band), `--auto-size` (real-world metres).
 - `--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`.
+From **35 credits** a model (**46** from a reference image; `--texture standard`
+**23**, `--geometry detailed` **58**, `--low-poly` **46**, `--parts` **58**) ·
+**46** segment · **29** rig · **12 per clip** for animate (1 credit = $0.01).
+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.
+for one status line each — in a tools workspace it also downloads every
+finished model that is not in `./assets` yet, so one call after a break (or a
+restarted session) delivers the whole batch. `npx genex wait <id>` picks one
+up. **Re-running the model command bills a NEW model** — never use it as a
+status check. Five or so in flight at a time is the provider's comfortable
+concurrency; a burst beyond that waits on the server side rather than failing.
+
+## Placing a model
+
+A generated GLB has no shared "front": one building's door faces −x, the next
+one's +z. Do not guess and do not spend a render per side — read the mesh once
+on load (bounding box, and where the detail is: the door, the counter, the
+opening) or check it in a viewer, then record a per-model `front` (a yaw in
+your manifest) beside its path and apply it when you place it. Ask for a facing
+in the prompt too (`"…front toward +Z"`) — it helps, it does not guarantee.
 
 ## Troubleshooting
 

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

@@ -0,0 +1,100 @@
+---
+name: genex-tool-publish
+description: Put the game in this folder on the web with Genex — the draft page, `npx genex preview`, then `promote` / `publish`; the link you hand the user, the size limits, and what to do with the preflight lines. Installed once the folder is connected to a hosted Genex game (`npx genex init --convert`). Load it before the first preview.
+---
+
+# Genex Tools · Publish
+
+The user built this game themselves and asked for it online. Your job is to
+put it there **as it is** — the code, the structure and the assets stay
+exactly what they are. Publishing adds glue and nothing else; it never starts
+a rework, a design document or a build plan.
+
+## The glue (all of it)
+
+1. **A static build.** The game must build to files with its own build
+   command — `npm run build` into `dist/`, or an `index.html` at the root
+   with no build step. Asset paths must work from the game's own hosted URL,
+   so prefer relative ones (Vite: `base: './'`). Files the game loads at
+   runtime — everything in `./assets` — must end up inside the build (Vite:
+   a `public/` folder, or copy `assets/` into `dist/` in the build).
+2. **Player identity.** Load `$genex-threejs-embed-auth` and add the one
+   `initEmbed(...)` call at the very top of the boot code. Create the
+   renderer and draw a frame BEFORE any `await waitForPlayer()` — on a hosted
+   page identity takes seconds, and a game that awaits it first ships black.
+3. **The CLI as a dev dependency** so plain `npx genex` keeps resolving here
+   (setup already did this; check `package.json` if in doubt).
+
+Commit the glue as its own small commit when the folder is a git repo, so the
+line between the user's game and what publishing added stays visible.
+
+## Preview
+
+```bash
+npx genex preview
+```
+
+Builds, uploads and puts the build on the game's **draft page** — unlisted,
+only the user can open it. When it reports live, open the hosted build once
+yourself and confirm it loads with no missing files (the dev server forgives
+paths the hosted build will not), then hand over the link.
+
+**The link is always the game's page on Genex, never the raw play address,
+never localhost, never a file path:**
+
+- draft: `<dashboard>/draft/<slug>`
+- public, once published: `<dashboard>/world/<slug>`
+
+`<dashboard>` is the first `dashboardOrigins` entry in `.genex/project.json`
+and `<slug>` is the `slug` there. `preview` prints the exact page link as
+"your game's page" — use that line verbatim.
+
+## The preflight is a report, not a to-do list
+
+`preview` prints warning lines before it uploads — an estimated phone GPU
+budget, a music track with no volume slider, a paid asset nobody wired, a
+viewport meta line. None of them blocks the deploy, and none of them was
+asked for. So: **ship first**, hand over the link, then relay each line to
+the user in one plain sentence with an offer ("phones will struggle with the
+textures — want me to shrink them?"). Fix one only on the user's yes. Never
+turn the report into a milestone before the link.
+
+## Draft and public version
+
+`preview` updates the **draft** and never touches what players are on. The
+first release lists the game:
+
+```bash
+npx genex publish --categories games
+```
+
+Pick 1–3 categories that fit (`games`, `assets`, `physics`, `terrain`,
+`lighting`, `vfx`); `games` when unsure. Ask before the first publish — "This
+is a private draft only you can open. Say the word and I'll publish it for
+anyone to play." — and celebrate the public page link when it lands.
+
+After that first release the game is two versions, and the user only ever
+hears these two words for them: the **draft** (updated by `preview`) and the
+**public version** (what everyone plays). "Publish it", "update it" and "yes"
+after the first release ALL mean:
+
+```bash
+npx genex promote      # the exact draft build goes public — no rebuild
+```
+
+Never run `publish` a second time (it would ship an untried rebuild). If
+anything changed since the last `preview`, preview again before promoting.
+Ask once per round of work, in one line, and keep working while you wait.
+
+## Limits and refusals
+
+- **Upload size**: ~95 MB per file, ~500 MB in total. Over that, tell the user
+  plainly which part is too large (usually a video, model or audio file) and by
+  roughly how much; ask before compressing or removing anything.
+- **Terms refusal**: the CLI prints a link, waits for the user's click and
+  re-sends by itself — hand the link over and let it finish.
+- **`preview` says the folder is behind another machine** (`stale_source`):
+  `npx genex pull` takes the newer draft, then redo the change — never
+  `--force` over somebody else's work.
+- **Out of credits or a lane down**: `npx genex doctor` says which; publishing
+  itself costs nothing.

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

@@ -39,7 +39,7 @@ repeat — the file names carry the role, so the mapping is unambiguous.
 
 ## Cost
 
-Typical: **3 credits** for the whole set — the cheapest lane. Live prices and
+From **5 credits** for the whole set (1 credit = $0.01). Live prices and
 your balance: `npx genex doctor`.
 
 ## Waiting

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

@@ -18,6 +18,10 @@ 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.
 
+Every clip carries a **native stereo audio track** (score, foley, ambience).
+Browsers only autoplay muted video, so keep the `<video>` element muted unless
+the sound is the point — and route it through your game's volume control.
+
 ## Animating a still
 
 The strongest results come from conditioning on an image you already approved,
@@ -29,13 +33,30 @@ npx genex video "camera drifts slowly forward, banners stirring" --frame ./asset
 ```
 
 - `--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.
+- `--start-frame <path|url>` — continue from this frame, no end anchor — the clip-chaining primitive.
+- `--first-frame <path|url>` / `--last-frame <path|url>` — a two-frame motion between them. All frame anchors take local files.
+
+Frame anchors are **compositional guidance, not pixel-pinning** — the model
+repaints the frame (same scene and composition, not the same pixels), and
+regenerating doesn't change that. Chained clips (a cutscene sequence, a
+branching video story) stay coherent when each clip starts from the previous
+clip's REAL last frame, so drift never accumulates:
+
+```bash
+ffmpeg -sseof -0.2 -i ./assets/prev.mp4 -update 1 -q:v 1 last.png
+npx genex video "she turns and walks toward the far door" --start-frame last.png
+```
+
+Write chained prompts as CHANGE ONLY — the start frame already says everything
+else. Cut clip-to-clip, or crossfade ~200 ms to hide the residual repaint.
 
 ## Options
 
-- `--duration <sec>` — target clip length.
+- `--duration <sec>` — target clip length, 5–15 seconds (default 5; clips bill
+  per second).
 - `--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.
+- `--resolution <480p|768p|2k|4k>` — default 768p (the top native mode). `2k`/`4k` upscale the same base at ~2–3× the cost; `480p` is the opt-down for clips where fidelity genuinely does not matter. Loop clips ignore it.
+- `--ref <path|url>` — repeatable, up to 9 subject/style reference images, cited in the prompt as "Image 1"…"Image N" — the way one character or art style holds across many clips. Cannot combine with `--frame`/`--loop`.
 - `--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.
@@ -43,8 +64,9 @@ npx genex video "camera drifts slowly forward, banners stirring" --frame ./asset
 
 ## Cost
 
-Typical: **20 credits** per video. Live prices and your balance:
-`npx genex doctor`.
+From **23 credits** for a 5 s 768p clip (1 credit = $0.01); longer clips, 2K/4K
+and `--frame` menu loops cost more, and the command prints the exact quote
+before it waits. Live prices and your balance: `npx genex doctor`.
 
 ## Waiting
 
@@ -55,5 +77,6 @@ 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.
+- **"Prompt rejected"** — the content-safety filter; never retryable with the same wording. The measured false-positive class is anatomy being pierced or entered (cables/wires/needles into a body — biomech vocabulary trips it). Describe the object or machine instead: "a statue-like figure threaded into the wall" passes where "cables entering her spine" fails.
 - **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

@@ -92,4 +92,7 @@ tiling floor and three paid assets nobody loaded.
 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.
+for a game you build and ship yourself. When the user wants that game live on
+Genex with its own URL, the AGENTS.md rules say how to offer it; on a yes the
+folder is connected to a hosted game in place — same cards, same rules — and
+the `$genex-tool-publish` card arrives with the publishing commands.

package/templates/skills/genex-updates/SKILL.md

@@ -38,7 +38,7 @@ update, so update immediately.)
 Run exactly the command the nudge printed, from the game project root:
 
 ```bash
-npm i -D @genex-ai/cli-demo@latest   # the genex CLI (a dev dependency)
+npm i -D @genex-ai/cli-demo@dev   # the genex CLI (a dev dependency)
 npm i @genex-ai/embed-sdk@latest     # identity/saves SDK (ships inside the game)
 npm i @genex-ai/multiplayer@latest   # multiplayer SDK (only if the game uses it)
 ```