@genex-ai/cli-demo 0.81.0-dev.214 → 0.85.0-dev.216

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.

package/templates/skills/genex-game-director/SKILL.md

@@ -10,6 +10,12 @@ tech demo that boots. You are the director; the other Genex skills are your
 specialists. Load only the skills that change the result; never the whole
 pack by default.
 
+**After ANY context compaction or session resume**, re-read the game's
+`AGENTS.md` (the Genex build contract block), `DESIGN.md`, and the skill for
+the stage you are executing — never keep building from memory alone. A
+compaction that eats the conversation does not release you from the
+pipeline; those two files are how it comes back.
+
 ## 1. Check what you can do (once, before planning)
 
 Look at your own tool list and note the answers — the rest of this workflow
@@ -27,6 +33,13 @@ uses them:
 Never claim a capability you didn't find, and never stall because one is
 missing.
 
+One more thing to note while you're looking: your platform may bundle its own
+image / video / site generation workflows. **They are not part of any Genex
+lane.** All generated art, audio, video, characters, and UI come from `genex`
+commands, unless the player explicitly asks for another tool by name — and a
+local reference image is never a reason to switch tools: `genex image --edit`
+and `--inpaint` take a local file path directly.
+
 ## 2. Scope check — what is this?
 
 - **A new game** → the full flow: contract (§3), teams menu (§4), build order
@@ -45,10 +58,34 @@ missing.
 
 ## 3. The design contract — DESIGN.md
 
-Before rendering code, write `DESIGN.md` at the project root from
-[references/design-contract.md](references/design-contract.md). Post a short
-summary in chat (the plan-message duties from `$genex-threejs-game-ui` fold
-into this file plus that summary). The file is the single source of truth:
+**First, the design interview — before DESIGN.md is written.** Ask the
+player 2–4 build-forking questions, batched in ONE round — use your
+structured question / ask tool if your harness has one, with answer options
+for the user. Ask only what genuinely forks the build:
+
+- the one-line pitch, confirmed or corrected ("a co-op scythe hunt in a
+  ruined cathedral — right?");
+- the solo / co-op / versus shape (it decides netcode and scope);
+- scope ambition, when the request could honestly be read small or large
+  (compact arena vs. open world);
+- any real ambiguity in the request itself.
+
+Never ask about SDKs, engines, renderers, file layout, or anything
+technical — those are your decisions. **The silence fallback applies only
+AFTER the questions have been posted in chat.** A request that already names
+the game does not skip the interview — then it's the confirm-pitch round.
+Asking is never optional; waiting is: if the player is silent or has no way
+to answer, proceed on your own stated assumptions and write each one into
+DESIGN.md → Decisions as "assumed — player didn't answer"; the build never
+stalls on the interview.
+
+Then, before rendering code, write `DESIGN.md` at the project root from
+[references/design-contract.md](references/design-contract.md). The moment
+the file lands, post a 5–6 line summary of the contract in chat — pitch,
+core loop, content counts, screens, multiplayer shape, what you build
+first — and keep building immediately: the summary is information, not a
+gate (the plan-message duties from `$genex-threejs-game-ui` fold into this
+file plus that summary). The file is the single source of truth:
 sub-agents build against it, and after any long break it is how work resumes.
 Keep it current — decisions land in its log the moment they're made.
 
@@ -65,13 +102,24 @@ steps live in each owning skill — load it when its lane fires:
   outdoors → `$genex-ai-skybox`
 - `npx genex sfx "<prompt>"` — the core verb and every impact →
   `$genex-ai-sfx`
+- `npx genex music "<prompt>"` — ONE looping instrumental gameplay track
+  (~90 s default; the menu reuses it quieter; settings gets Music + SFX
+  sliders) → `$genex-ai-music`
+- `npx genex voice "<line>"` — short spoken lines: NPC barks, narrator
+  beats, tutorial VO (curated cast via `--voice`; keep lines short,
+  subtitled, skippable) → `$genex-ai-voice`
 - `npx genex image "<prompt>"` — posters, signs, sprites, decals, HUD art
-  (`--transparent` for anything laid on a surface) → `$genex-ai-image`,
+  (`--transparent` for anything laid on a surface; `--glass` for real-
+  translucency glass panels) → `$genex-ai-image`,
   `$genex-ai-hud`
-- `npx genex video "<prompt>"` — in-world screens, billboards, an animated
-  menu backdrop (`--loop` for seamless) → `$genex-ai-video`, `$genex-ai-menu`
-- `npx genex character "<prompt>"` — a custom playable humanoid (REQUIRED
-  player approvals — §7) → `$genex-ai-character`
+- `npx genex video "<prompt>"` — in-world screens and billboards (`--loop`
+  for a seamless in-world loop) → `$genex-ai-video`; the animated menu
+  backdrop is its own lane — `$genex-ai-menu`'s `--frame` flow, never `--loop`
+- `npx genex character "<prompt>"` — the game's themed character (approval
+  flow — §7) → `$genex-ai-character`
+- `npx genex creature "<desc>"` — a rigged enemy/creature in one shot
+  (biped-shaped bodies only — the creatures skill routes the rest to
+  static + procedural) → `$genex-threejs-creatures`
 - `npx genex controller character|car|drone|touch|quality` and
   `npx genex animations search "<intent>"` — ready-made, tuned movement and
   motion; never write movement physics from scratch →
