@genex-ai/cli-demo 0.80.2-dev.213 → 0.84.0-dev.215

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

@@ -81,7 +81,10 @@ reason is the failure mode this section exists to kill:**
 (cinematic, the example below) / CSS plate (styled FROM the brief —
 gradients, borders, chamfers per the game-ui corner rules; default-gray
 plates are a defect) / sprite chrome (from the HUD sheet or a dedicated
-generation — Tier 2b, when the brief is ornate). The per-genre lean lives
+generation — Tier 2b, when the brief is ornate) / real glass
+(`npx genex image "<frosted panel>" --glass` — menus love frosted panels,
+and the solved RGBA carries TRUE translucency over the moving backdrop;
+`$genex-ai-image` documents the lane). The per-genre lean lives
 in the style capsules (`$genex-threejs-game-ui`'s
 references/style-capsules.md) — a lean, not a rule.
 
@@ -136,7 +139,7 @@ cycle. Two stacked `<video>` elements with the same src crossfade at the
 cycle end; any seam disappears deterministically, no regeneration lottery.
 
 **Phone tiers get the poster, not the videos** (`$genex-threejs-adaptive-quality`):
-two preloading 720p decoders while the 3D scene boots is a spike at exactly the
+two preloading HD decoders while the 3D scene boots is a spike at exactly the
 moment phones get killed for memory. On a phone tier, show the key-art poster
 image (a captured frame of the clip works) and skip `seamlessLoop` entirely —
 or defer ONE non-preloading video until after the first gameplay frame:
@@ -171,7 +174,10 @@ export function seamlessLoop(holder: HTMLElement, url: string, fade = 0.6): void
 
 Pause both videos when the menu phase hides (they're decode work), and
 resume the front one when it returns. Watch ONE full cycle in the browser
-before calling the menu done — that's the seam check.
+before calling the menu done — that's the seam check, and once the video is
+wired it is the menu's capture in the milestone smoke pass: one full loop
+cycle watched AS RENDERED. A metadata probe (ffprobe) can't see a seam, a
+panel covering the video, or a video that never plays — only watching can.
 
 **Work async — the menu must never block the game.** The still is
 `--edit`-anchored to the concept mockup, so it's style-dependent: generate it
@@ -184,6 +190,17 @@ the moment the user approves the concept (not before), enqueue the video with
 (R2) — permanent, public, CORS-open; you load them straight from the printed
 URLs, nothing is downloaded or committed.
 
+**When the generated art lands, the upgrade is a RE-COMPOSITION — not a
+backdrop swap.** DELETE the placeholder panel/card the moment the still or
+video goes in: the still was generated with negative space precisely so the
+buttons and logo sit DIRECTLY on the key art. A placeholder card left
+floating over the finished video is the single most common bad menu — a
+near-opaque panel (plus its darkening layers) hides the art you just paid
+for, and the menu reads as the plain CSS draft it started as. Allowed over
+the art: a thin, low-opacity scrim strictly behind the button rail for
+legibility, and at most ONE subtle full-screen grade layer. NEVER a
+card/panel covering the art.
+
 **Two failed video attempts = ship the still. Hard stop.** Video is the one
 generation that fails server-side with real frequency (render timeouts), and
 every attempt costs minutes of waiting. One retry is fair — shorten the clip
@@ -350,7 +367,11 @@ not):
   `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`. Short names (one or two
+  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
   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).
@@ -370,14 +391,12 @@ not):
   re-anchored the look) re-opens this rule once — re-edit the still
   (`--edit` against the new concept mockup) and re-run the video from the
   new still. Agent-initiated polish never does.
-- **The menu (`--frame`) path renders 720p — don't force 1080p.** The
-  frame-conditioned first-last-frame route was rejected by the provider at
-  1080p (repeated 422 failures that shipped a dead static menu), so the menu
-  video path defaults to the proven-good, seamless-looping 720p — no flag
-  needed. The DOM crossfade + full-screen scale read fine at 720p; do NOT pass
-  `--resolution 1080p` on a `--frame` menu clip just to sharpen it, or you risk
-  re-triggering the 422 and losing the video entirely. (Plain text-to-video,
-  without `--frame`, still defaults to 1080p.)
+- **The menu video renders 1080p 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.
 - **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 =
