@genex-ai/cli-demo 0.48.0-dev.80 → 0.48.0-dev.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.48.0-dev.80",
+  "version": "0.48.0-dev.89",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -128,7 +128,10 @@ scaffolding, plain-CSS placeholder bars) while it renders — the CSS HUD keeps
 the game playable until the sprites land. When the gate produced a concept
 frame, anchor Stage 1 to it — `--edit <concept-url>` holds the game's
 register far better than a text-only prompt; single-sprite regenerations
-anchor the same way. Generate 2 mockup candidates in one
+anchor the same way. The concept is a STYLE anchor only: the widget set and
+layout come from the element inventory and the game contract — a mechanic
+the concept invented (a lap counter, a stamina orb) does not enter the HUD,
+and a mechanic it failed to show still does. Generate 2 mockup candidates in one
 call (`--candidates 2`) and pick the better one: a re-roll costs the whole
 serial chain, a second candidate costs nothing extra in wall-clock.
 

package/templates/skills/genex-threejs-game-ui/SKILL.md

@@ -68,12 +68,32 @@ you're borrowing. The bar is what those games ship, not "good enough for a
 demo". Conventions only — never logos, exact layouts, or trade dress. The
 same 2–3 names carry into the router's visual-direction gate for the scene.
 Then turn references + brief into ONE **concept frame** — a single generated
-image of what THIS game should look like mid-play (scene, mood, lighting;
-a UI impression is welcome but optional):
-`npx genex image "<one-sentence game look from the brief>" --aspect 16:9 --quality high --no-wait`,
-enqueued FIRST of all art. Its URL goes into the style-brief comment as the
-game's north star: every later 2D generation that accepts `--edit` anchors
-to it, and the scene's lighting/grading is judged against it.
+image of a PLAYABLE MOMENT of this game, not key art. Build the prompt from
+the game contract, not just the mood: what the player is DOING mid-action
+(the verb), what threatens them right now (enemy silhouettes), what they
+are chasing (the objective — a finish gate, a goal, a pickup), and how the
+space reads (route, scale) — plus the brief's palette, materials, and
+light. A beautiful empty vista with nothing to fight and nowhere to go is a
+FAILED concept; so is one that invents mechanics the game doesn't have (a
+lap counter in a game without laps). `--aspect 16:9 --quality high
+--no-wait`, enqueued FIRST of all art; the URL goes into the style-brief
+comment.
+
+**Share it before building on it.** The moment the frame lands, show it to
+the user — "this is roughly how the game will look: keep it, or change
+something?" — as ONE structured question with 2–3 concrete adjustment
+options. Keep building gameplay-neutral work (scaffold, physics, netcode)
+while waiting, but do NOT anchor further art to an unapproved frame; if the
+user redirects, regenerate with their notes before the HUD mockup and menu
+frame go out.
+
+**The concept anchors STYLE, not truth.** Palette, materials, light, and
+register come from the frame; CONTENT comes from the game contract. When
+the frame lands, diff it against the contract in one visible line — what
+does this game have that the frame doesn't show (enemies? arenas? the
+finish? the pickup)? Carry those requirements in words into every later
+prompt. Where the frame contradicts gameplay, gameplay wins — never inherit
+an invented mechanic, or the absence of a real one, from a picture.
 
 **4. Ask only when genuinely ambiguous.** If the concept pins the mood (a
 "gothic horror dungeon crawler" pins it), decide and state the plan in one

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

@@ -99,7 +99,8 @@ owns the queue, roles, winner-stays, forfeit, timeout, and the win condition.
 **Choosing a preset — your own rules → `open`; a ready-made match loop → `duel`/`arena`/`teams`.**
 Presets: **open** (a room of N players — the server owns only seating/capacity/refill, you write
 everything else), **duel** (1v1 winner-stays), **arena** (N-player FFA, join-anytime), **teams**