@@ -89,12 +137,18 @@ variation); prefer these generators for concrete, describable, photoreal
 assets — they complement each other. Assets you didn't plan don't exist: if
 the menu has a lane this game needs, put a row in the Assets table.
 
+**No eternal `proposed`.** At every preview and publish, walk the Assets
+table and resolve every `proposed` row — promote it to `planned` (and
+enqueue it when its turn comes) or cancel it, saying which in one visible
+line ("cancelled: UI hover sfx — out of scope for v1"). A row parked at
+`proposed` across a whole session is a decision you didn't make.
+
 **Generate a core asset set by default — don't wait to be asked.** For any
 game that needs concrete objects or surfaces, decide a small core set from the
 game IDEA — and from the Content lines when there are any (locations and the
 enemy roster name the set) — and put it in the Assets table up front. This set
 is concept-INDEPENDENT (prompted from the idea, not the concept image, and it
-mostly survives a style change), so it does NOT wait on the concept yes. Each
+mostly survives a style change), so it never waits on the concept at all. Each
 `npx genex` job is an independent ~1-minute render: launch them concurrently
 in the background (`--no-wait`), scaffold the scene while they run, and wire
 each in as it lands, with a procedural placeholder until then:
@@ -102,7 +156,9 @@ each in as it lands, with a procedural placeholder until then:
 - the **hero model** the player controls or chases (`npx genex model`),
 - one key **texture** for the ground/main surface (`--terrain` for ground),
 - a **skybox** when the scene is outdoors,
-- a **sfx** or two for the core action and its feedback.
+- a **sfx** or two for the core action and its feedback,
+- one looping **music** track for the gameplay bed (`npx genex music`,
+  ~90 s; the menu reuses it at lower volume).
 
 Skip generation only for purely abstract/geometric games. For three.js
 questions no skill covers, use the official three.js documentation
@@ -124,11 +180,18 @@ The mandatory rows, in order, each with its one "done when" line:
    shows; the tier is what keeps a phone boot alive.
 3. **UI plan gate** — `$genex-threejs-game-ui`, every game: the screen
    inventory, one shared style brief, 2–3 AAA references, the menu archetype,
-   then the concept image with its full HUD already on it. Show the player
-   the picture the moment it lands and ask the keep-or-change question with
-   your question tool. Done when: the player said yes to a frame. The yes
-   gates ONLY style-dependent art — everything else keeps moving while you
-   wait.
+   then ONE concept image with its full HUD already on it (no candidate
+   variants unless the player asks). **The moment it lands: decide the HUD
+   lane (the lane beat below), enqueue the Stage-2 sheet + the menu still +
+   the logotype `--no-wait` IMMEDIATELY, and only THEN show the player the
+   frame and ask keep-or-change with your question tool — as information,
+   never as a gate.** Silence = the concept stands; a "change" answer loops
+   the concept with the player's notes and the chain re-runs from the new
+   frame (image-priced — cheap by design). Only the menu VIDEO waits, for
+   the FIRST of: the player's yes · the next `genex preview` after the menu
+   still landed · style work being the only work left — and it never fires
+   while a player objection is open. Done when: the sheet, still, and
+   logotype are enqueued and the frame is in front of the player.
 4. **Content contract when the request names plural content** — quests,
    enemies, bosses, locations, spells, items, or a content genre (an RPG, an
    adventure, an open world, a story game) — `$genex-threejs-game-content`.
