@genex-ai/cli-demo 0.85.0-dev.216 → 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.85.0-dev.216",
+  "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/controllers/character/character-animations.ts

@@ -324,6 +324,17 @@ export interface PlayOneShotOptions {
   clamp?: boolean;
   /** Fired when the clip finishes (skipped if a newer one-shot interrupts it). */
   onDone?: () => void;
+  /**
+   * Movement cancels this one-shot. Every one-shot is FULL-BODY (there is no
+   * upper-body layering), so it freezes the legs — a moving character SLIDES
+   * across the ground in a static pose for the clip's whole length (a 2.9s hit
+   * reaction, a 2.7s cast). With `interruptible: true`, grounded movement
+   * intent releases the clip via {@link CharacterAnimations.clearOneShot} and
+   * locomotion takes over immediately. Use it for reactions and gestures a
+   * player can walk out of; leave it off for poses that must hold to their end
+   * (a death/knockdown). Default false.
+   */
+  interruptible?: boolean;
 }
 
 type MutableAnimationStateContext = {
@@ -358,6 +369,9 @@ export class CharacterAnimations {
   // When true, the active one-shot holds its final pose on finish (clamp:true —
   // e.g. Death01) instead of crossfading back to locomotion.
   #oneShotHoldPose = false;
+  // When true, grounded movement intent cancels the active one-shot (see
+  // PlayOneShotOptions.interruptible).
+  #oneShotInterruptible = false;
 
   #state: CharacterAnimationState = "IDLE";
   #prevActionName: string | null;
@@ -398,7 +412,27 @@ export class CharacterAnimations {
     options: CharacterAnimationsOptions = {}
   ) {
     this.#model = model;
-    this.#clipMap = buildClipMap(clips, options.clipMap);
+    // Seed the fuzzy name-matched map from the locomotion profile's own slots
+    // (explicit options.clipMap still wins). Simple boolean snapshots (remote
+    // players, bots) never reach the profile's directional resolver and fall
+    // through to this map — without the seed they bind DIFFERENT clips than the
+    // local player ("Running" vs the profile's run.forward), so the same
+    // movement renders as two different gaits on two screens. Jump states are
+    // deliberately NOT seeded: jump.full would one-shot-clamp as a loop.
+    const slots = options.locomotionProfile?.slots ?? {};
+    const profileSeed: Partial<Record<CharacterAnimationState, string>> = {};
+    const seedPairs: ReadonlyArray<[CharacterAnimationState, string]> = [
+      ["IDLE", "idle.default"],
+      ["WALK", "walk.forward"],
+      ["RUN", "run.forward"],
+      ["CROUCH_IDLE", "crouch.idle"],
+      ["CROUCH_MOVE", "crouch.forward"],
+    ];
+    for (const [state, slot] of seedPairs) {
+      const clip = slots[slot];
+      if (clip) profileSeed[state] = clip;
+    }
+    this.#clipMap = buildClipMap(clips, { ...profileSeed, ...options.clipMap });
     this.#resolver = options.resolver ?? resolveAnimationState;
     this.#onChange = options.onChange;
     this.#locomotionProfile = options.locomotionProfile;
@@ -542,6 +576,13 @@ export class CharacterAnimations {
     // Optional in the snapshot (older five-boolean remote-player objects).
     ctx.crouchActive = snapshot.crouchActive ?? false;
 
+    // Grounded movement cancels an interruptible one-shot — otherwise the
+    // frozen full-body pose slides across the ground for the clip's whole
+    // length. clearOneShot crossfades locomotion back in with no T-pose frame.
+    if (this.#oneShotAction && this.#oneShotInterruptible && ctx.isMoving && ctx.isOnGround) {
+      this.clearOneShot();
+    }
+
     const next = this.#resolver(ctx);
     const stateChanged = next !== this.#state;
     if (stateChanged) this.#state = next;
@@ -550,6 +591,19 @@ export class CharacterAnimations {
     // (Jump_Start/Jump_Land) finishes and unlocks, the pending loop clip must still fade in
     // even though the state did not change again. Internal guards make this a no-op otherwise.
     this.#desiredMotionName = this.#resolveLocomotionClip(snapshot, next) ?? this.#clipMap[next];
+    // Rigs whose airborne slots fall back to the SAME clip as jump.start (every
+    // Meshy rig: jump.rise/jump.fall → jump.full) never re-enter #applyTransition
+    // while airborne — the name never changes — so once the one-shot finishes the
+    // character hangs FROZEN in the jump's final frame for the rest of the fall
+    // (long drops, knockback launches). Once the held action has finished
+    // (paused+clamped), retarget sustained airtime at the idle loop so the limbs
+    // keep animating while descending.
+    if ((next === "JUMP_IDLE" || next === "JUMP_FALL") && this.#desiredMotionName !== null) {
+      const held = this.#actions.get(this.#desiredMotionName);
+      if (held && held.paused) {
+        this.#desiredMotionName = this.#resolveProfileSlot("idle.default") ?? this.#clipMap.IDLE;
+      }
+    }
     // A full-jump profile clip may outlast a very short physics hop. Release
     // its one-shot lock as soon as the controller lands so idle/walk can
     // crossfade immediately instead of waiting for the authored clip to end.
@@ -643,6 +697,7 @@ export class CharacterAnimations {
     // finish and the rig snaps to bind pose for a frame — the T-pose flash.
     action.clampWhenFinished = true;
     this.#oneShotHoldPose = options.clamp ?? false;
+    this.#oneShotInterruptible = options.interruptible ?? false;
     action.timeScale = options.timeScale ?? 1;
     action.reset();
     if (current && current !== action) {
@@ -660,6 +715,42 @@ export class CharacterAnimations {
     return true;
   }
 
+  /**
+   * Cancel a one-shot and hand control back to locomotion NOW. The case that
+   * REQUIRES it: a `clamp:true` one-shot (death/knockdown, a held wind-up)
+   * holds its final frame and keeps the locomotion lock closed FOREVER by
+   * design — so a respawn or an aborted action must explicitly release it, or
+   * the rig keeps the clamped pose while the body moves around. Safe to call
+   * at any time; a no-op when nothing is held.
+   *
+   * Call it on TRANSITIONS (respawn, revive, action aborted) — never per
+   * frame, or it cancels every in-flight reaction clip.
+   *
+   * @example
+   * // on respawn, before teleporting the body:
+   * anims.clearOneShot();
+   */
+  clearOneShot(): void {
+    if (this.#disposed) return;
+    const finished = this.#oneShotAction;
+    this.#oneShotAction = null;
+    this.#oneShotOnDone = undefined;
+    this.#oneShotHoldPose = false;
+    this.#oneShotInterruptible = false;
+    this.#canPlayNext = true;
+    // Crossfade the current state's loop in FROM the held pose — same path the
+    // "finished" handler uses, so there is no unposed/T-pose frame.
+    if (finished) this.#recoverFromOneShot(finished);
+  }
+
+  /** Clip name of the currently-playing (or clamped-held) one-shot, or null.
+   *  Lets a caller cancel a SPECIFIC one-shot (e.g. a held charge wind-up)
+   *  without clobbering whatever replaced it:
+   *  `if (anims.currentOneShotName === WINDUP_CLIP) anims.clearOneShot();` */
+  get currentOneShotName(): string | null {
+    return this.#oneShotAction?.getClip().name ?? null;
+  }
+
   /** Stop all actions, uncache clips, remove the mixer's 'finished' listener. */
   dispose(): void {
     if (this.#disposed) return;
@@ -766,9 +857,23 @@ export class CharacterAnimations {
   #releaseStuckLocks(): void {
     const prevActionName = this.#prevActionName;
     if (prevActionName === null) return;
+    // Match BOTH bindings a jump one-shot can have: the fuzzy clipMap names and
+    // the profile slots. On profile rigs the clipMap entries are usually null
+    // (no clip is literally named "jump_start"), which made this escape hatch
+    // dead code — a stuck jump lock could never self-release. The jump.land
+    // slot is ignored when it falls back to idle.default (same guard
+    // #applyTransition uses), or an idle prevAction would spuriously match.
+    const startName = this.#clipMap.JUMP_START ?? this.#resolveProfileSlot("jump.start");
+    const profileLand = this.#resolveProfileSlot("jump.land");
+    const landName =
+      this.#clipMap.JUMP_LAND ??
+      (profileLand !== this.#resolveProfileSlot("idle.default") ? profileLand : null);
+    // A manual playOneShot() lock is NOT ours to release — even when its clip
+    // happens to share a name with the jump binding (clearOneShot owns that).
+    if (this.#oneShotAction) return;
     if (
       !this.#canPlayNext &&
-      prevActionName === this.#clipMap.JUMP_START &&
+      prevActionName === startName &&
       this.#state !== "JUMP_IDLE" &&
       this.#state !== "JUMP_START"
     ) {
@@ -776,7 +881,7 @@ export class CharacterAnimations {
     }
     if (
       !this.#canPlayNext &&
-      prevActionName === this.#clipMap.JUMP_LAND &&
+      prevActionName === landName &&
       this.#state !== "IDLE" &&
       this.#state !== "JUMP_LAND"
     ) {
@@ -878,13 +983,19 @@ export class CharacterAnimations {
     snapshot: CharacterStateSnapshot,
     state: CharacterAnimationState,
   ): void {
-    if (!this.#locomotionProfile || !isAdvancedSnapshot(snapshot) || this.oneShotActive) return;
+    // Gate on a numeric moveSpeed rather than the full advanced snapshot:
+    // remote players and bots drive with simple boolean snapshots plus an
+    // estimated speed (position deltas / their own velocity), and without this
+    // they play locomotion at a flat 1.0 while the local player's clips
+    // speed-match — visibly different gaits for the same movement.
+    const speed = (snapshot as Partial<AdvancedCharacterStateSnapshot>).moveSpeed;
+    if (!this.#locomotionProfile || typeof speed !== "number" || this.oneShotActive) return;
     const band = state === "RUN" ? "run" : state === "CROUCH_MOVE" ? "crouch" : state === "WALK" ? "walk" : null;
     if (!band || !this.#prevActionName) return;
     const nominal = this.#locomotionProfile.nominalSpeed?.[band];
     if (!nominal || nominal <= 0) return;
     const limits = this.#locomotionProfile.playbackRate ?? { min: 0.75, max: 1.35 };
-    const rate = THREE.MathUtils.clamp(snapshot.moveSpeed / nominal, limits.min, limits.max);
+    const rate = THREE.MathUtils.clamp(speed / nominal, limits.min, limits.max);
     this.#actions.get(this.#prevActionName)?.setEffectiveTimeScale(rate);
   }
 }

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".

package/templates/skills/genex-threejs-character-controller/references/animations.md

@@ -257,7 +257,34 @@ addEventListener("pointerdown", () => {
 ```
 
 `options`: `fadeIn` (default 0.1 s), `timeScale`, `clamp` (hold the final pose —
-for deaths), `onDone`.
+for deaths), `interruptible` (grounded movement cancels the clip), `onDone`.
+
+**Every one-shot is FULL-BODY** (there is no upper-body layering), so it freezes
+the legs — a moving character SLIDES across the ground in a frozen pose for the
+clip's whole length. Two rules keep that from ever being visible:
+
+- **Reactions and gestures a player can walk out of get `interruptible: true`**
+  (hit flinches, casts, taunts, celebrations). Movement intent releases the clip
+  and locomotion takes over the same frame. A 2.9 s hit reaction without it
+  locks the player's animation for 2.9 s *per hit taken*.
+- **`clamp: true` holds the lock FOREVER by design** — nothing releases it
+  automatically, not even the clip ending. Every clamped one-shot needs a
+  guaranteed paired release: call `anims.clearOneShot()` on the transition out
+  (respawn, revive, action aborted). Audit every early-return on the path
+  between "clamped one-shot started" and "the replacing clip plays" — an abort
+  branch that skips the replacement strands the pose and the character slides
+  around locked until something else clears it.
+
+`anims.clearOneShot()` cancels the active one-shot and crossfades locomotion
+back in with no T-pose frame; it is safe to call when nothing is held. Call it
+on TRANSITIONS only — per-frame calls cancel every in-flight reaction clip. To
+cancel one SPECIFIC one-shot without clobbering whatever replaced it, check
+`anims.currentOneShotName` first:
+
+```ts
+// abort a held charge wind-up, but never a death pose that replaced it:
+if (anims.currentOneShotName === WINDUP_CLIP) anims.clearOneShot();
+```
 
 The 12 core clips are always available; everything else comes from
 `npx genex controller anims <selectors…>` — selectors are **tags** (install a

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -658,6 +658,25 @@ Corollary: **cap top speeds against the network, not just the physics** — an o
 crossing time should stay above ~2× the smoothing delay (~0.25 s), or receivers are reacting to
 history no matter how correct the code is.
 
+**Packed animation-flag bitfields are the sneakiest violation.** Smoothing lerps EVERY numeric
+field — there is no integer exemption — and a lerped bitfield decodes to garbage: with
+`moving=1, running=2, grounded=8`, walking is `f=9` and running is `f=11`, and the interpolation
+passes through `10`, where `10 & moving === 0` — the sprinting opponent renders as *standing
+still*. Worse, the exponential ease approaches an increasing target from below, so truncation
+reads `target - 1` for the whole approach (~1.5 s median before RUN appears; at a vsync-locked
+frame rate it can stick one ULP below the target *forever*). A field-verified failure: a
+playtester swore he was running while his opponent's screen showed him walking — both were right.
+Always drive remote animation from `stateRaw`:
+
+```js
+avatar.updateFromFlags(p.stateRaw.f ?? 0, dt);   // flags are DISCRETE — never p.state.f
+```
+
+**Reaction one-shots on remotes fire on EDGES, never per frame.** If you replay a remote's
+death/hit pose from their published `out`/`hp` state, track the previous value and act only on
+the transition — a per-frame `reset()`/`playDown()` restarts or cancels every in-flight reaction
+clip (and re-writing ghost/material flags 60×/s is pure churn).
+
 ## Shared objects (the ball, the NPC) — use `objects`, never `shared`
 
 A ball belongs to no player. Put it on `objects`: exactly one client owns it at a time (the SDK +