-(balanced N-v-N), **private** (invite-code lobby). Win conditions (batteries-included presets only):
+(N-v-N with a server-owned match loop + eviction — only when you want that whole loop ready-made;
+for your own team game use `open` + the team section below), **private** (invite-code lobby). Win conditions (batteries-included presets only):
 **lastStanding** (last one alive), **firstToScore** (first to the score target), **highScoreInTime**
 (top score at the time cap), **firstToFinish** (first to finish). A round that hits the time cap
 undecided is a draw. (`open` has no win condition — it never ends a round for you.)
@@ -120,14 +121,17 @@ build teams/rounds/scoring/win-logic in game code on the primitives you already
 ```
 
 With `open`, `mm.matchmaking.status` only goes `searching`→`waiting`→`playing` (never `countdown`/
-`ended`), `players` is the live roster, and `scores`/`winnerId` stay empty — watch `players` and
-`status`, not `matchStart`/`matchEnded` (they never fire). Nobody is ever evicted. Build the rest:
+`ended`), `players` is the live roster, and `teams`/`myTeam`/`scores`/`winnerId` stay EMPTY forever
+— only the server presets fill them. Watch `players` and `status`, not `matchStart`/`matchEnded`
+(they never fire); your teams live in `shared` (mandatory section below), never in
+`mm.matchmaking.teams` — reading that empty map is how every player ends up "on one team".
+Nobody is ever evicted. Build the rest:
 
 | Want… | Do it in game code on top of `open` |
 | --- | --- |
 | Room formation & refill | Nothing — the server owns it via `minPlayers`/`maxPlayers`/`fill`. |
 | Duel (1v1) | `maxPlayers: 2, minPlayers: 2`, then start when `mm.matchmaking.players.length === 2`. |
-| Team assignment | The **host** splits `players` deterministically (sort ids, round-robin) and writes the map to `shared` (`session.shared.set('teams', …)`); everyone renders from it. Survives host migration because it lives in shared state. |
+| Team assignment | The MANDATORY team section right below this table — the **host** reconciles a balanced `id → team` map into `shared`; every client only reads it. Never computed per-client, never read from `mm.matchmaking.teams` (empty on `open`). |
 | Rounds / countdown | Host writes `{ phase, deadline }` into `shared`; clients render the countdown from the timestamp (no server clock — approximate fairness is fine at this trust tier). |
 | Scores | A host-owned entry in `shared` (or per-player state); you define what a point means. |
 | Win condition | Your code checks its own condition (you already compute the signals) and the host writes the result to `shared`. |
@@ -135,6 +139,62 @@ With `open`, `mm.matchmaking.status` only goes `searching`→`waiting`→`playin
 | Forfeit on disconnect | React to the `players` list shrinking (the SDK surfaces leaves after the reconnect grace). |
 | Spectators | A game-level role: keep a "dead"/observing player seated and just render them as a watcher. There is no server spectator concept — everyone in a room is a player. |
 