@@ -407,11 +426,10 @@ not):
   genuine state change; expect a loop seam.
 - `--duration <sec>` (video) — 4, 6, or 8 for frame-conditioned clips;
   default 8.
-- `--resolution <720p|1080p>` (video) — plain text-to-video defaults to 1080p;
-  the frame-conditioned (`--frame`) menu path defaults to **720p** for
-  reliability (1080p was rejected there). `720p` is also the cost fallback
-  (~half the credits). Loop clips (`--loop`) ignore it (that model has no
-  resolution parameter).
+- `--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).
 - `--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

@@ -14,6 +14,14 @@ Turn a text prompt into a real, game-ready **GLB** and drop it into the project.
 - **Use `$genex-threejs-procedural-geometry`** for parametric/abstract shapes,
   terrain, or anything you want to generate in code (infinite variations, no files).
 
+**The output is a STATIC, unrigged mesh — no skeleton, no animation clips.**
+A "wolf" or "guard" from this command can be posed and moved as one object,
+but its limbs cannot animate. Anything that must walk, attack, or die on
+screen routes to the creature lane instead: `npx genex creature` for
+biped-shaped bodies (real rig + library clips), or this command plus the
+procedural-motion recipes for everything else — `$genex-threejs-creatures`
+owns that split. The player's own character is `$genex-ai-character`.
+
 ## Run
 
 ```bash

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

@@ -0,0 +1,142 @@
+---
+name: genex-ai-music
+description: Generate a real instrumental background-music track (mp3) from a text prompt with `npx genex music`, then loop it quietly under the game in Three.js. Use for the one looping gameplay track every game with generated audio should have (reused on the menu at lower volume), plus optional boss or menu-specific tracks — always instrumental, always behind Music/SFX volume sliders in settings.
+---
+
+# Genex AI · Music
+
+Turn a prompt into a real **mp3** instrumental track and loop it under the game.
+One track transforms how finished a game feels — a silent game with polished art
+still reads as a tech demo.
+
+## When to use this vs. sfx
+
+- **Use `npx genex music`** for the continuous bed: the gameplay loop, a boss
+  theme, a menu theme. Tracks are instrumental by design (the API enforces it —
+  vocals under gameplay read as karaoke).
+- **Use `$genex-ai-sfx`** for event sounds — impacts, pickups, UI ticks. The
+  0.5–22 s sfx lane cannot produce a music bed; don't try.
+
+**The default plan is ONE track:** a ~90 s loopable gameplay track, reused on
+the menu (same URL, lower volume). Propose extra tracks (boss/menu-specific) as
+their own Assets-table rows only when the game's shape earns them.
+
+## Run
+
+```bash
+npx genex music "<prompt>" --no-wait
+npx genex music "dark orchestral hunt, low strings and taiko, steady menace, seamless loop, consistent energy, no intro, no outro" --duration 120 --no-wait
+```
+
+`--duration <sec>` (10–300) sets the length; the default **90 s** is the sweet
+spot for a loop. Music takes a minute-plus — enqueue with `--no-wait` alongside
+your other generations and pick it up with `npx genex wait <id>`. Prints:
+
+```
+https://assets.genex.technology/generations/<id>/audio-music
+```
+
+The mp3 lives in Genex storage (R2) and loads straight from that URL — you don't
+download it and nothing is committed to your repo. The URL is permanent (local
+dev, published game, and remixes alike).
+
+## Prompt recipe for loopable game music
+
+Mood + instrumentation + energy + loop wording:
+
+- Name the game's emotional register and 2–3 instruments ("brooding synthwave,
+  analog pads and arpeggio", "cozy acoustic folk, fingerpicked guitar and soft
+  strings").
+- Always end with: **"seamless loop, consistent energy, no intro, no outro"** —
+  there is no API loop flag; consistent energy at both ends is what makes
+  `setLoop(true)` inaudible. A track with a big intro pops every cycle.
+- Don't ask for vocals — the lane forces instrumental regardless.
+
+## Wire it in Three.js
+
+Music is **non-positional** (`THREE.Audio`, not `PositionalAudio`), looped,
+and QUIET — the default volume is **0.30**: it sits under the sfx, never over
+them. Browsers block autoplay, so start it on the first user gesture:
+
+```ts
+import * as THREE from "three";
+
+const listener = new THREE.AudioListener();
+camera.add(listener); // ONE listener serves music and every sfx
+
+// the URL `npx genex music` printed (R2 sends CORS headers, cross-origin works):
+const MUSIC_URL = "https://assets.genex.technology/generations/<id>/audio-music";
+const music = new THREE.Audio(listener);
+new THREE.AudioLoader().loadAsync(MUSIC_URL).then((buffer) => {
+  music.setBuffer(buffer);
+  music.setLoop(true);
+  music.setVolume(0.30); // the default — under the sfx, never over them
+  // autoplay policy: start on the first gesture (the menu's PLAY click is ideal)
+  const start = (): void => {
+    if (!music.isPlaying) music.play();
+  };
+  window.addEventListener("click", start, { once: true });
+  window.addEventListener("keydown", start, { once: true });
+});
+
+// Suspend when the tab hides (decode work + politeness), resume on return:
+document.addEventListener("visibilitychange", () => {
+  const ctx = listener.context;
+  if (document.hidden) void ctx.suspend();
+  else void ctx.resume();
+});
+```
+
+**Menu reuse:** the same `music` object at lower volume (`setVolume(0.18)`)
+during the menu phase, restored to the setting's value on PLAY — zero extra
+generations. If the loop point is audible (the track came back with an
+intro/outro despite the prompt), crossfade the tail into the head with a second
+`THREE.Audio` on the same buffer rather than regenerating.
+
+## Volume sliders are NOT optional
+
+A game with generated audio and no volume control is a failure mode. The
+settings screen gets **two sliders — Music and SFX** (music default 0.30, sfx
+~0.7), persisted (localStorage or the save slot) and applied live:
+`music.setVolume(v)` for the music bed; keep every sfx's volume routed through
+one shared multiplier. `$genex-threejs-game-ui` carries this as a hard settings
+rule — wire the sliders in the same milestone as the track.
+
+## Publish checklist
+
+- Load it from the **URL** the command printed — absolute and permanent, so it
+  resolves the same in local dev, the published game, and remixes. Nothing to
+  commit.
+- The track must be audible in the shipped game AND adjustable in settings —
+  an unwired paid track is flagged at preview/publish (the wiring audit).
+
+## Options
+
+- `--duration <sec>` — track length 10–300; default 90 (the loop sweet spot).
+  Longer costs more; a 90–120 s loop outlasts most sessions.
+- `--no-wait` — enqueue and return immediately with the generation id; pick it
+  up later with `npx genex wait <id>` (safe to re-run — it attaches to the SAME
+  generation). The default for music: build while it renders.
+- `--api-url <url>` — override the API base (local dev).
+
+## 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 music generation. Tell the user the facts the CLI printed: their
+  balance, this generation's cost, and when their credits refill. Then continue
+  the build without a music bed (the game must work silent anyway) and mark the
+  spot with `// TODO(genex): regenerate when credits refill` so the real track
+  is one command away later. Do not stop the session over this.
+- **"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.
+- **No sound** — the `AudioContext` is suspended until a user gesture; the
+  first `music.play()` must come from a click/keydown. Confirm the camera has
+  an `AudioListener`.
+- **The loop "pops" every cycle** — the track has an intro/outro (the prompt
+  missed the loop wording). One regeneration with "seamless loop, consistent
+  energy, no intro, no outro" is fair; after that, crossfade tail-into-head
+  with a second `THREE.Audio` on the same buffer instead of re-rolling.
+- **Music drowns the game** — 0.30 is the ceiling for a bed, not the floor;
+  drop it further under dialogue-heavy or ambience-led scenes.

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