@@ -148,10 +211,26 @@ The mandatory rows, in order, each with its one "done when" line:
    declares its `genex.matchmaking` block before preview. Done when: the
    model, start rule, and late-join behavior are stated in DESIGN.md and the
    netcode feel gate ran before handoff.
-7. **Ship the first playable v0 fast and preview it.** The scaffold prompt
-   owns the player-facing milestones and links — don't restate them; obey
-   them. Done when: the player has a draft link within about ten minutes of
-   the build starting.
+7. **Ship the playable v0 and preview it.** The scaffold prompt owns the
+   player-facing milestones and links — don't restate them; obey them. Done
+   when: the v0 loop is genuinely playable and the player has their draft
+   page link.
+
+**The HUD lane — the concept decides it, and DESIGN.md records it.** You
+make this call as the art director the moment the mockup lands: ornate /
+painterly / material widget chrome (carved bone, etched metal, glowing
+runes, brushed gold) → **sprites** — the `$genex-ai-hud` pipeline is
+mandatory. Chrome that is flat geometry + typography, where a CSS rebuild
+would be screenshot-indistinguishable from the mockup → **CSS allowed**,
+styled from the brief. The litmus test: would a screenshot of the CSS
+rebuild pass for the mockup at a glance? Unsure or ambiguous → sprites.
+Record it as one DESIGN.md line — `HUD lane: sprites (…)` or
+`HUD lane: CSS (…, one-line justification)` — the preview preflight checks
+for it. In BOTH lanes: micro-text (damage numbers, timers, ammo digits)
+stays HTML text in the brief's font, and no rectangular backing plates
+behind bars, digits, or icons — ever (a truly needed shaped plate comes
+from `npx genex ui plate`). Only the player may decline the generated HUD,
+and the player's explicit lane request wins in both directions.
 
 Two rules for every game that moves (decide both before building, state them
 in DESIGN.md):
@@ -187,10 +266,12 @@ agent: you stay the director.
   rule is anti-collision, never a reason to serialize work.
 - You stay the integrator and the only writer of shared files (boot, main
   loop, netcode). Workers never spawn workers — one level deep, always.
