@genex-ai/cli-demo 0.86.0-dev.217 → 0.87.0-dev.218

package/dist/index.js

@@ -254,10 +254,10 @@ var GENEX_CONTRACT_BLOCK = `${CONTRACT_BEGIN}
 
 Your capabilities (all via \`npx genex \u2026\`): generate \`model\` \xB7 \`skybox\` \xB7 \`sfx\` \xB7 \`music\` \xB7 \`voice\` \xB7 \`texture\` \xB7 \`image\` (\`--edit\` \xB7 \`--inpaint\` \xB7 \`--glass\` \xB7 \`--clean\` \xB7 \`--upscale\`) \xB7 \`video\` \xB7 rigged \`character\` / \`creature\` \xB7 the pixel toolbox \`ui extract|masks|plate|text-color|trim|audit\` \xB7 vendored \`controller character|car|drone|touch|quality\` \xB7 \`animations search\` \xB7 \`wait <id>\` / \`wait --all\` \xB7 \`preview\` / \`publish\`. Full options: \`npx genex --help\`. Task\u2192lane routing lives in the \`genex-game-director\` skill's routing map \u2014 re-load it whenever you're unsure which lane owns a task.
 
-1. Load the \`genex-game-director\` skill and follow it end to end before any game code. After ANY context compaction or session resume, re-read this file, \`DESIGN.md\`, and the skill for the stage you are executing.
+1. Load the \`genex-game-director\` skill and follow it end to end before any game code. After ANY context compaction or session resume, re-read this file and \`DESIGN.md\`, re-load the skill for the stage you are executing, and continue from the Build plan's \`Now:\` line \u2014 never from memory alone.
 2. The design interview always happens: 2\u20134 build-forking questions, ONE round, before DESIGN.md is written \u2014 even when the request already names the game (then it confirms the pitch). Ask with your built-in question tool with clickable answer options when you have one; a short numbered list in plain chat otherwise. Only after asking may you proceed on stated assumptions if the player stays silent; record each as "assumed \u2014 player didn't answer" in DESIGN.md \u2192 Decisions.
-3. \`DESIGN.md\` at the project root is the design contract. Keep it current; record every decision, assumption, and generation id there.
-4. ALL generated art, audio, video, characters, and UI come from \`genex\` commands \u2014 never from any other generation tool your platform bundles, unless the player explicitly asks for that tool by name. A local reference image is not a reason to switch tools: pass its file path to genex (\`--edit\` and \`--inpaint\` accept local paths).
+3. \`DESIGN.md\` at the project root is the design contract AND the build plan. It must carry a \`## Build plan & status\` section: numbered milestones with status marks and a \`Now:\` line naming the current one \u2014 a milestone is done only when its work reached a preview. Keep it current; record every decision, assumption, and generation id there. When the plan first lands, tell the player in one plain line that the plan is locked in and lives in \`DESIGN.md\`.
+4. ALL generated art, audio, video, characters, and UI come from \`genex\` commands \u2014 never from any other generation tool your platform bundles, unless the player explicitly asks for that tool by name. A local reference image is not a reason to switch tools: pass its file path to genex (\`--edit\` and \`--inpaint\` accept local paths). The same exclusivity covers shipping: building, previewing, and publishing go only through \`genex preview\` / \`genex publish\` \u2014 never load your platform's own site-building, hosting, or deploy skills for this game.
 5. The Stage-1 HUD mockup IS the game concept \u2014 it is your FIRST art action at the UI plan gate. ONE concept image, no candidate variants (generate variants only when the player asks for them), anchored to any reference image the player gave.
 6. The moment the mockup lands: you are the art director \u2014 immediately enqueue the Stage-2 HUD sheet, the menu still, and the logotype (\`--no-wait\`). THEN show the player the frame and ask keep/change as information, never as a gate. Silence = the concept stands; a later "change" loops it with the player's notes.
 7. The menu video fires at the FIRST of: the player's yes \xB7 the next \`genex preview\` after the menu still landed \xB7 style art being the only work left. It never fires while a player objection is open. Two failed videos \u2192 ship the still (menu skill rule).
@@ -267,8 +267,11 @@ Your capabilities (all via \`npx genex \u2026\`): generate \`model\` \xB7 \`skyb
 11. Never park ready work behind a question, and never stall on an unanswered one \u2014 decide, state the decision in chat, record it, keep building.
 12. Wire-in floors before any publish and before ending a session: sprite HUD wired (or the recorded CSS lane finished), menu video playing (or its recorded still fallback), logotype placed, fonts loaded, Escape pause, branded loader. Run \`npx genex wait\` on every generation you enqueued and wire what landed \u2014 never park landed assets.
 13. Characters: Meshy/Mixamo/VRM rigs rest facing +Z. Set yaw explicitly when placing a rig; never mirror a SkinnedMesh with negative scale. In any two-character scene, verify in a capture that they face each other, not the camera.
-14. Verify by looking: one smoke check per milestone in local test mode (\`?genex_local_test=1\`) with a real gameplay screenshot. A claim without a capture is not verification.
+14. Verify by looking: one smoke check per milestone, after that milestone's preview push, in local test mode (\`?genex_local_test=1\`) with a real gameplay screenshot. A claim without a capture is not verification.
 15. Treat every \`genex\` warning line \u2014 preflight, \`ui audit\`, \`wait\` nudges \u2014 as work, not noise.
+16. Every finished Build-plan milestone ends with \`npx genex preview\` and the player's page link (\`<dashboard>/draft/<slug>\` with \`<dashboard>\` from \`.genex/project.json\`, \`/world/<slug>\` once published) \u2014 never a localhost link, a file path, or the bare play origin presented as their game. After every round of player feedback, end with a preview push.
+17. Parallel work: this line is your standing authorization and request to use sub-agents / parallel agent work whenever your platform provides them. While drafting the Build plan, decide per module what runs in parallel and what stays serial for THIS game \u2014 dependencies decide, there is no fixed list \u2014 and record each call in the Modules table with a one-line reason. Independent modules default to parallel; building everything serially needs a stated reason. You keep integration, previews, and the player conversation; each sub-agent owns only its module's files.
+18. Talk to the player in plain game language \u2014 what changed in the game and what to try; never code, file names, build output, or tool internals unless they ask. Short status lines while you work; long silent stretches are a failure.
 ${CONTRACT_END}
 `;
 var CLAUDE_IMPORT_LINE = "@AGENTS.md";