@@ -10,13 +10,26 @@ also lights it (image-based lighting).
 
 ## When to use this vs. a procedural sky
 
-- **Use `npx genex skybox`** for a specific, recognizable sky/backdrop you can
-  describe — "golden hour over misty mountains", "stormy alien sky", "city at
-  night". You get a real image.
+- **Use `npx genex skybox`** for a specific, describable ENVIRONMENT — "golden
+  hour over misty mountains", "rolling thunderstorm, towering cumulonimbus",
+  "alien purple nebula", "hazy dusk sky over a distant sea horizon". You get a
+  real image.
 - **Use `$genex-threejs-atmosphere-aerial-perspective`** (or
   `$genex-threejs-volumetric-clouds`) for a fully procedural, animated,
   time-of-day sky generated in shaders.
 
+**A skybox is environment only — never content.** Buildings, trees, ruins,
+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.
+
 ## Run
 
 ```bash
@@ -81,8 +94,11 @@ scene.background = texture; // keep the raw texture for the visible sky
 
 ## Options
 
-- `--no-wait` — enqueue and return immediately (the file won't be downloaded;
-  re-run without `--no-wait` to fetch it).
+- `--raw` — send the prompt exactly as written, skipping the appended
+  environment-only guard (for the rare sky that must carry content).
+- `--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
+  to the SAME generation).
 - `--api-url <url>` — override the API base (local dev).
 
 ## Troubleshooting

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

