@genex-ai/cli-demo 0.78.1-dev.203 → 0.80.0-dev.211

package/dist/index.js

@@ -287,7 +287,7 @@ async function hasGenexSkills(skillsDir) {
     return false;
   }
 }
-var REMOVED_SKILLS = ["genex-explore"];
+var REMOVED_SKILLS = ["genex-explore", "genex-threejs-skill-router"];
 async function pruneRemovedSkills(skillsDir, log) {
   const removed = [];
   for (const name of REMOVED_SKILLS) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.78.1-dev.203",
+  "version": "0.80.0-dev.211",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/README.md

@@ -17,5 +17,5 @@ command keeps them in sync with the installed CLI version automatically
 - `agents/` - example subagent definitions.
 - `commands/` - example slash commands.
 
-Start with `skills/genex-threejs-skill-router/SKILL.md` when asking your agent
+Start with `skills/genex-game-director/SKILL.md` when asking your agent
 to build or improve a 3D browser game.

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

@@ -43,10 +43,8 @@ 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. (For these approvals, use your environment's structured
-question tool when it has one — Claude Code: `AskUserQuestion`; Codex:
-`request_user_input`; if it has none, e.g. Cursor, a short numbered list in
-chat.)
+rigged and animated. (For these approvals, use your question tool when you
+have one; if you have none, a short numbered list in chat.)
 
 The high-detail pre-rig generation stays in the selected neutral A-pose. There
 is no dynamic-pose concept and no silent T-pose fallback. After the user has

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

@@ -48,14 +48,12 @@ ring) that no hand-written CSS can fake.
   semi-transparency physically cannot survive sprite extraction: a composited
   panel's pixels are a blend of panel and background, and no cutout can
   un-blend them. Plates are NEVER baked into sprites. Give the plate its
-  corners with `border-radius` or a clean `clip-path`/`mask` shape — a CSS
-  chamfer/notch is allowed, as long as the cut never clips the plate's
-  content (text, padding, a glow), leaves no jagged-edge artifacts, and
-  nothing ends up crooked — and a plain `border`/`box-shadow` won't follow a
-  `clip-path` cut, so use `$genex-threejs-game-ui`'s two-layer chamfer-border
-  recipe when a chamfer needs a frame; a genuinely ornamented angular frame is still
-  best as chrome, generated. The load-bearing `mask`/`clip-path` in this
-  skill is the masked-fill reveal below.
+  corners with `border-radius` — **never a raw `clip-path`/`mask` chamfer**
+  (it shears off borders, shadows, and content near the cut and re-breaks on
+  every padding/value change: the recurring "cut corners" defect). A genuinely
+  ornamented or angular frame belongs in chrome, generated. The one
+  load-bearing `mask`/`clip-path` in this skill is the masked-fill reveal
+  below — never corner shaping.
 - **Chrome (sprites — what THIS pipeline generates).** Opaque frames, corner
   brackets, ornaments, emblems, icons, medallions — hard-alpha art laid over
   the glass. The Stage-2 sheet contains ONLY chrome; never a panel with its
@@ -82,7 +80,7 @@ ring) that no hand-written CSS can fake.
   the container is the sprite and the content is DOM — the default split.
 - **Rule B — image vs code (the 5-minute test).** If CSS can build the
   element in under ~5 minutes without losing fidelity — flat plates, simple
-  dots/pips, plain strokes, a chamfered corner — it is CSS. If it needs
+  dots/pips, plain strokes, a rounded corner — it is CSS. If it needs
   craft (material, ornament, painterly texture), it is a sprite. One
   exception cuts the other way: a static label engraved/embossed into a
   frame's craft stays BAKED in the sprite (`baked_static` below) even
