@genex-ai/cli-demo 1.31.1 → 1.32.0-dev.650

package/templates/controllers/quality/pick-asset.ts

@@ -9,6 +9,7 @@
 // whose backfill hasn't run). loadTextureWithFallback retries the bare URL on
 // a rung failure, so the worst case is today's behavior — never a broken boot.
 import type { QualityTier } from './tier.ts';
+import { withDeadline, RUNG_DEADLINE_MS, ORIGINAL_DEADLINE_MS } from './deadline.ts';
 
 // Host-agnostic on purpose: each stand serves generated assets from its own
 // domain (prod assets.genex.technology, dev assets.auras.cc), and baking one
@@ -56,23 +57,28 @@ export async function loadTextureWithFallback<T>(
   url: string,
   tier: QualityTier,
   load: (resolvedUrl: string) => Promise<T>,
-  opts?: { ktx2Load?: (resolvedUrl: string) => Promise<T> },
+  opts?: { ktx2Load?: (resolvedUrl: string) => Promise<T>; deadlineMs?: number },
 ): Promise<T> {
+  // EVERY RUNG IS BOUNDED. The fallbacks below live in `catch`, so they advance
+  // on a rejection and never on silence — a rung that HANGS rather than 404s
+  // parked the boot forever, with no error in the console. `deadlineMs: 0`
+  // opts out.
+  const rungMs = opts?.deadlineMs ?? RUNG_DEADLINE_MS;
   const picked = pickAsset(url, tier);
   if (picked !== url && opts?.ktx2Load) {
     try {
-      return await opts.ktx2Load(`${picked}.ktx2`);
+      return await withDeadline(opts.ktx2Load(`${picked}.ktx2`), rungMs, `ktx2 texture ${picked}`);
     } catch {
-      console.warn(`[genex-quality] ktx2 variant missing for ${picked} — using the browser-decodable rung`);
+      console.warn(`[genex-quality] ktx2 variant missing or too slow for ${picked} — using the browser-decodable rung`);
     }
   }
-  if (picked === url) return load(url);
+  if (picked === url) return withDeadline(load(url), opts?.deadlineMs ?? ORIGINAL_DEADLINE_MS, `texture ${url}`);
   try {
-    return await load(picked);
+    return await withDeadline(load(picked), rungMs, `texture rung ${picked}`);
   } catch {
-    // Missing rung (old asset, un-backfilled env) — degrade to the original.
-    console.warn(`[genex-quality] rung missing for ${url} — loading the original`);
-    return load(url);
+    // Missing or hung rung (old asset, un-backfilled env) — degrade to the original.
+    console.warn(`[genex-quality] rung missing or too slow for ${url} — loading the original`);
+    return withDeadline(load(url), opts?.deadlineMs ?? ORIGINAL_DEADLINE_MS, `texture ${url}`);
   }
 }
 