@@ -37,11 +37,13 @@ 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, 720p** clip, and that IS the right
-> default for a looping screen or backdrop — only pass `--duration` when the content
-> genuinely needs to be longer (a cutscene). Longer, higher-res clips cost more and
-> take longer. 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, 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).
 
 ## Play it in Three.js
 
@@ -80,8 +82,9 @@ window.addEventListener("keydown", () => {
 One `VideoTexture` can feed **many** surfaces — a bank of monitors, N sprays. Cost is
 per distinct `<video>` element (media decode + one GPU upload per frame), **not** per
 surface, so sharing one element for every screen is nearly free (all play in sync).
-Keep clips **≤720p**. Pause the element (`video.pause()`) when no video surface is
-visible.
+Pause the element (`video.pause()`) when no video surface is visible; on phones,
+prefer the clip's source still as a poster and start the video only where it plays
+smoothly.
 
 ## Video decals
 
@@ -132,6 +135,9 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 - `--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

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

@@ -0,0 +1,151 @@
+---
+name: genex-ai-voice
+description: Generate a short spoken voice line (mp3) from text with `npx genex voice` — NPC barks, narrator beats, tutorial VO, announcer calls — picking a voice from the curated cast (`--voice narrator|heroine|gruff|elder|robot|imp`) or any raw ElevenLabs voice id (`--voice-id`). Billed per character, hard-capped at 1000 chars per line. Voice lines are content — keep them short, subtitled, and skippable.
+---
+
+# Genex AI · Voice
+
+Turn a line of text into a real spoken **mp3** and play it in the game. A
+guard that actually says "Halt! Who goes there?", a narrator that opens the
+run, a tutorial voice over the first jump — one or two spoken lines move a
+game from "asset flip" to "authored" faster than almost any other audio spend.
+
+## When to use this vs. music / sfx
+
+- **Use `npx genex voice`** for SPEECH: NPC barks, narrator lines, tutorial
+  VO, announcer calls, boss taunts. The text you pass IS what gets spoken —
+  write the line, not a description of it.
+- **Use `$genex-ai-music`** for the continuous instrumental bed and
+  **`$genex-ai-sfx`** for event sounds — impacts, pickups, UI ticks. A
+  scream, grunt, or monster roar is an SFX (describe it), not a voice line.
+
+**Voice lines are content, not chrome: keep them SHORT, show a SUBTITLE for
+every line, and let the player skip or interrupt.** A game that talks over
+itself un-skippably reads worse than a silent one.
+
+## Run
+
+```bash
+npx genex voice "Halt! Who goes there?" --voice gruff
+npx genex voice "Level up! New ability unlocked." --voice robot --no-wait
+```
+
+Prints:
+
+```
+https://assets.genex.technology/generations/<id>/audio-voice
+```
+
+The mp3 lives in Genex storage (R2) and loads straight from that URL — you
+don't download it and nothing is committed to your repo. The URL is permanent
+(local dev, published game, and remixes alike).
+
+## The cast
+
+Six curated archetypes — pick by gameplay role, not by auditioning ids:
+
+| `--voice` | Reads as | Use for |
+| --- | --- | --- |
+| `narrator` (default) | warm storyteller | intros, quest text, tutorials |
+| `heroine` | confident young female lead | player character, guide |
+| `gruff` | fierce warrior | guards, bosses, drill sergeants |
+| `elder` | wise old mentor | sages, shopkeepers, lore |
+| `robot` | calm neutral synthetic | AI companions, announcers, computers |
+| `imp` | husky trickster | goblins, sidekicks, comic relief |
+
+**Escape hatch:** `--voice-id <ElevenLabsVoiceId>` uses any raw ElevenLabs
+voice id (overrides `--voice`) — for when the user has a specific voice in
+mind. The cast covers the normal cases; don't browse ids speculatively.
+
+Pick ONE voice per character and stay with it — a guard who changes voice
+between barks breaks the character. The model is multilingual: text in the
+game's language comes back spoken in that language.
+
+## Cost honesty
+
+Voice is billed **per character of the submitted text**, hard-capped at
+**1000 characters** per line (longer text is clamped, and the clamp is what
+bills). A one-sentence bark costs a fraction of a credit-priced generation —
+but 30 speculative barks are 30 paid calls. Write the script first, generate
+once per line, and reuse lines (the same "Halt!" serves every guard).
+
+## Wire it in Three.js
+
+Same machinery as sfx — one `AudioListener` on the camera serves everything.
+Non-positional (`THREE.Audio`) for narrator/announcer voices; positional
+(`THREE.PositionalAudio`) when a CHARACTER in the world speaks:
+
+```ts
+import * as THREE from "three";
+
+const listener = new THREE.AudioListener();
+camera.add(listener); // ONE listener serves music, sfx, and voice
+
+const VOICE_URL = "https://assets.genex.technology/generations/<id>/audio-voice";
+const line = new THREE.Audio(listener); // PositionalAudio(listener) at the speaker's mesh for world speech
+const subtitles = document.getElementById("subtitles")!;
+
+new THREE.AudioLoader().loadAsync(VOICE_URL).then((buffer) => {
+  line.setBuffer(buffer);
+  line.setVolume(0.9);
+});
+
+function sayLine(text: string): void {
+  if (line.isPlaying) line.stop(); // a new line interrupts the old — never overlap voices
+  line.play();
+  subtitles.textContent = text;    // SUBTITLE every voice line, always
+  subtitles.classList.add("visible");
+  line.onEnded = () => subtitles.classList.remove("visible");
+}
+```
+
+- **Subtitles are mandatory** — the same text you generated from, shown while
+  the line plays. Muted players and streamers still get the content.
+- **Route voice volume through the SFX slider** (or its own Voice slider in a
+  dialogue-heavy game) — `$genex-threejs-game-ui`'s settings rule; an
+  uncontrollable voice is worse than none.
+- **Duck the music** while a line plays (`music.setVolume(0.15)`, restore on
+  `onEnded`) so speech never fights the bed.
+- Browsers block autoplay: no voice before the first user gesture (the menu's
+  PLAY click).
+
+## Publish checklist
+
+- Load from the **URL** the command printed — permanent, nothing to commit.
+- Every generated line is WIRED and subtitled — an unwired paid line is
+  flagged at preview/publish (the wiring audit).
+- Lines are skippable/interruptible and respect the volume sliders.
+
+## Options
+
+- `--voice <cast>` — `narrator|heroine|gruff|elder|robot|imp` (default
+  `narrator`).
+- `--voice-id <id>` — any raw ElevenLabs voice id (overrides `--voice`).
+- `--no-wait` — enqueue and return immediately with the generation id; pick
+  it up later with `npx genex wait <id>` (safe to re-run — it attaches to the
+  SAME generation).
+- `--api-url <url>` — override the API base (local dev).
+
+## 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 voice generation. Tell the user the facts the CLI printed:
+  their balance, this generation's cost, and when their credits refill. Then
+  continue the build with the subtitle alone (the game must read fine silent
+  anyway) and mark the spot with `// TODO(genex): regenerate when credits refill`
+  so the real line is one command away later. Do not stop the session
+  over this.
+- **"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 line got cut off** — text past 1000 characters is clamped (the CLI
+  warns). Split long copy into separate lines — narration beats work better
+  as short lines anyway.
+- **Wrong language/accent** — the model speaks the language of the TEXT; for
+  an accent, pick a different cast voice (or a specific `--voice-id`) rather
+  than describing the accent in the text.
+- **No sound** — the `AudioContext` is suspended until a user gesture; confirm
+  the camera has an `AudioListener` and the first play comes from a
+  click/keydown.