+#### Team games — the HOST assigns teams into `shared` (MANDATORY, balanced from the first frame)
+
+Any team game on `open` (1v1 on opposite sides, 2v2, N-v-N, red-vs-blue) assigns teams in GAME
+CODE — the server never will. Get this wrong and every player lands on one team and the match is
+unplayable. The non-negotiable shape: exactly ONE writer — the current host — keeps an
+`id → teamId` map in `shared`, and every client (host included) READS its own team from that map.
+The assignment is one reconciler that keeps sides balanced at all times: drop leavers, then seat
+every unassigned player on the SMALLEST team, walking the roster in sorted order. From an empty
+map that IS a round-robin split (1v1 → opposite teams, four players → 2+2), and a late joiner
+(`fill: 1`) always lands on the short-handed side. Run it in the host's fixed tick:
+
+```ts
+const TEAM_IDS = ["red", "blue"];  // your team set — three or more sides work unchanged
+
+function reconcileTeams() {        // HOST-only, every tick — cheap; writes only on change
+  if (!room.isHost) return;
+  const teams = { ...((room.shared.get("teams") ?? {}) as Record<string, string>) };
+  const roster = [...room.players.keys()].sort();           // deterministic order
+  let changed = false;
+  for (const id of Object.keys(teams))                      // 1. drop leavers
+    if (!roster.includes(id)) { delete teams[id]; changed = true; }
+  const size = (t: string) => Object.values(teams).filter((x) => x === t).length;
+  for (const id of roster) {                                // 2. newcomers → the smallest team
+    if (teams[id]) continue;
+    teams[id] = TEAM_IDS.reduce((a, b) => (size(b) < size(a) ? b : a));
+    changed = true;
+  }
+  if (changed) room.shared.set("teams", teams);             // no diff, no write (message budget)
+}
+
+// EVERY client, in the render loop — read your team, never compute it:
+const myTeam = (room.shared.get("teams") as Record<string, string> | undefined)?.[room.id] ?? null;
+if (myTeam === null) renderNeutral();                       // unassigned ≠ team red
+```
+
+The failure modes this shape exists to prevent — do NOT do any of these:
+
+- **Per-client assignment** (each client picks its own team from `players` order, join time, or
+  `Math.random()`): clients see different rosters at different moments, so they all self-assign
+  the same side. Team choice has exactly one writer — the host.
+- **Reading `mm.matchmaking.teams` / `myTeam`** — empty/`null` on `open` forever (server presets
+  only). A `myTeam ?? "red"` fallback puts EVERYONE on red.
+- **Defaulting the unassigned** (`teams[id] ?? "red"`): between joining and the host's next write
+  a player has NO team — render them neutral (or keep the lobby up), never fold them into a side.
+- **Assigning once at match start**: with `fill: 1` the queue keeps seating players mid-game; the
+  reconciler runs every tick precisely so joiner #5 lands on the 2-player side, not the 3-player one.
+- **Keeping the map anywhere but `shared`**: host-local state dies with the host's tab. In `shared`
+  the map survives host migration — the NEW host's reconciler continues from what's already there
+  (nobody's team changes; it only fills gaps).
+
+Balance beyond headcount (roles, kits, skill) stays a game decision — headcount balance via this
+reconciler is the floor every team game ships with. **Verify it like the lobby rule:** two browser
+windows on a two-team game MUST land on OPPOSITE teams (different colors, different spawn sides).
+Both on one team = broken — fix it before shipping. Full genre wiring (team spawns, friendly fire,
+team score) is Recipe 4 in [references/genre-recipes.md](references/genre-recipes.md).
+
 #### Waiting room / lobby — two patterns
 
 `open` seats you into a LIVE shared room the moment you're matched (`session` goes live, players sync)
@@ -559,6 +619,10 @@ host-driven saving works as long as ANY account is in the room.
 - [ ] Waiting room (if any): overlay driven by `mm.matchmaking.status` read every frame, gone the
       moment it flips to `'playing'` — and you WATCHED it close in two browser windows at
       `minPlayers` (never gated on `matchStart` or a host `shared` signal alone).
+- [ ] Team game: the HOST reconciles the balanced `id → team` map into `shared` (leavers dropped,
+      newcomers to the smallest team); every client READS its team from `shared` — never computed
+      per-client, never `mm.matchmaking.teams`, never a default for the unassigned — and you
+      WATCHED two browsers land on OPPOSITE teams.
 - [ ] Picked the matching recipe from [references/genre-recipes.md](references/genre-recipes.md).
 
 ## Troubleshooting auth

package/templates/skills/genex-threejs-multiplayer/references/genre-recipes.md

@@ -132,6 +132,48 @@ sees the correct wave and enemy positions.
 
 ---
 
+## Recipe 4 — Team vs team (1v1 sides, 2v2, N-v-N: team deathmatch, CTF, team football)
+
+Two (or more) sides; players on a side cooperate. The whole recipe hangs off ONE fact: **teams are
+assigned by the HOST into `shared`, balanced from the first frame** — the mandatory team section in
+SKILL.md is the assignment story, verbatim. Everything else is Recipe 1/2 mechanics filtered by team.
+
+| Thing | Channel | Authority |
+| --- | --- | --- |
+| Each player's avatar (+ `uid`, hp, `life`) | `me.set` / `players` | each player |
+| The team map (`id → red/blue`) | `shared` (`"teams"`) | the **host** — the SKILL.md reconciler, every tick |
+| Team scores | `shared` (exactly-once marker — SKILL.md host section) | `room.isHost` |
+| Attacks / defeats | `send` (Recipe 2 rules verbatim) | attacker / victim |
+| A contested ball / flag / payload | `objects` (Recipe 1 rules) | current owner |
+
+**Decisions:**
+- **Matchmaking config is only headcount:** `preset: "open"` with `maxPlayers` = team size × team
+  count, `minPlayers` = the count the game is playable at (`2` starts a 2v2 short-handed as a 1v1
+  and refills to full; `4` waits for a full lobby — pick one deliberately). The server seats
+  players; it will NEVER assign teams — that is your host code.
+- **Run the SKILL.md team reconciler in the host tick** — sorted roster + smallest-team =
+  round-robin balance, late joiners to the short side, the map in `shared` survives host
+  migration. Do not re-derive teams anywhere else, and never read `mm.matchmaking.teams` (empty
+  on `open`).
+- **Everything team-flavored READS the map:** tint/skin by `teams[id]`, spawn each player on their
+  team's side (respawn via `me.snap`), gate friendly fire in the hit-test — skip targets where
+  `teams[target] === teams[me]` before applying damage — and frame the HUD ("your team" vs
+  "enemy") from your own entry. A player not yet in the map renders neutral and takes no damage;
+  never fold them into a side.
+- **Score per TEAM, not per player:** the host turns Recipe 2's defeat events (or goals/captures)
+  into a team point with the exactly-once marker write, keyed by the team id; per-player stats can
+  ride alongside keyed by the stable `uid`.
+- **Win + rematch are host-written `shared` facts:** the host checks its own condition (first to
+  N, timer end) and writes `shared.set("result", { winner, at })`; everyone renders it. For a
+  rematch the host clears `result` and the scores — keep the team map so nobody's side flips.
+
+**Acceptance feel:** two browsers land on OPPOSITE teams instantly (the 1v1 case); a third and
+fourth joiner alternate sides (never 3v1); killing the host's tab mid-match changes nobody's team;
+the team score survives the host change; a just-joined player is neutral for a beat, then snaps to
+the short-handed side.
+
+---
+
 ## Not sure which? Start from the table
 
 Whatever the genre, ask per thing: *is it one player's own state* (`me.set`) *· a moving thing

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -25,8 +25,10 @@ Three.js release or branch, and do not blindly copy demo architecture.
    decided silently. Enqueue the Tier-2 UI generations now with `--no-wait`
    (pick them up later with `npx genex wait <id>`) — they render server-side
    while you build the game. FIRST of all art: the gate's **concept frame** —
-   the single image of the finished game's look that every later `--edit`-able
-   generation anchors to. Then the `$genex-ai-hud` Stage-1 mockup, enqueued
+   a playable-moment shot (verb + threat + objective in frame, per the
+   game-ui gate), shown to the user for a keep-or-change answer the moment
+   it lands; later `--edit`-able generations anchor to it for STYLE while
+   the game contract owns content. Then the `$genex-ai-hud` Stage-1 mockup, enqueued
    here for EVERY game; and the `$genex-ai-menu` video whenever the menu
    decision is yes (the default for every game — "it's only a draft" is not a
    reason to decide no). Skipping this enqueue is
@@ -50,8 +52,8 @@ Three.js release or branch, and do not blindly copy demo architecture.
    - **references**: name 2–3 AAA games whose look this game borrows
      (conventions, lighting mood, palette, post — never trade dress); the
      same 2–3 the UI gate named, extended from the interface to the scene,
-     and embodied in the gate's concept frame — the image the scene is
-     judged against;
+     and embodied in the gate's concept frame — the image the scene's STYLE
+     is judged against (content always comes from the game contract);
    - **ambient motion**: name ONE subtle environmental motion loop that keeps
      the scene alive at rest — an emissive pulse along edges, heat shimmer,
      drifting dust, a slowly flowing texture. Shader/procedural, zero