@@ -90,9 +88,10 @@ ring) that no hand-written CSS can fake.
 - **CSS-chrome recipes — the middle ground.** Between bare CSS and the full
   sprite pipeline sits brief-styled CSS chrome, right for utilitarian panels
   and secondary screens: a two-hue gradient frame (border + inset
-  box-shadow in brief hues), a clip-path chamfer (execution bar per
-  `$genex-threejs-game-ui`'s corner rules), a 9-slice-ish panel from nested
-  divs (outer div = border hue, inset div = plate hue, 2–3px reveal). What
+  box-shadow in brief hues), rounded with `border-radius` (never a raw
+  `clip-path` chamfer — see `$genex-threejs-game-ui`'s corner rules), a
+  9-slice-ish panel from nested divs (outer div = border hue, inset div =
+  plate hue, 2–3px reveal). What
   makes these legitimate: **CSS elements are styled FROM THE BRIEF — hue,
   weight, texture. Default-gray CSS anywhere on screen is a defect** (the
   classic failure: score pips shipped as unstyled "○ ●" system glyphs).
@@ -219,8 +218,16 @@ serves as the user's style checkpoint, and anchors all later art
 is frame-anchored, so it waits for the user's keep/change YES on that
 checkpoint — kick it off the instant they approve, not before.** The scene half
 of the prompt is written in TEXT from the game plan — `[GAME_SCENE]` in the
-Stage-1 template: setting, the moment, what the player is doing, lighting —
-never `--edit`-anchored to a prior image (there is none). Then write the
+Stage-1 template: setting, the moment, what the player is doing, lighting.
+**If a concept/reference image already exists — the user's own concept art, or
+a look frame you generated and they approved — anchor Stage 1 to it with
+`--edit <that-url>` so the HUD inherits its exact palette, materials, and
+lighting; that anchoring is what makes the final HUD actually match the
+concept, and skipping it is why a text-only mockup drifts.** A text-only
+Stage 1 is the fallback for when no reference exists. (To `--edit` a
+user-supplied image it must be reachable as an R2 URL — a bare chat attachment
+is not; reproduce it as a generation first, or say plainly you can't anchor to
+it rather than silently guessing.) Then write the
 widget layout and wiring code (placement, masked-fill scaffolding,
 plain-CSS placeholder bars) while it renders — the CSS HUD keeps
 the game playable until the sprites land. When a sprite lands it REPLACES
@@ -238,8 +245,9 @@ re-run from Stage 1 with their notes — cheaper than it sounds (one image
 is the whole concept now), so say so in one line and do it.
 
 ```bash
-# Stage 1 — the game CONCEPT: full HUD composited over the game's own scene,
-# described in TEXT (one generation covers concept + layout reference).
+# Stage 1 — the game CONCEPT: full HUD composited over the game's own scene.
+# TEXT-described; add `--edit <concept-url>` to anchor it to an existing
+# concept/reference image so the HUD inherits its exact style.
 # Two candidates in one call; pick the better, save its URL:
 npx genex image "<filled stage-1 prompt>" --size 2560x1440 --quality high --candidates 2
 
@@ -492,6 +500,13 @@ Two hard rules:
 
 ## Verify before calling it done
 
+**This is a gate, not a suggestion — the HUD is not "done", does not ship, and
+is not called a milestone until you have looked at it running.** The field
+failure is an agent that wires the sprites, takes one glance, notices a possible
+clip or cutoff, and ships anyway with "I'll refine if the user reports issues."
+That punt IS the defect. You are the one who verifies, not the user. If you are
+out of budget to check, say the HUD is unverified — never call it done.
+
 - **Open every extracted PNG and eyeball it** — right subject, right name.
   The reading-order sort can mismap when rows are uneven; re-run `extract`
   with corrected name order rather than regenerating anything.
@@ -502,9 +517,11 @@ Two hard rules:
   Display fonts run 25–50% wider than a naive estimate; widen the box or drop
   the weight, don't shrink the font.
 - **No widget overlaps** at the reference viewport, and none off-screen.
-- **Screenshot-check over real gameplay** — bright AND dark scenes — with
-  `$genex-threejs-visual-validation`'s capture discipline. Judge the pixels,
-  not your intent.
+- **Screenshot the running HUD and inspect it** — bright AND dark scenes —
+  with `$genex-threejs-visual-validation`'s capture discipline. **Zoom every
+  corner:** no sheared frames, no clipped/cut corners, no text truncated or
+  colliding with an edge. Judge the pixels, not your intent — skipping this is
+  exactly how the "cut corners" defect ships.
 
 ## The closing wiring audit — the pipeline's final stage, not optional
 
@@ -536,6 +553,16 @@ does not count. fillBox numbers, `segments`, and real sprite dims do not
 survive paraphrase; the canonical version of this failure is a subagent
 reporting "masks validated" while the parent ships width% fills.
 
+**Do not fire-and-forget the whole HUD/menu/logo into one background subagent.**
+The field failure: the entire production art pipeline was handed to a single
+background agent that then stalled overnight, so every preview the user played
+showed the CSS placeholder and the real HUD only landed hours later, unseen. If
+art runs in a subagent it is a BOUNDED task you wait on, then wire and verify in
+THIS session — not an overnight handoff. While the art is pending the HUD is
+unverified: do not call the game done or push it as a finished milestone. If a
+subagent stalls or misses its window, wire what landed and say plainly what is
+still placeholder — never present a placeholder HUD as the finished look.
+
 ## Cost & latency honesty
 
 A full HUD is **~9 image generations** (mockup + deconstruct + clean + a few

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

@@ -370,13 +370,14 @@ 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.
-- **1080p is the default — leave it.** The menu clip is full-screen key art,
-  the first moving thing the player sees, and 720p visibly softens it on any
-  modern display. `genex video` renders 1080p by default; pass
-  `--resolution 720p` only as an explicit cost fallback (about half the
-  credits) when the user asks to economize. The flip side of 1080p: getting
-  the phone rule above wrong now costs twice as much bandwidth — poster on
-  phone tiers, always.
+- **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.)
 - **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 =
@@ -406,9 +407,11 @@ 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) — default 1080p; `720p` is the
-  explicit cost fallback (~half the credits). Loop clips (`--loop`) ignore
-  it (that model has no resolution parameter).
+- `--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).
 - `--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

@@ -87,16 +87,22 @@ const gltf = await loadModelWithFallback(
   MODEL_URL, tier, (u) => gltfLoader.loader.loadAsync(u), { ktx2: gltfLoader.ktx2 },
 );
 const model = gltf.scene;
-// Clamp the provider's mirror-metal PBR (metalness~1 reflects the whole sky
-// env and swims with every camera move):
+// Tame ONLY the provider's mirror-metal artifact (metalness≈1 + near-zero
+// roughness mirrors the whole sky env and swims with every camera move). Do
+// NOT flatten every material to 0.6 — that was dulling legitimately metallic
+// props (gunmetal, chrome, gold, polished stone). Clamp the extreme case only;
+// leave everything else as authored.
 model.traverse((o) => {
   const m = (o as THREE.Mesh).material as THREE.MeshStandardMaterial;
-  if (m?.isMeshStandardMaterial) {
-    m.metalness = Math.min(m.metalness, 0.6);
-    m.roughness = Math.max(m.roughness, 0.35);
-    m.envMapIntensity = 0.6;
+  if (!m?.isMeshStandardMaterial) return;
+  if (m.metalness > 0.85 && m.roughness < 0.2) {
+    m.metalness = 0.7; // still reads metallic, no longer a full mirror
+    m.roughness = Math.max(m.roughness, 0.3);
   }
+  m.envMapIntensity = Math.min(m.envMapIntensity, 0.8);
 });
+// If a model that SHOULD read metallic still looks dull, this clamp is not the
+// cause — check the model against the concept and lift per-material as needed.
 model.scale.setScalar(1); // tune to taste
 model.position.set(0, 0, 0);
 scene.add(model);

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

@@ -0,0 +1,265 @@
+---
+name: genex-game-director
+description: The Genex game director — the entry point for every Genex build. Checks what your environment can do, writes the DESIGN.md design contract, routes any new-game, feature, or component request to the right Genex skills in the right order, and fans independent modules out to your sub-agents when you have them. Load first for any game work, or when unsure which skill applies.
+---
+
+# Genex Game Director
+
+Own the end-to-end outcome: a finished, playable, good-looking game — not a
+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.
+
+## 1. Check what you can do (once, before planning)
+
+Look at your own tool list and note the answers — the rest of this workflow
+uses them:
+
+- **A question tool?** Something that asks the player a structured question
+  with clickable options. If you have one, use it wherever this workflow says
+  "ask"; if not, a short numbered list in plain chat.
+- **Sub-agents?** A way to hand a scoped task to a background worker. If you
+  have them, delegation (§6) is your default for independent modules; if not,
+  do the same work yourself, in the same order — nothing else changes.
+- **A browser?** If you can open pages and take screenshots, verify visuals
+  yourself; if not, ask the player to look and tell you what they see.
+
+Never claim a capability you didn't find, and never stall because one is
+missing.
+
+## 2. Scope check — what is this?
+
+- **A new game** → the full flow: contract (§3), teams menu (§4), build order
+  (§5), delegation (§6).
+- **A feature or fix for an existing game** → read the game's `DESIGN.md` if
+  present (keep it current as you work; create a stub if it's missing and the
+  change is big), then load just the skills the
+  [routing map](references/routing-map.md) names for the touched systems.
+  Read before writing: learn the current renderer choice, physics setup, and
+  file conventions first, then extend them — don't rebuild working systems or
+  switch renderers mid-project.
+- **A component or tool** — a custom controller, a shader, an asset-pipeline
+  piece → skip the contract; route straight to the matching skills via the
+  routing map. Mostly we build games, but nothing here breaks for
+  game-adjacent work.
+
+## 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:
+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.
+
+## 4. Know your teams — what we can generate
+
+Plan the DESIGN.md Assets table from this menu. Details, flags, and approval
+steps live in each owning skill — load it when its lane fires:
+
+- `npx genex model "<prompt>"` — a real 3D thing (GLB): what you chase,
+  drive, fight → `$genex-ai-model`
+- `npx genex texture "<prompt>"` — any surface bigger than a prop
+  (`--terrain` for ground) → `$genex-ai-texture`
+- `npx genex skybox "<prompt>"` — a described 360° sky when the game is
+  outdoors → `$genex-ai-skybox`
+- `npx genex sfx "<prompt>"` — the core verb and every impact →
+  `$genex-ai-sfx`
+- `npx genex image "<prompt>"` — posters, signs, sprites, decals, HUD art
+  (`--transparent` for anything laid on a surface) → `$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 controller character|car|drone|touch|quality` and
+  `npx genex animations search "<intent>"` — ready-made, tuned movement and
+  motion; never write movement physics from scratch →
+  `$genex-threejs-character-controller`,
+  `$genex-threejs-vehicle-controllers`, `$genex-threejs-touch-controls`,
+  `$genex-threejs-adaptive-quality`
+
+Run the commands inside the project (the `@genex-ai/cli-demo` dev dependency
+makes `npx genex` resolve to the right CLI). Each prints a permanent
+`assets.genex.technology` URL you load straight from at runtime — the asset
+lives in Genex storage, not your repo, so there's nothing to commit; each
+owning `genex-ai-…` skill has the exact loader code. Prefer the procedural skills in
+the routing map for abstract/parametric/animated systems (no files, infinite
+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.
+
+**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
+`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:
+
+- 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.
+
+Skip generation only for purely abstract/geometric games. For three.js
+questions no skill covers, use the official three.js documentation
+(https://threejs.org/docs/) — the skills cover the Genex-specific parts, not
+the whole engine.
+
+## 5. Build order — the same hard floors, one owner
+
+The mandatory rows, in order, each with its one "done when" line:
+
+1. **Identity first** — load `$genex-threejs-embed-auth` unconditionally,
+   every game (multiplayer or not), before any boot code. Done when:
+   `initEmbed(...)` runs at the very top of boot and the right gate
+   (`waitForPlayer()` vs `waitForAuth()`) is wired.
+2. **Adaptive quality at boot** — `$genex-threejs-adaptive-quality`. Done
+   when: the device tier is wired at boot (tier-capped pixel ratio), the
+   governor runs in the loop, and generated skyboxes/textures load through
+   their rungs. Phones enforce a hard GPU-memory kill desktop testing never
+   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.
+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`.
+   Its countable lines live in DESIGN.md's Content section, written before
+   the asset batch (the asset set derives from it). Done when: every plural
+   noun of the request has a countable line. Shrinking one is a question to
+   the player, never a silent cut.
+5. **Route the rest** via [references/routing-map.md](references/routing-map.md):
+   the smallest useful skill set, the execution order, the visual-direction
+   gate (renderer baseline + named post stack), and the world-dressing
+   decision. Done when: DESIGN.md names the chosen skills and gates.
+6. **Multiplayer when 2+ players share a world** — `$genex-threejs-multiplayer`
+   before any networking code. Choose the net model from the experience
+   (`connect()` for one ongoing drop-in world, `matchmake()` for fresh capped
+   matches) — never ask the player to pick an SDK API. When a Play/Online
+   button exists, nothing connects before the click. A `matchmake()` game
+   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.
+
+Two rules for every game that moves (decide both before building, state them
+in DESIGN.md):
+
+- **Pointer bucket** — the bundled `FollowCamera` locks the pointer by
+  default on desktop, so this is mostly a decision to opt OUT. **Mandatory
+  pointer lock**: first-person of any kind, and any mouse-aimed action
+  (third-person shooter, FPS, sniper, turret, crosshair/reticle) — leave it
+  on. **Lock by default**: third-person free-camera action/adventure —
+  drag-orbit (`pointerLockAim: false`) only with a stated reason (e.g. a
+  cursor-heavy UI core). **Never**: cursor-core games (click-to-move, tower
+  defense, builder, card/puzzle), orbit showcases, touch-only — these MUST
+  pass `pointerLockAim: false`. Keyboard-only games (racer, platformer) lock
+  too: the cursor is either a gameplay tool or locked away during play. The
+  mechanism and the full aim contract live in
+  `$genex-threejs-camera-direction`.
+- **Input direction** — D/ArrowRight must move or turn the player
+  screen-RIGHT, mouse-right must turn the view right, drag-pan axes share one
+  convention. The screen-direction contract and verified copy-paste bases
+  live in `$genex-threejs-camera-direction` — hand-rolled steering/pan/look
+  math copies one instead of deriving signs, and the smoke check's
+  input-direction pass verifies it.
+
+## 6. Delegate — sub-agents own Modules rows
+
+If your environment has sub-agents, delegation is the DEFAULT for every
+independent DESIGN.md Modules row — not a big-game special case. If it
+doesn't, run the same rows yourself in order; the `--no-wait` generation
+pattern still hides most latency. Either way this skill is worn by the main
+agent: you stay the director.
+
+- One row = one worker = one disjoint file set. One writer per file — that
+  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.
+- 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/…`,
+  whichever this project has). A worker prompt shape that works: "You own the
+  `<row>` module of `<project>/DESIGN.md` — read it first, then read the
+  named skill files. Build ONLY the files your row owns. Generate ONLY your
+  row's assets already marked `planned` in the Assets table; anything new you
+  need, add it as a `proposed` row and say so. Report what landed and what's
+  left."
+- **The Assets table is the budget.** A worker runs generation commands only
+  for its own rows already marked `planned`; anything new it wants goes in as
+  a `proposed` row for you to approve first. An asset-shepherd lane polls
+  `npx genex wait --all` and wires + flips landed rows to `wired` — it never
+  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`.
+
+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
+`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.)
+
+Load `$genex-ai-character`, search Meshy actions first with
+`npx genex animations search "<intent>" --json`, and use returned action IDs;
+never invent IDs. Meshy limb rotations play unchanged. Never freeze hand tracks
+or apply post-mixer arm, hand, leg, or foot corrections. Only horizontal root
+or hip translation may be normalized for Rapier. In both lanes, the
+ECCTRL-derived character controller owns collision and world translation.
+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
+finds; never publish over an unacknowledged gap.
+
+## 9. Say it straight
+
+"Loaded" means you read a file. "Built" means the thing runs. "Done" means its
+"done when" line is true. Never report a skill as applied because you read it,
+an asset as wired because it generated, or a gate as passed because you meant
+to.

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