-- Concept-DEPENDENT rows (the HUD chain, style-matched art) wait for the
-  player's yes on the concept; concept-INDEPENDENT rows (world/terrain,
-  content data, enemies, asset wiring) launch immediately. Typing a big game
-  alone, line by line, is how sessions run out before the world exists.
+- Concept-DEPENDENT rows (the HUD chain, style-matched art) launch the
+  moment the concept LANDS — the Stage-2 chain enqueues immediately (§5.3);
+  only the menu video waits for its event triple. Concept-INDEPENDENT rows
+  (world/terrain, content data, enemies, asset wiring) launch immediately
+  either way. Typing a big game alone, line by line, is how sessions run
+  out before the world exists.
 - Give each worker everything by path: the `DESIGN.md` path, its Modules row,
   and the skill files it needs (skills live in this project —
   `.claude/skills/<name>/SKILL.md`, `.codex/skills/…`, or `.cursor/skills/…`,
@@ -207,36 +288,59 @@ agent: you stay the director.
   enqueues. (Whoever wires the HUD after a worker finishes follows
   `$genex-ai-hud`'s handoff rule: read the produced mask/bbox JSON from disk,
   never wire from a prose summary.)
-- Do NOT spawn workers to write extra test suites or audits — one
-  verification worker at most, running the smoke checks the scaffold prompt
-  already requires.
-
-## 7. A custom playable character (Meshy) — approvals are the product
-
-Use the existing VRM + UAL character controller by default
-(`npx genex controller character`). Use `npx genex character` when the game
-needs a custom generated humanoid or an action unavailable in UAL. Before
-generating a Meshy character, discuss two or three visual directions. When the
-user names a visual reference, inspect references before writing the concept
-prompt. Recommend a neutral A-pose for characters that will be rigged.
-
-Generate concept images first and show the actual images to the user. Do not
-start Image-to-3D until the user explicitly selects a candidate. Generate
-exactly three concepts, all neutral A-pose; never use a dynamic concept pose
-or silently fall back to T-pose. Warn that held, slung, or overlapping props
-and straps can fuse into the body or obscure limbs, and recommend separate
-gameplay props. Only after the explicit choice, run
-`npx genex character preview <concept-id> --candidate <1|2|3> --user-approved`.
+- Do NOT spawn workers to write extra test suites, audits, or verification
+  passes — the per-milestone smoke pass is yours, the director's, and it is
+  ONE pass (§8; the scaffold prompt owns the ceilings).
+- If you build a module the table planned for a sub-agent inline, say why in
+  one line in chat ("built enemies inline — the arena worker was still
+  holding the only free slot"). The table is accountability, not ceremony —
+  inline can be the right call.
+
+## 7. The game's character (Meshy) — themed by default
+
+**A themed character is the DEFAULT for any game whose protagonist is
+VISIBLE** — third-person, or first-person with co-op/remote players who see
+each other. Put its row in the Assets table up front and install the
+VRM + UAL controller (`npx genex controller character`) as the instant
+placeholder. The VRM stays the FINAL character only for games with no
+themed protagonist to sell (a generic exploration toy, a faceless solo
+first-person game — say which in one line). A capsule or hand-built
+primitive standing in for a person is never a shipped state, for the local
+player or a remote one.
+
+**The default lane has ONE user stop, and it rides the concept review.**
+When the user names a visual reference, inspect references before writing
+the concept prompt. Generate exactly three concepts, all neutral A-pose;
+never use a dynamic concept pose or silently fall back to T-pose. Warn that
+held, slung, or overlapping props and straps can fuse into the body or
+obscure limbs, and recommend separate gameplay props. Show the actual
+images in the SAME beat as the game-concept keep-or-change question — one
+review, two picks. The player's pick carries the lane end to end:
+`npx genex character preview <concept-id> --candidate <1|2|3> --user-approved`,
+then finalize below. **If the player hasn't picked by the time the
+character blocks progress (or ~10 minutes), pick the strongest candidate
+yourself, say which and why in chat, and proceed** — this auto-proceed is
+owner-ratified platform policy (2026-07-23), not an agent liberty; record
+it in DESIGN.md → Decisions ("auto-picked candidate 2 — cleanest
+silhouette; player away").
 
 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. Before rigging, ask the user to approve a separate
-10,000-face triangle remesh. The 10k remesh—not the high-detail source—is
-rigged and animated. Keep every pre-animation generation in the selected
-neutral A-pose. Wait for that explicit approval before
+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 the remesh
+proceeds on the same authorization as the pick (say it plainly: "building
+the 10,000-face rigging copy now"):
 `npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 [--animation <action-id>…]`.
-(`npx genex character "<prompt>" --direct-text` is the explicit legacy
-one-shot path, not a substitute for these approvals.)
+Keep every pre-animation generation in the selected neutral A-pose.
+
+**When the user themselves asked for a custom character** (an explicit
+custom-character request, not the game default), the ceremony is two
+separate stops and the approvals are the product: do not start Image-to-3D
+until they explicitly select a candidate, and before rigging ask them to
+approve the separate 10,000-face triangle remesh — wait for that explicit
+approval before finalize. (`npx genex character "<prompt>" --direct-text`
+is the explicit legacy one-shot path, not a substitute for these
+approvals.)
 
 Load `$genex-ai-character`, search Meshy actions first with
 `npx genex animations search "<intent>" --json`, and use returned action IDs;
@@ -248,13 +352,34 @@ Before handoff, visibly check idle, walk, run, crouch-idle, crouch-move, and
 jump — shoulders, elbows, wrists, hands, both leg cycles, and feet — and press
 every control the HUD advertises.
 
-## 8. Fresh-eyes review — before publish
-
-Take the game's current screenshots (desktop and phone sizes) and hand them,
-with DESIGN.md only, to a fresh reviewer — a sub-agent if you have one,
-otherwise re-read them yourself adversarially, looking to refute "it's done":
-untextured surfaces, a bare HUD, missing screens, Content lines not in the
-game, Assets rows never flipped to `wired`. Fix or honestly report what it
+## 8. Verification — the smoke pass's captures grow with the build
+
+The per-milestone smoke pass and its ceilings belong to the scaffold prompt
+(ONE pass per milestone, never test suites, never re-verify after cosmetic
+tweaks) — this section only defines WHAT that one pass captures once the
+relevant piece exists:
+
+- **Always:** the gameplay screenshot + the main controls responding the
+  right way (the scaffold prompt's baseline).
+- **Once the generated HUD is wired:** take the gameplay screenshot AFTER
+  taking damage once, with an enemy in frame facing the player. A full-HP
+  shot cannot show a broken meter (a painted trough hides behind a 100%
+  fill), and an enemy you never faced head-on may be looking sideways at
+  everyone.
+- **Once the menu video is wired:** watch one full loop cycle as rendered
+  (`$genex-ai-menu`'s seam check). A metadata probe can't see a seam, a
+  hidden video, or a leftover panel covering it.
+
+Judge each capture against DESIGN.md once, fix only what is visibly broken,
+and move on — the captures are eyes, not a test suite.
+
+**Fresh eyes before publish.** The pre-publish check is just the last
+milestone's pass, plus this: take the game's current screenshots (desktop
+and phone sizes) and hand them, with DESIGN.md only, to a fresh reviewer —
+a sub-agent if you have one, otherwise re-read them yourself adversarially,
+looking to refute "it's done": untextured surfaces, a bare HUD, missing
+screens, Content lines not in the game, Assets rows never flipped to
+`wired`, `proposed` rows never resolved. Fix or honestly report what it
 finds; never publish over an unacknowledged gap.
 
 ## 9. Say it straight

package/templates/skills/genex-game-director/references/design-contract.md

@@ -13,7 +13,10 @@ Rules the director enforces about this file:
   sections as decisions land and keep it current (stale is worse than short).
 - **The Modules table is the delegation contract**: one row per independent
   lane, and a row's "Owns files" set never overlaps another row's. One writer
-  per file.
+  per file. "Sub-agent when available" stays flexible — but if a
+  planned-sub-agent module gets built inline, the agent says why in one line.
+  Verification is never a module row: the milestone smoke pass belongs to the
+  director (the scaffold prompt owns its ceilings).
 - **The Assets table is the budget**: the asset list falls out of Content
   (enemies → models, an arena → a ground texture, outdoors → a skybox).
   Status flow per row: `proposed → planned → generating (id) → landed (URL) →
@@ -22,6 +25,8 @@ Rules the director enforces about this file:
   flips statuses and never enqueues. Re-rolls follow the player's notes only.
   The `Wired?` column exists because "generated but never wired in" is the
   most common way finished art gets lost — a row isn't done at `landed`.
+  And no eternal `proposed`: at every preview/publish, every `proposed` row
+  gets promoted or cancelled with one visible line — never silently parked.
 - Shrinking any Content line is a question to the player first, never a
   silent cut.
 
@@ -35,8 +40,8 @@ the bottom._
 
 ## Concept
 One paragraph: what the game is, what playing it feels like.
-Concept image: <asset URL> (candidate <n> — my pick, approved by the player
-on <date>)
+Concept image: <asset URL> (standing — shown <date>; player said
+<yes | nothing — pick stands | change → looped>)
 
 ## Core loop
 - **You do:** <primary verb — drive, shoot, build…>
@@ -56,18 +61,35 @@ Every plural noun from the request becomes a countable line:
 ## Screens & UI
 Screens: <loader, menu, HUD, pause, win/lose…> · Style brief: <one line>
 References: <2–3 named games> · Menu archetype: <name>
+HUD lane: <sprites (…) | CSS (…, one-line justification)> — mandatory line;
+the concept decides it (director §5) and the preview preflight checks for it
+Menu video: <yes (the default for every game) | declined (player's reason)>
 
 ## Assets — the generation plan AND the budget
 | Asset            | Kind        | Status                          | Wired? |
 |------------------|-------------|---------------------------------|--------|
-| Concept + HUD    | image       | landed → <URL> (candidate <n>)  | n/a    |
+| Concept + HUD    | image       | landed → <URL>                  | n/a    |
 | <main surface>   | texture     | generating (<id>)               | —      |
 | <hero model>     | model       | planned                         | —      |
-| Menu still+video | image+video | blocked on concept yes → queued | —      |
+| Background music | music       | planned (one ~90s looping track)| —      |
+| Menu still       | image       | enqueued on concept landing (<id>) | —   |
+| Menu video       | video       | waits: yes / next preview after still / style-only-left | — |
+| Logotype         | image       | enqueued on concept landing (<id>) | —   |
 Status flow: proposed → planned → generating (id) → landed (URL) → wired.
 (Optionally note the prompt gist per row — it makes style-change re-rolls one
 command.)
 
+**HUD pipeline state (sprites lane) — keep this current; it is how the
+pipeline survives a context compaction.** One row per stage with its
+generation id / output path, so a resumed session knows exactly where the
+chain stopped and what fires next:
+- Stage-1 mockup: <id → URL>
+- Stage-2 sheet: <id → URL>
+- Cleaned sheet: <id → URL>
+- Extracted sprites: <public/assets/hud/…>
+- Masks: <public/assets/hud/…-mask.png + sidecars>
+- Next stage: <what fires next, one line>
+
 ## World & scale
 <Size in numbers if open world; arena bounds otherwise. Streamed terrain? y/n>
 
@@ -83,8 +105,7 @@ click (when a Play screen exists).
 | World/terrain | src/world/** | sub-agent when available | walkable, matches World & scale |
 | Quests & dialogue data | src/content/** | sub-agent when available | counts match Content lines |
 | Enemies/AI | src/enemies/** | sub-agent when available | roster matches Content |
-| HUD chain (style-dependent) | src/ui/** | sub-agent AFTER concept yes | all screens from Screens & UI |
-| Verification | (no source files) | one sub-agent max | smoke check notes per milestone |
+| HUD chain (style-dependent) | src/ui/** | sub-agent on concept landing | all screens from Screens & UI |
 
 ## Decisions & changes
 - <date> — <one-liner per decision, including anything the player said no or
@@ -101,7 +122,7 @@ A scrap-robot arena shooter: you skate a magnetized junkyard bot around a
 crusher pit, blasting rival bots into spare parts before the magnet cycle
 pulls everything in. Fast, crunchy, thirty-second lives.
 Concept image: https://assets.genex.technology/g/rustyard/concept.png
-(candidate 2 — approved 2026-07-20)
+(standing — shown 2026-07-20; player said yes)
 
 ## Core loop
 - **You do:** skate + shoot
@@ -116,17 +137,26 @@ Concept image: https://assets.genex.technology/g/rustyard/concept.png
 Screens: loader, title menu, HUD (health, scrap, cycle timer), pause,
 win/lose. Style brief: oily metal, warning-stripe accents, stencil type.
 References: <three named AAA games>. Menu archetype: hangar pan.
+HUD lane: sprites (stencil-cut metal meters + riveted scrap counter — ornate
+material chrome, CSS can't pass for it)
+Menu video: yes
 
 ## Assets
 | Asset            | Kind    | Status                     | Wired? |
 |------------------|---------|----------------------------|--------|
-| Concept + HUD    | image   | landed → <URL> (cand. 2)   | n/a    |
+| Concept + HUD    | image   | landed → <URL>             | n/a    |
 | Junkyard ground  | texture | landed → <URL>             | yes    |
 | Player bot       | model   | generating (gen_8f2k)      | —      |
 | Rival bot        | model   | planned                    | —      |
 | Overcast sky     | skybox  | landed → <URL>             | yes    |
 | Blaster zap      | sfx     | landed → <URL>             | yes    |
-| Menu still+video | image+video | blocked on concept yes | —      |
+| Menu still       | image   | landed → <URL>             | —      |
+| Menu video       | video   | waiting (still landed — fires at yes / next preview / style-only-left) | — |
+| Logotype         | image   | generating (gen_9t3m)      | —      |
+
+HUD pipeline state: Stage-1 mockup gen_7a1x → URL · Stage-2 sheet gen_7b2y →
+URL · cleaned gen_7c3z → URL · extracted public/assets/hud/ · masks derived ·
+next: wire masked fills
 
 ## World & scale
 One 60×60 m arena, walled; no streaming.