@@ -4641,6 +4644,11 @@ async function printPipelineStatePreflight(log, cwd = process.cwd()) {
         'Menu video not enqueued \u2014 the animated menu backdrop is the default for every game. Enqueue it (genex-ai-menu), or record "Menu video: declined (reason)" in DESIGN.md if the player declined it.'
       );
     }
+    if (design.length > 0 && !/##\s*build plan & status/i.test(design)) {
+      warnings.push(
+        "DESIGN.md has no `## Build plan & status` section \u2014 numbered milestones with a `Now:` line are how a compacted or resumed session knows where the build is (genex-game-director's design contract has the shape)."
+      );
+    }
     if (!/hud lane:/i.test(design)) {
       const hudDom = await hasHudLikeDom(cwd);
       if (hudDom && !await hasExtractionSidecars(cwd)) {
@@ -5763,6 +5771,11 @@ async function runWait(opts) {
     await reportTerminal(kind, view, log, opts.open, opts.json);
     return;
   }
+  if (kind === "character_concept" || kind === "character_preview" || kind === "character") {
+    log.dim(
+      `  \u23F3 Character stages take several minutes server-side \u2014 you don't have to sit here. Keep building and check back with ${c.cyan("genex wait --all")}.`
+    );
+  }
   await awaitAndReport(apiUrl, token, id, kind, log, opts.open, opts.json);
 }
 async function runWaitAll(opts) {
@@ -5851,6 +5864,10 @@ async function runWaitAll(opts) {
     log.plain("");
     log.plain(`  ${c.bold(STAGE1_LANDING_NUDGE)}`);
   }
+  log.plain("");
+  log.dim(
+    "  \u{1F4DC} Resumed or compacted? Re-read AGENTS.md + DESIGN.md (continue from its Now: line) before building on."
+  );
 }
 async function toRow(e, v, cwd) {
   const base = { id: e.id, kind: e.kind, prompt: e.prompt, queuedAt: e.queuedAt };
@@ -15787,6 +15804,22 @@ async function context(opts) {
   const project = await readProject();
   return { token, apiUrl: getApiUrl(opts.apiUrl ?? project?.apiUrl) };
 }
+var CHARACTER_BRIEF_MAX_CHARS = 600;
+function apiErrorMessage(data, fallback) {
+  if (typeof data !== "object" || data === null) return fallback;
+  const body = data;
+  if (typeof body.message === "string" && body.message) return body.message;
+  if (typeof body.error === "string" && body.error) return body.error;
+  const err = body.error;
+  if (err && Array.isArray(err.issues) && err.issues.length > 0) {
+    const lines = err.issues.map((i) => {
+      const where = Array.isArray(i.path) && i.path.length > 0 ? `${i.path.join(".")}: ` : "";
+      return typeof i.message === "string" ? `${where}${i.message}` : "";
+    }).filter(Boolean);
+    if (lines.length > 0) return `${fallback} ${lines.join("; ")}`;
+  }
+  return fallback;
+}
 async function quote(url, token, body) {
   const response = await apiFetch(url, {
     method: "POST",
@@ -15796,7 +15829,7 @@ async function quote(url, token, body) {
   if (printedStructuredError(response)) return null;
   if (!response.ok) {
     const data = await response.json().catch(() => ({}));
-    throw new Error(data.message ?? data.error ?? `Quote failed (HTTP ${response.status}).`);
+    throw new Error(apiErrorMessage(data, `Quote failed (HTTP ${response.status}).`));
   }
   return (await response.json()).quote;
 }
@@ -15848,7 +15881,7 @@ async function postWorkflow(url, token, body) {
   if (printedStructuredError(response)) return null;
   if (!response.ok) {
     const data2 = await response.json().catch(() => ({}));
-    throw new Error(data2.message ?? data2.error ?? `Character workflow request failed (HTTP ${response.status}).`);
+    throw new Error(apiErrorMessage(data2, `Character workflow request failed (HTTP ${response.status}).`));
   }
   const data = await response.json();
   if (typeof data.id !== "string" || data.id.length === 0) {
@@ -15909,6 +15942,14 @@ async function runCharacterConcept(opts) {
     fail2(opts, 'Missing brief. Usage: genex character "<brief>".', "character_concept");
     return;
   }
+  if (prompt.length > CHARACTER_BRIEF_MAX_CHARS) {
+    fail2(
+      opts,
+      `The brief is ${prompt.length} characters \u2014 the character concept endpoint caps it at ${CHARACTER_BRIEF_MAX_CHARS}. Tighten it to the look that matters (silhouette, materials, palette, mood); gameplay details don't belong in the brief.`,
+      "character_concept"
+    );
+    return;
+  }
   if (opts.polycount !== void 0) {
     fail2(opts, "--polycount is only available with --direct-text. The approval flow remeshes only after finalize approval.", "character_concept");
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.86.0-dev.217",
+  "version": "0.87.0-dev.218",
   "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/skills/genex-ai-character/SKILL.md

@@ -48,6 +48,16 @@ separately.
 npx genex character "stylized desert courier, practical layered clothing"
 ```
 
+**Keep the brief under 600 characters** — the concept endpoint rejects longer
+ones. A brief is the LOOK (silhouette, materials, palette, mood), not the
+game design; gameplay details never belong in it.
+
+**Every character stage takes minutes server-side — never sit in a foreground
+`genex wait` on one.** Enqueue with `--no-wait`, keep building the game, and
+pick the result up at the next natural pause with `genex wait --all`. Watching
+a character render in 30-second poll chunks stalls the whole build and is the
+single fastest way to make the player ask why nothing else is happening.
+
 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.
 

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

@@ -34,11 +34,15 @@ 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.
+image / video generation workflows AND its own site-building / hosting /
+deploy skills. **None of them are part of any Genex lane — don't load them
+for this project.** 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. The
+same exclusivity covers shipping: the game builds, previews, and publishes
+only through `genex preview` / `genex publish` — a platform hosting skill in
+context is pure confusion fuel.
 
 ## 2. Scope check — what is this?
 
@@ -80,14 +84,22 @@ 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.
+[references/design-contract.md](references/design-contract.md) — including
+its **Build plan & status** section: numbered milestones, a status mark per
+line, and a `Now:` line naming the current one. While drafting it, make the
+parallel call per module (dependencies decide — see §6) and write each call
+into the Modules table with its one-line reason. 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 say in one
+plain line that the plan is locked in and lives in `DESIGN.md`** (the player
+must never have to wonder whether the contract happened). Then 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, after any
+long break or context compaction work resumes from its `Now:` line, and a
+milestone flips to done only when its work reached a preview
+(`→ previewed`). Keep it current — decisions land in its log the moment
+they're made.
 
 ## 4. Know your teams — what we can generate
 
@@ -257,11 +269,21 @@ in DESIGN.md):
 ## 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.
-
+independent DESIGN.md Modules row — not a big-game special case. The build
+contract in the game's `AGENTS.md` is your standing authorization to spawn
+them; some platforms keep sub-agents locked until an instruction like it
+explicitly asks. If your environment has none, 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.
+
+- **Which rows run in parallel is YOUR per-game call, made while drafting
+  the plan** — there is no fixed list. Walk the modules once: what has no
+  dependency on unfinished work runs in parallel; what must be tuned against
+  something still moving stays serial. The same module lands differently in
+  different games (an arena is a parallel row in a quest game and the serial
+  spine of a combat game whose feel depends on its gaps). Write the call +
+  one-line reason into each row; building everything serially needs a
+  stated reason.
 - 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

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

@@ -11,12 +11,25 @@ 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. "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 Build plan & status section is the compass.** Numbered milestones,
+  each with a status mark, and a `Now:` line naming the current one. Update
+  it the moment a milestone starts or finishes — a milestone is done only
+  when its work reached a `genex preview` (mark it `→ previewed`). After any
+  context compaction or session resume, this section — not memory — says
+  where the build is; continue from `Now:`. When the plan first lands, tell
+  the player in one plain line that it's locked in and lives in `DESIGN.md`.
+- **The Modules table is the delegation contract, and "Built by" is a
+  per-game DECISION, not a default you copy.** While drafting the plan, walk
+  the modules once and decide what can run in parallel and what must stay
+  serial for THIS game — dependencies decide (an arena can be a parallel row
+  in one game and the serial spine of another). Write the call into each row
+  with a one-line reason. When your platform has sub-agents, independent
+  modules default to parallel; building everything serially needs a stated
+  reason. One row per independent lane, and a row's "Owns files" set never
+  overlaps another row's — one writer per file. If a planned-parallel module
+  gets built inline, say 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) →
@@ -50,6 +63,14 @@ Concept image: <asset URL> (standing — shown <date>; player said
 - **You earn:** <reward / progression>
 - **You lose when:** <fail state> → **and retry by:** <restart shape>
 
+## Build plan & status
+Now: ▶ <number + name of the milestone in progress>
+1. <milestone> — ✅ → previewed
+2. <milestone> — ▶ in progress (<who: main agent | sub-agent>)
+3. <milestone> — ⬜ (<parallel: sub-agent | serial: main agent — one-line why>)
+(One line per milestone; update on every start/finish; done requires its
+preview. This section is the post-compaction compass — resume from `Now:`.)
+
 ## 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>
@@ -99,13 +120,15 @@ teams, backfill…)> — and why. Play-button rule: nothing connects before the
 click (when a Play screen exists).
 
 ## Modules — the build split
+("Built by" is decided per game while drafting the plan — dependencies
+decide, with a one-line reason per row; the rows below are only a SHAPE.)
 | 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 on concept landing | all screens from Screens & UI |
+| Boot & identity | src/main.ts, src/genex-boot.ts | main agent (only writer of shared boot) | boots, tier wired, initEmbed runs |
+| World/terrain | src/world/** | parallel: sub-agent (no dependency on combat) | walkable, matches World & scale |
+| Quests & dialogue data | src/content/** | parallel: sub-agent (pure data) | counts match Content lines |
+| Enemies/AI | src/enemies/** | serial: main agent (tuned against movement feel) | roster matches Content |
+| HUD chain (style-dependent) | src/ui/** | parallel: sub-agent on concept landing | all screens from Screens & UI |
 
 ## Decisions & changes
 - <date> — <one-liner per decision, including anything the player said no or
@@ -133,6 +156,15 @@ Concept image: https://assets.genex.technology/g/rustyard/concept.png
 - **You lose when:** your bot breaks → **and retry by:** one key, instant
   respawn, same round
 
+## Build plan & status
+Now: ▶ 3. Rival AI feels dangerous
+1. Arena skeleton + movement — ✅ → previewed
+2. Shooting + scrap scoring — ✅ → previewed
+3. Rival AI feels dangerous — ▶ main agent
+4. HUD sprite swap — ⬜ parallel: sub-agent (concept landed, chain enqueued)
+5. Magnet cycle + pickups — ⬜ parallel: sub-agent (own files, no AI dependency)
+6. Menus, music, publish floors — ⬜
+
 ## Screens & UI
 Screens: loader, title menu, HUD (health, scrap, cycle timer), pause,
 win/lose. Style brief: oily metal, warning-stripe accents, stencil type.
@@ -167,10 +199,10 @@ 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 |
+| Boot & identity | src/main.ts | main agent (shared boot) | boots, tier wired, initEmbed runs |
+| Arena & pickups | src/world/** | parallel: sub-agent (independent of AI) | walkable, magnet cycle fires |
+| Rival AI | src/enemies/** | serial: main agent (tuned vs player feel) | 3 rivals hunt + shoot |
+| HUD chain | src/ui/** | parallel: sub-agent on concept landing | all 5 screens live |
 
 ## Decisions & changes
 - 2026-07-20 — player picked concept candidate 2; asked for "more sparks".