@@ -0,0 +1,148 @@
+# The design contract — DESIGN.md
+
+Write `DESIGN.md` at the game project root before any rendering code, from the
+template below. Plain game language, readable by the player, committed to the
+game's repo (it travels into remixes). It is a working document, not paperwork:
+it replaces the plan you would otherwise post only in chat, and it is the
+recovery point after any long break — sub-agents read it by path, and so do
+you when a session resumes.
+
+Rules the director enforces about this file:
+
+- Create it right after the scope check, before the concept generation; fill
+  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.
+- **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) →
+  wired`. Workers generate only their own rows already marked `planned`; new
+  wants enter as `proposed` for the main agent to approve; the asset shepherd
+  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`.
+- Shrinking any Content line is a question to the player first, never a
+  silent cut.
+
+## Template
+
+```markdown
+# <Game name> — Design
+
+_Living document — the agent keeps this current; changes land in the log at
+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>)
+
+## Core loop
+- **You do:** <primary verb — drive, shoot, build…>
+- **To:** <objective>
+- **Under pressure from:** <what pushes back>
+- **You earn:** <reward / progression>
+- **You lose when:** <fail state> → **and retry by:** <restart shape>
+
+## Content (only when the request names plural content or a content genre)
+Every plural noun from the request becomes a countable line:
+- Quests: <N>, chained by <how>
+- Locations: <named list>
+- Enemies: <N kinds, which are bosses>
+- Grows: <levels/gear/abilities> · Earn/spend: <economy>
+- Ten minutes in, I am: <one honest sentence>
+
+## Screens & UI
+Screens: <loader, menu, HUD, pause, win/lose…> · Style brief: <one line>
+References: <2–3 named games> · Menu archetype: <name>
+
+## Assets — the generation plan AND the budget
+| Asset            | Kind        | Status                          | Wired? |
+|------------------|-------------|---------------------------------|--------|
+| Concept + HUD    | image       | landed → <URL> (candidate <n>)  | n/a    |
+| <main surface>   | texture     | generating (<id>)               | —      |
+| <hero model>     | model       | planned                         | —      |
+| Menu still+video | image+video | blocked on concept yes → queued | —      |
+Status flow: proposed → planned → generating (id) → landed (URL) → wired.
+(Optionally note the prompt gist per row — it makes style-change re-rolls one
+command.)
+
+## World & scale
+<Size in numbers if open world; arena bounds otherwise. Streamed terrain? y/n>
+
+## Multiplayer
+<single-player | ongoing world (connect) | fresh matches (matchmake: quorum,
+teams, backfill…)> — and why. Play-button rule: nothing connects before the
+click (when a Play screen exists).
+
+## Modules — the build split
+| Module | Owns files | Built by | Done when |
+|---|---|---|---|
+| Boot & identity | src/main.ts, src/genex-boot.ts | main agent (only writer) | boots, tier wired, initEmbed runs |
+| 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 |
+
+## Decisions & changes
+- <date> — <one-liner per decision, including anything the player said no or
+  yes to>
+```
+
+## Filled example (a small arena shooter)
+
+```markdown
+# Rustyard — Design
+
+## Concept
+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)
+
+## Core loop
+- **You do:** skate + shoot
+- **To:** outscore three rival bots before the magnet cycle ends
+- **Under pressure from:** rivals hunting you; the pit's edges electrify as
+  the cycle counts down
+- **You earn:** scrap for hits → speed/armor pickups mid-round
+- **You lose when:** your bot breaks → **and retry by:** one key, instant
+  respawn, same round
+
+## Screens & UI
+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.
+
+## Assets
+| Asset            | Kind    | Status                     | Wired? |
+|------------------|---------|----------------------------|--------|
+| Concept + HUD    | image   | landed → <URL> (cand. 2)   | 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 | —      |
+
+## World & scale
+One 60×60 m arena, walled; no streaming.
+
+## Multiplayer
+Single-player v1 (rivals are host-free local AI). Revisit after publish.
+
+## Modules
+| Module | Owns files | Built by | Done when |
+|---|---|---|---|
+| Boot & identity | src/main.ts | main agent | boots, tier wired, initEmbed runs |
+| Arena & pickups | src/world/** | sub-agent | walkable, magnet cycle fires |
+| Rival AI | src/enemies/** | sub-agent | 3 rivals hunt + shoot |
+| HUD chain | src/ui/** | sub-agent after yes | all 5 screens live |
+
+## Decisions & changes
+- 2026-07-20 — player picked concept candidate 2; asked for "more sparks".
+- 2026-07-20 — sparks added as the ambient-motion loop, not particles-everywhere.
+```