@@ -90,7 +96,28 @@ export async function loadTextureWithFallback<T>(
 function modelBudgetFor(tier: QualityTier): number {
   return tier.name === "phone" || tier.name === "phone-low" ? 1024 : 2048;
 }
-const MODEL_ROLE_RE = /^(model-glb|character-rigged(-a\d+)?-glb(-r\d+)?)$/;
+/** Which roles the server actually ladders. This MIRRORS `MODEL_RUNGS` in
+ *  apps/api/src/generation/model-rungs.ts and the two move together: a role
+ *  the writer emits but this list misses is a rung computed, stored and never
+ *  requested — every tier silently fetches the provider-raw original instead,
+ *  which is the one thing the ladder exists to prevent. Mirroring the writer
+ *  is always the safe side of the error, because a rung that turns out not to
+ *  exist just warns and falls back (see loadModelWithFallback below).
+ *
+ *  Second line = the AG-908 Tripo mesh lanes: `genex model segment` (a static
+ *  prop, simplified like model-glb), `genex model rig`, and `genex model
+ *  animate` — one `model-anim-<preset>-glb` per clip plus the
+ *  `model-animations-glb` bundle. Animation-only clip GLBs from the character
+ *  lane (`character-motion-*-glb`) are deliberately NOT here: the rung
+ *  pipeline would prune away the sampler data that IS the clip. */
+// `rigged-character.glb` is the role the GUIDED character lane actually writes —
+// reversed words and a dot extension, unlike every other entry here. Until
+// 2026-09-07 neither this regex nor the server's rung writer knew it, so every
+// generated character was fetched provider-raw (measured: 23.85 MB, and its
+// texture failed to decode into a white body). The dot is safe: the rung URL is
+// built by appending `@<width>`, so it lands as `rigged-character.glb@2048`.
+const MODEL_ROLE_RE =
+  /^(model-glb|character-rigged(-a\d+)?-glb(-r\d+)?|rigged-character\.glb|model-segmented-glb|model-rigged-glb|model-animations-glb|model-anim-.+-glb)$/;
 
 /** Resolve the model URL a THIS-tier device should load. `ktx2: true` (from
  *  createGltfLoader) upgrades to the GPU-compressed sibling. */
@@ -115,22 +142,28 @@ export async function loadModelWithFallback<T>(
   url: string,
   tier: QualityTier,
   load: (resolvedUrl: string) => Promise<T>,
-  opts?: { ktx2?: boolean },
+  opts?: { ktx2?: boolean; deadlineMs?: number },
 ): Promise<T> {
+  // See the note in `loadTextureWithFallback`: without a deadline a hung rung
+  // never reaches these `catch` blocks and the boot never finishes. The
+  // original gets a longer one — reaching it at all means every rung failed,
+  // and it is the archival asset.
+  const rungMs = opts?.deadlineMs ?? RUNG_DEADLINE_MS;
+  const originalMs = opts?.deadlineMs ?? ORIGINAL_DEADLINE_MS;
   const withKtx2 = pickModel(url, tier, opts);
   const universal = pickModel(url, tier, { ktx2: false });
   if (withKtx2 !== universal) {
     try {
-      return await load(withKtx2);
+      return await withDeadline(load(withKtx2), rungMs, `ktx2 model rung ${withKtx2}`);
     } catch {
-      console.warn(`[genex-quality] ktx2 model rung missing for ${url} — trying the universal rung`);
+      console.warn(`[genex-quality] ktx2 model rung missing or too slow for ${url} — trying the universal rung`);
     }
   }
-  if (universal === url) return load(url);
+  if (universal === url) return withDeadline(load(url), originalMs, `model ${url}`);
   try {
-    return await load(universal);
+    return await withDeadline(load(universal), rungMs, `model rung ${universal}`);
   } catch {
-    console.warn(`[genex-quality] model rung missing for ${url} — loading the original`);
-    return load(url);
+    console.warn(`[genex-quality] model rung missing or too slow for ${url} — loading the original`);
+    return withDeadline(load(url), originalMs, `model ${url}`);
   }
 }

package/templates/controllers/shared/physics-world.ts

@@ -59,8 +59,6 @@ export interface PhysicsWorldOptions {
   allowedLinearError?: number;
   /** Contact prediction distance (length units). Default 0.002. */
   predictionDistance?: number;
-  /** Minimum island size for parallelism. Default 128. */
-  minIslandSize?: number;
   /** Max CCD substeps. Default 1. */
   maxCcdSubsteps?: number;
   /** Contact softness frequency (Hz). Default 30. */
@@ -211,8 +209,12 @@ export class PhysicsWorld {
       options.numInternalPgsIterations ?? 1;
     this.world.integrationParameters.normalizedAllowedLinearError =
       options.allowedLinearError ?? 0.001;
-    this.world.integrationParameters.minIslandSize =
-      options.minIslandSize ?? 128;
+    // `minIslandSize` is deliberately NOT set. Rapier 0.20.0 (2026-08-08)
+    // removed it from `IntegrationParameters`, and the skill installs the
+    // package unpinned — so a game that set it failed `tsc` on its first build
+    // (measured on a hosted session 2026-09-03) and the agent patched this
+    // vendored file by hand. The knob only tuned island parallelism, which the
+    // JS build never had.
     this.world.integrationParameters.maxCcdSubsteps =
       options.maxCcdSubsteps ?? 1;
     this.world.integrationParameters.normalizedPredictionDistance =

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

@@ -101,12 +101,13 @@ they crop well to a portrait and read as one set across the cast.
 npx genex character preview <concept-id> --candidate <1|2|3> --user-approved
 ```
 
-Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
-front, back, left, and right views and report its measured face count.
-Preserve that model in R2. The 10,000-face triangle remesh—not the
-high-detail source—is rigged and animated. In the default lane, proceed to
-the remesh directly; when the player explicitly requested a custom character,
-ask for their explicit approval first. (For the custom lane's approvals, use
+Meshy 7 Image-to-3D (Ultra, 4k textures by default) first produces an
+unremeshed high-detail model. Show its front, back, left, and right views and
+report its measured face count. Preserve that model in R2. A triangle remesh
+at the face budget you approve—not the high-detail source—is rigged and
+animated. In the default lane, proceed to the remesh directly; when the player
+explicitly requested a custom character, ask for their explicit approval
+first. (For the custom lane's approvals, use
 your question tool when you have one; if you have none, a short numbered list
 in chat.)
 
@@ -122,10 +123,10 @@ npx genex character finalize <preview-id> \
   --animation <action-id>
 ```
 
-`--animation` is repeatable. Finalization uses Meshy 6, creates the approved
-10k triangle remesh, rigs it, adds the immutable preview-reviewed neutral-v3
-idle/walk/run/crouch/jump controller pack, and stores the source, remesh, rig,
-and clips at permanent Genex asset URLs. It prints the complete Genex-credit
+`--animation` is repeatable. Finalization creates the approved triangle
+remesh from the Meshy 7 preview, rigs it, adds the immutable preview-reviewed
+neutral-v3 idle/walk/run/crouch/jump controller pack, and stores the source,
+remesh, rig, and clips at permanent Genex asset URLs. It prints the complete Genex-credit
 quote before enqueueing. The Meshy API key remains server-side; never ask the
 user for one or call Meshy directly from game code.
 
@@ -133,18 +134,40 @@ Meshy's public API performs automatic rigging. The manual joint-marker step
 shown in Meshy Web is not exposed through that API, so do not claim that this
 part of the hosted workflow is reproduced.
 
-The legacy one-shot text workflow is explicit and does not masquerade as the
-reviewed image-first path:
+The one-shot text workflow is explicit and does not masquerade as the
+reviewed image-first path. It runs the same Meshy 7 (Ultra, 4k) — the only
+thing it skips is the review:
 
 ```bash
 npx genex character "compact fantasy knight" --direct-text
 ```
 
+## The quality knobs are yours to set
+
+Every lane runs Meshy 7 with Ultra and 4k textures unless you say otherwise,
+and every knob is priced in the quote the command prints before enqueueing.
+Choose per role, and say the choice in one line of chat:
+
+- `--approve-remesh <faces>` (finalize) / `--polycount <faces>` (one shot):
+  the rigging copy's face budget, 10000-100000. **10000** for anything seen
+  in a crowd or at a distance; **20000-30000** for the player's body in a
+  third-person game; **50000+** only for a hero seen in close-up cutscenes.
+  Mobile budgets favour the low end. The number moves no cost.
+- `--texture 2k|4k|8k` (preview / one shot): 4k is the default; 8k (+5
+  credits) only for a body the camera sits on in close-up; 2k for crowds.
+- `--no-ultra` (preview / one shot): −5 credits and less surface detail —
+  crowd enemies and stand-ins, never the player's body.
+- `--pose a-pose|t-pose` (one shot): the preferred rest pose; the other
+  stays the structural-QA fallback.
+- `--height <metres>`: 0.5-3, default 1.7.
+
 Useful options:
 
 ```bash
-npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 --height 1.7
+npx genex character preview <concept-id> --candidate 2 --user-approved --texture 8k
+npx genex character finalize <preview-id> --user-approved --approve-remesh 30000 --height 1.7
 npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 --animation 466 --no-wait
+npx genex character "market guard" --direct-text --polycount 10000 --no-ultra --texture 2k
 npx genex wait <generation-id>
 ```
 
@@ -153,10 +176,10 @@ npx genex wait <generation-id>
 compatibility path. The guided parity workflow always installs neutral-v3.
 `--no-wait` returns a generation id for `genex wait`; it does not create a
 second paid request. In the default lane, `--user-approved` and
-`--approve-remesh 10000` record the pick you made and announced after showing
+`--approve-remesh <faces>` record the pick you made and announced after showing
 the real images. When the player explicitly requested a custom character,
 never add `--user-approved` until they have actually seen and selected the
-candidate, and never add `--approve-remesh 10000` until they have seen the
+candidate, and never add `--approve-remesh <faces>` until they have seen the
 four high-detail views and measured face count.
 
 Before handoff, capture idle, walk, run, crouch-idle, crouch-move, and jump.
@@ -165,6 +188,35 @@ shrugging palms-up poses, permanently raised elbows, or a gait whose
 upper-body style contradicts the requested character. “No T-pose” is not
 an animation-quality check.
 
+## Import a character the player already has (`character import`)
+
+When the player hands you a humanoid mesh — their own Blender character, a
+bought asset, an export from another tool — **import it, never regenerate
+it**. The upload is free; Uthana then auto-rigs it (one paid call, finger
+joints included) and it becomes a character of theirs:
+
+```bash
+npx genex character import ./assets/knight.glb --height 1.8
+npx genex character animate <character-id> --locomotion --no-wait   # the 16-clip walk/run set
+npx genex controller character --character <character-id>          # once locomotion lands
+```
+
+What Uthana needs: a **biped humanoid** in a **T- or A-pose, feet on the
+ground, facing +Z**, as a `.glb` under **30 MB** (textures are the bulk —
+shrink them, not the mesh). Non-biped bodies go through `npx genex model
+import` + `npx genex model rig` (7 body plans) instead. `--no-fingers` skips
+finger joints when the hands are blobs (Uthana warns poor finger geometry
+lowers rig quality).
+
+An imported character is **Uthana-rigged**: `character animate` in plain
+words, `--locomotion` and `--video` all work on it, and the manifest reads
+`rig: "uthana-biped"`. The Meshy catalog (`--animation <id>`) and the
+neutral-v3 controller pack do **not** apply — those are Meshy-rig clips — so
+run `--locomotion` before installing the controller, or the body stands
+still. `--texture`, `--no-ultra`, `--pose` and `--polycount` are Meshy
+generation knobs and are refused here: an import keeps the mesh exactly as it
+is.
+
 ## Search first; use action IDs
 
 ```bash
@@ -305,6 +357,16 @@ game with a generated character, every remote wears it — one
   `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.
+- **"The character provider is out of credit on this stand"** (the line `npx genex
+  wait` / `npx genex character` prints when the VENDOR refused for money — Meshy
+  "Insufficient funds", Tripo code 2010) — this is the platform's own provider
+  account, not your prompt and not the user's credits (the charge auto-refunds),
+  and no re-run changes it. Take the same fallback: keep the profile VRM avatar,
+  tell the user in one plain line that the game is wearing the platform avatar
+  because the character lane is unavailable on this stand, record
+  `Player character: VRM — provider out of credit` in DESIGN.md, and mark the spot
+  with `// TODO(genex): regenerate when credits refill`. `npx genex doctor` shows
+  the lane as OUT OF CREDIT while it lasts.
 - **"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.

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

@@ -406,12 +406,15 @@ fight — the title in the display font is a finished title, not a stand-in:
   re-prompt the still against the new direction (or `--edit` it against the
   new reference) and re-run the video from the new still. Agent-initiated
   polish never does.
-- **The menu video renders 1080p by default — leave it alone.** Every video
+- **The menu video renders 768p by default — leave it alone.** Every video
   path, the frame-conditioned (`--frame`) menu route included, defaults to
-  1080p: the menu clip is full-screen key art, and 720p stretched across a
-  desktop reads soft. Don't pass a resolution flag at all; `--resolution 720p`
-  exists only as a deliberate cost opt-down for clips that are genuinely
-  incidental — never the main menu.
+  768p — the model's top NATIVE mode; `--resolution 2k` is an upscale of the
+  same base at ~2× the cost, worth it only if the menu still reads soft on a
+  large desktop. Don't opt DOWN: `--resolution 480p` exists for clips that are
+  genuinely incidental — never the main menu.
+- **The clip ships with a native audio track — keep the menu `<video>` muted.**
+  Autoplay requires `muted` anyway; menu music stays the `npx genex music`
+  track under the Music volume slider, not the clip's baked-in audio.
 - **Pause/victory/defeat variants reuse the same video — as GRADES.** Same
   `<video>` element or URL, different emotion via CSS `filter` on the
   background: pause = a plain dark overlay (`rgba(0,0,0,0.55)`); defeat =
@@ -439,12 +442,13 @@ fight — the title in the display font is a finished title, not a stand-in:
   frame: the seamless-loop mode. The URL must be one printed by `npx genex image`.
 - `--first-frame <url>` / `--last-frame <url>` (video) — two-frame mode for a
   genuine state change; expect a loop seam.
-- `--duration <sec>` (video) — 4, 6, or 8 for frame-conditioned clips;
-  default 8.
-- `--resolution <720p|1080p>` (video) — every path defaults to **1080p**, the
-  `--frame` menu route included. `720p` is the deliberate cost opt-down
-  (~half the credits) for incidental clips — not for the menu. Loop clips
-  (`--loop`) ignore it (that model has no resolution parameter).
+- `--duration <sec>` (video) — 5–15 for frame-conditioned clips; default 8
+  (menu loops read better long).
+- `--resolution <480p|768p|2k|4k>` (video) — every path defaults to **768p**
+  (the top native mode), the `--frame` menu route included. `2k` upscales for
+  ~2× the cost; `480p` is the cost opt-down for incidental clips — not for the
+  menu. Loop clips (`--loop`) ignore it (that model has no resolution
+  parameter).
 - `--aspect 16:9 --quality high` (image) — the right settings for a menu frame.
 - `--no-wait` — enqueue and return immediately with the generation id; pick
   the result up later with `npx genex wait <id>` (safe to re-run — it attaches

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

@@ -9,13 +9,17 @@ Turn a text prompt into a real, game-ready **GLB** and drop it into the project.
 
 ## When to use this vs. procedural geometry
 
-- **Use `npx genex model`** for a specific, recognizable object — a barrel, a chair, a
-  sword, a spaceship, an animal. You get a real textured mesh.
-- **Use `$genex-threejs-procedural-assets`** when code is the more efficient
-  engine: structures and buildings, modular kits, and anything placed many
-  times with variation (editable, seeded, no GLB file). Mixing both in one
-  scene is the normal way to build a detailed world — generated hero pieces
-  over procedural dressing.
+- **Use `npx genex model`** for a specific, recognizable object the player will
+  look at — a barrel, a chair, a sword, a spaceship, an animal, a named
+  building, the thing the request asked for. You get a real textured mesh, and
+  this is the default route whenever code would not honestly make the object
+  read as itself.
+- **Use `$genex-threejs-procedural-assets`** for what is structural, repeated,
+  distant, or parametric — modular kits, fences, walls, paving, terrain,
+  anything placed many times with variation (editable, seeded, no GLB file) —
+  and for a close-up object only when the code result meets the same bar and
+  you have checked it in a capture. Mixing both in one scene is the normal way
+  to build a detailed world.
 
 **The output is a STATIC, unrigged mesh by default — no skeleton, no animation
 clips.** A "wolf" or "guard" from this command can be posed and moved as one
@@ -62,6 +66,26 @@ URL passes through. The prompt becomes optional (it's recorded for the ledger,
 the provider works from the image alone). A clear, single-object image on a
 plain background converts best.
 
+## Bring your own mesh (`model import`)
+
+A model the player already has — a Blender export, a bought asset, a file
+from another tool — is **imported, never rebuilt**. Importing is free and
+makes it a model of theirs, so every id-only lane works on it: `model rig`,
+`model animate`, `model segment`, `blender import`, and "Use in game" on the
+dashboard.
+
+```bash
+npx genex model import ./assets/hero-cart.glb
+```
+
+- `.glb` only (binary glTF 2.0), up to 64 MB. A `.gltf` + `.bin` pair or an
+  FBX is exported as one `.glb` first — in Blender, File → Export → glTF 2.0
+  with format "glTF Binary".
+- The file is checked (magic, version, triangle geometry) before the row
+  completes; a bad file is refused and nothing is charged.
+- A humanoid that should walk goes through `$genex-ai-character`'s
+  `character import` instead — same upload, plus a Uthana auto-rig.
+
 ## Split into parts (`model segment`)
 
 ```bash
@@ -252,6 +276,20 @@ scene is a ghost: players and objects pass straight through it.
 
 - `--image <path|url>` — build from a reference image (local file ≤4 MB, or a
   generated-asset URL); the prompt becomes optional.
+- **Quality knobs** (Tripo H3.1; each is priced in the quote, choose per
+  asset and say it in one line): `--texture standard|detailed|none` (detailed
+  is the default and +10 credits over standard; `none` is geometry only, for
+  something you texture in code), `--geometry detailed` (+20 — a hero prop
+  the camera sits on; never for a crate), `--quad` (+5, quad-dominant mesh
+  for anything you will deform or edit further; face limit ≤150000),
+  `--low-poly` (+10, smart low-poly topology — the game-ready choice for
+  props that appear in numbers; it holds `--face-limit` to 1000-20000,
+  500-10000 with `--quad` — omit the flag to take 20000 — and runs a
+  post-process after the mesh, so allow up to 30 minutes), `--parts` (+20, separated named parts at
+  generation — cheaper than `model segment` when you know up front you need
+  doors, wheels, magazines), `--face-limit <n>` (1000-2000000, default
+  150000; the raw cap — the game still loads the @2048/@1024 rungs),
+  `--auto-size` (real-world metres by AI estimate).
 - `--granularity simple|balanced|detailed` — (`model segment`) part granularity.
 - `--type <plan>` — (`model rig`) body plan; omit to let the free rig-check pick.
 - `--preset walk[,run,…]` — (`model animate`) clips to retarget; billed per clip.

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

@@ -225,7 +225,7 @@ first one is the one a screenshot of the whole arena will not show you.
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
   this texture generation. Tell the user the facts the CLI printed: their balance,
   this generation's cost, and when their credits refill. Then offer to continue the

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

@@ -37,13 +37,18 @@ The clip lives in Genex storage (R2) and loads straight from that URL — you do
 download it and nothing is committed to your repo. The URL is permanent (local dev,
 published game, and remixes alike).
 
-> **Cost & length:** the default is a **5-second, 1080p** clip — the right default
-> for anything the player looks at directly. Only pass `--duration` when the content
-> genuinely needs to be longer (a cutscene), and `--resolution 720p` only when the
-> clip is genuinely incidental (a small in-world screen seen from a distance): it
-> halves the cost, but 720p stretched across the whole screen reads soft. mp4 has
-> **no alpha channel**, so a video is always a full rectangle (there are no
-> transparent video decals).
+> **Cost & length:** the default is a **5-second, 768p** clip (MiniMax H3's top
+> native mode) — the right default for anything the player looks at directly.
+> Only pass `--duration` when the content genuinely needs to be longer (5–15s;
+> a cutscene), `--resolution 2k`/`4k` only for hero shots (they upscale the
+> same native base, run on an older and pricier model, and cost roughly 3–4×),
+> and `--resolution 480p` only when
+> the clip is genuinely incidental (a small in-world screen seen from a
+> distance). Every clip carries a **native stereo audio track** (score, foley,
+> even dialogue) — in-game `<video>` elements autoplay muted, so unmute it only
+> when the sound is the point (a cutscene) and route it through the SFX volume
+> slider. mp4 has **no alpha channel**, so a video is always a full rectangle
+> (there are no transparent video decals).
 
 ## Play it in Three.js
 
@@ -133,15 +138,32 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 ## Options
 
 - `--loop` — a seamless loop (for screens, ambient backdrops, video decals).
-- `--duration <sec>` — clip length 1–15; default 5. Only raise it when the content
-  genuinely needs more — longer clips cost more and take longer.
-- `--resolution 720p|1080p` — output resolution (default **1080p**). `--resolution
-  720p` halves the cost — use it only when quality genuinely doesn't matter (a small
-  far-away in-world screen). `--loop` clips ignore it (model default).
-- `--frame <url>` — one generated image as BOTH first and last frame — the
-  seamless-loop mode (motion must return to its start).
-- `--first-frame <url>` / `--last-frame <url>` — two-frame motion between two
-  stills (a genuine state change; expect a loop seam).
+- `--duration <sec>` — clip length 5–15; default 5. Only raise it when the content
+  genuinely needs more — clips bill per second.
+- `--resolution 480p|768p|2k|4k` — output resolution (default **768p**, the top
+  native mode). `2k`/`4k` upscale the same base for hero shots at ~2–3× the
+  cost; `480p` is the cost opt-down for genuinely incidental clips. `--loop`
+  clips ignore it (model default).
+- `--frame <url|file>` — one generated image (or a local file ≤4 MB) as BOTH
+  first and last frame — the seamless-loop mode (motion must return to its
+  start; the seam is mathematically exact).
+- `--start-frame <url|file>` — continue from this frame, no end anchor — the
+  clip-chaining primitive (see below). Local files inline like `--frame`.
+- `--first-frame <url|file>` / `--last-frame <url|file>` — two-frame motion
+  between two stills (a genuine state change — a door opens, day turns to
+  night). `--first-frame` alone means `--start-frame`.
+
+**Frame anchors are compositional guidance, not pixel-pinning.** The model
+repaints every anchor — the clip's first frame lands near the supplied image
+(same scene, same composition) but not ON it, and regenerating doesn't change
+that; it is how the mode works. Plan for it: chains stay coherent when each
+clip starts from the previous clip's REAL frame (below), and a supplied
+`--last-frame` steers where motion ends rather than guaranteeing the exact
+pixels.
+- `--ref <url|file>` — repeatable, up to 9 subject/style reference images.
+  Cite each in the prompt by its order: "Image 1 is the hero — she walks into
+  frame…". This is how the SAME character or art style holds across many clips
+  (a cutscene series, an episodic story). Cannot combine with `--frame`/`--loop`.
 - `--no-wait` — enqueue and return immediately, without the URL. Fire-and-forget
   only: re-running the command creates (and bills) a NEW video.
 - `--api-url <url>` — override the API base (local dev).
@@ -149,11 +171,47 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 Menu backdrops belong to `$genex-ai-menu`; a cohesive art-directed HUD sprite
 set belongs to `$genex-ai-hud` — both build on `npx genex image`/`video`.
 
+## Interactive video games
+
+Clips are cheap and fast enough to be a game's PRIMARY content, not just set
+dressing — an interactive movie (Detroit-style branching story), a generated-
+evidence detective game, a video-book. The pattern that makes it hold together:
+
+- **Branching scenes**: generate one clip per story node at build time, ship
+  the mp4 URLs in a scene-graph JSON, play them full-screen with DOM choice
+  buttons; preload the clips reachable from the current node while it plays.
+- **Visual continuity — chain from REAL frames**: extract the previous clip's
+  actual last frame and seed the next clip with it:
+
+  ```bash
+  ffmpeg -sseof -0.2 -i prev.mp4 -update 1 -q:v 1 last.png
+  npx genex video "she turns and walks toward the far door" --start-frame last.png
+  ```
+
+  Never chain from the image you WISHED the clip ended on — anchors are
+  repainted (above), so the wish and the clip disagree and every join jumps.
+  Chaining from the real frame keeps drift from accumulating; the residual
+  repaint at each cut is small, and a ~200 ms crossfade between the two
+  `<video>` elements hides it entirely. Write chained prompts as CHANGE ONLY
+  ("she turns…", "the light flickers out") — the start frame already says
+  everything else.
+- **Cast consistency**: give every scene the same `--ref` images of your
+  protagonist and key locations — the single biggest quality lever for any
+  multi-clip story.
+- Keep hard facts (dialogue you must control, exact text) in subtitles and
+  `npx genex voice` lines layered on top; the clip's own audio is atmosphere.
+
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Prompt rejected"** — the provider's content-safety filter blocked the prompt.
   This is non-retryable; retrying the same wording fails again. Rewrite the prompt.
+  The measured false-positive class is anatomy being pierced or entered
+  (cables/wires/needles into a body — biomech and cyberpunk vocabulary trips
+  it). Describe the object or machine instead of the anatomy: "a statue-like
+  figure threaded into the wall" passes where "cables entering her spine"
+  fails. Word it that way on the FIRST try — each rejection still ends a
+  billed-then-refunded round trip.
 - **Nothing plays / black surface** — the first `video.play()` must run inside a user
   gesture (click/keydown); confirm it's called and its promise rejection is logged.
 - **Tainted-source / security error** — set `video.crossOrigin = "anonymous"` before