@jgengine/convex 0.18.1 → 0.19.0

package/dist/server.js

@@ -3,7 +3,7 @@ import { ConvexError, v } from "convex/values";
 import { validateChatMessage } from "@jgengine/core/game/chat";
 import { createFeedWriteGate, validateFeedWrite, } from "@jgengine/core/multiplayer/feedWriteGate";
 import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, isPresenceExpired, pickReusablePresence, resolveActivePresence, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
-import { commandScopeEscape, scopeWithActor } from "@jgengine/core/runtime/commandRunner";
+import { SERVER_ONLY_COMMAND_REASON, commandScopeEscape, scopeWithActor } from "@jgengine/core/runtime/commandRunner";
 import { createGameRuntime, initialPlayerState } from "@jgengine/core/runtime/gameRuntime";
 import { buildHydratePlayers, planServerPersist, shouldAutoSave, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
 import { JG_MAX_MEMBERS_PER_SERVER, isListablePublicly, isPrivateJoinBlocked, isServerFull, isServerMember, selectJoinTarget, statusAfterLeave, validateSlotsPerServer, withJoinedMember, withoutMember, } from "@jgengine/core/runtime/hostPolicy";
@@ -56,6 +56,8 @@ export function jgengineTables() {
             serverId: v.id("jgGameServers"),
             userId: v.string(),
             joinedAt: v.number(),
+            /** Live client sessions holding this membership; absent on legacy and host-driven joins. */
+            sessionIds: v.optional(v.array(v.string())),
         }).index("by_server", ["serverId"]).index("by_server_and_user", ["serverId", "userId"]),
         jgRateLimits: defineTable({
             key: v.string(), startedAt: v.number(), count: v.number(), expiresAt: v.number(),
@@ -196,6 +198,21 @@ async function hasMember(ctx, server, userId) {
     return (await ctx.db.query("jgServerMembers")
         .withIndex("by_server_and_user", q => q.eq("serverId", server._id).eq("userId", userId)).unique()) !== null;
 }
+async function memberRow(ctx, serverId, userId) {
+    return ctx.db.query("jgServerMembers").withIndex("by_server_and_user", q => q.eq("serverId", serverId).eq("userId", userId)).unique();
+}
+/** Most live client sessions one shared-topology membership remembers; the oldest drop first. */
+export const MAX_MEMBER_SESSIONS = 16;
+/** Longest accepted client `sessionId`. */
+export const MAX_SESSION_ID_LENGTH = 128;
+function withSession(sessionIds, sessionId) {
+    return [...(sessionIds ?? []).filter((id) => id !== sessionId), sessionId].slice(-MAX_MEMBER_SESSIONS);
+}
+function assertSessionId(sessionId) {
+    if (sessionId !== undefined && (sessionId.length === 0 || sessionId.length > MAX_SESSION_ID_LENGTH)) {
+        throw new ConvexError("Invalid sessionId");
+    }
+}
 async function requireServerMember(ctx, serverId, actorUserId) {
     const server = await ctx.db.get("jgGameServers", serverId);
     if (!server)
@@ -525,6 +542,145 @@ export function createGameServerFunctions(options) {
     const tickableGameIds = (options?.runtimes ?? [])
         .filter((runtime) => runtime.hasTick)
         .map((runtime) => runtime.gameId);
+    const joinAs = async (ctx, actorUserId, args, sessionId) => {
+        const now = Date.now();
+        const runtime = resolveRuntime(registry, args.gameId);
+        const save = runtime.save;
+        const slotsPerServer = hostSlotsPerServer;
+        let server = args.serverId !== undefined ? await ctx.db.get("jgGameServers", args.serverId) : null;
+        if (args.serverId !== undefined && !server) {
+            return { ok: false, reason: "closed" };
+        }
+        if (server && server.gameId !== args.gameId) {
+            return { ok: false, reason: "unauthorized" };
+        }
+        if (server?.status === "closed")
+            return { ok: false, reason: "closed" };
+        let mayCreate = true;
+        if (!server) {
+            const joinable = [];
+            for (const status of ["running", "open"]) {
+                const rows = await ctx.db
+                    .query("jgGameServers")
+                    .withIndex("by_game_and_status", (q) => q.eq("gameId", args.gameId).eq("status", status))
+                    .take(100);
+                joinable.push(...rows);
+            }
+            // Two concurrent first-joins can both see an empty list here and both insert. Convex's OCC
+            // resolves it — the loser's read set is invalidated and its mutation retries against the
+            // winner's row — so the engine adds no lock. A `HostPersistence` backend without
+            // serializable-snapshot retry must supply that guarantee itself.
+            const target = selectJoinTarget(joinable, {
+                userId: actorUserId,
+                mode: matchmaking,
+                slotsPerServer,
+            });
+            if (target.kind === "refuse")
+                return { ok: false, reason: "full" };
+            server = target.kind === "join" ? target.row : null;
+            mayCreate = target.kind === "create";
+        }
+        if (!server && mayCreate) {
+            const serverId = await ctx.db.insert("jgGameServers", {
+                gameId: args.gameId,
+                status: "running",
+                mode: args.mode,
+                modeConfig: args.modeConfig,
+                visibility: args.visibility ?? "public",
+                joinCode: args.joinCode,
+                topology: shared ? "shared" : "rooms",
+                memberCount: 0,
+                memberUserIds: [],
+                slotsPerServer,
+                save,
+                serverState: defaultServerStateForGame(args.gameId),
+                sessionPlayers: {},
+                revision: 0,
+                tickAnchorMs: now,
+                createdAt: now,
+                updatedAt: now,
+            });
+            server = await ctx.db.get("jgGameServers", serverId);
+            if (!server)
+                throw new ConvexError("Failed to create server");
+        }
+        if (!server)
+            throw new ConvexError("No joinable server");
+        // Capacity and save policy live in host options, not in the row. Without this a long-lived
+        // world keeps whatever it was created with and raising the host option silently does nothing.
+        if (server.slotsPerServer !== slotsPerServer || JSON.stringify(server.save) !== JSON.stringify(save)) {
+            await ctx.db.patch(server._id, { slotsPerServer, save, updatedAt: now });
+            const reconciled = await ctx.db.get("jgGameServers", server._id);
+            if (!reconciled)
+                throw new ConvexError("Server missing after reconcile");
+            server = reconciled;
+        }
+        if (!shared && isServerFull(server.memberUserIds, server.slotsPerServer, actorUserId)) {
+            return { ok: false, reason: "full" };
+        }
+        if (isPrivateJoinBlocked({
+            visibility: server.visibility,
+            memberUserIds: await hasMember(ctx, server, actorUserId) ? [actorUserId] : [],
+            userId: actorUserId,
+            joinCode: server.joinCode,
+            suppliedCode: args.joinCode,
+        })) {
+            return { ok: false, reason: "unauthorized" };
+        }
+        let profile = await ctx.db
+            .query("jgPlayerProfiles")
+            .withIndex("by_user_and_game", (q) => q.eq("userId", actorUserId).eq("gameId", args.gameId))
+            .unique();
+        if (shared && server.topology !== "shared") {
+            for (const userId of server.memberUserIds) {
+                const member = await ctx.db.query("jgServerMembers").withIndex("by_server_and_user", q => q.eq("serverId", server._id).eq("userId", userId)).unique();
+                if (!member)
+                    await ctx.db.insert("jgServerMembers", { serverId: server._id, userId, joinedAt: now });
+                const state = server.sessionPlayers[userId];
+                if (!state)
+                    continue;
+                const stored = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", userId).eq("gameId", server.gameId)).unique();
+                const patch = { sessionState: state.session ?? {}, sessionServerId: server._id };
+                if (stored)
+                    await ctx.db.patch(stored._id, patch);
+                else
+                    await ctx.db.insert("jgPlayerProfiles", { userId, gameId: server.gameId, playerState: state, revision: server.revision, createdAt: now, updatedAt: now, ...patch });
+            }
+            await ctx.db.patch(server._id, { topology: "shared", memberCount: server.memberUserIds.length, memberUserIds: [], sessionPlayers: {} });
+            server = (await ctx.db.get("jgGameServers", server._id));
+            profile = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", actorUserId).eq("gameId", args.gameId)).unique();
+        }
+        const isNew = profile === null;
+        const memberUserIds = withJoinedMember(server.memberUserIds, actorUserId);
+        if (shared) {
+            const capacity = await ensureServerCapacity(ctx, server);
+            const member = await memberRow(ctx, server._id, actorUserId);
+            const isMember = member !== null || server.memberUserIds.includes(actorUserId);
+            await ctx.db.patch(capacity._id, {
+                memberCount: capacity.memberCount + (isMember ? 0 : 1), status: "running", slotsPerServer,
+            });
+            if (!isMember) {
+                await ctx.db.insert("jgServerMembers", {
+                    serverId: server._id, userId: actorUserId, joinedAt: now, ...(sessionId === undefined ? {} : { sessionIds: [sessionId] }),
+                });
+            }
+            else if (member !== null && sessionId !== undefined) {
+                await ctx.db.patch(member._id, { sessionIds: withSession(member.sessionIds, sessionId) });
+            }
+            if (server.status !== "running")
+                await ctx.db.patch(server._id, { status: "running" });
+        }
+        else {
+            await ctx.db.patch(server._id, { memberUserIds, status: "running", updatedAt: now });
+        }
+        const refreshed = await ctx.db.get("jgGameServers", server._id);
+        if (!refreshed)
+            throw new ConvexError("Server missing after join");
+        let snapshot = await loadServerSnapshot(ctx, refreshed, runtime, scopeWithActor(runtime.joinScope(actorUserId, isNew), actorUserId));
+        snapshot = runtime.joinPlayer(snapshot, actorUserId, isNew, now);
+        await persistServerSnapshot(ctx, refreshed, snapshot, save);
+        return { ok: true, serverId: refreshed._id, isNew };
+    };
     const joinServer = mutation({
         args: {
             gameId: v.string(),
@@ -534,155 +690,45 @@ export function createGameServerFunctions(options) {
             visibility: v.optional(v.union(v.literal("public"), v.literal("private"))),
             joinCode: v.optional(v.string()),
             externalId: v.optional(v.string()),
+            sessionId: v.optional(v.string()),
         },
         returns: v.union(v.object({ ok: v.literal(true), serverId: v.id("jgGameServers"), isNew: v.boolean() }), v.object({ ok: v.literal(false), reason: v.union(v.literal("full"), v.literal("closed"), v.literal("unauthorized")) })),
         handler: async (ctx, args) => {
             const actorUserId = await resolveActor(ctx, args.externalId, mode);
             if (!actorUserId)
                 return { ok: false, reason: "unauthorized" };
-            const now = Date.now();
-            const runtime = resolveRuntime(registry, args.gameId);
-            const save = runtime.save;
-            const slotsPerServer = hostSlotsPerServer;
-            let server = args.serverId !== undefined ? await ctx.db.get("jgGameServers", args.serverId) : null;
-            if (args.serverId !== undefined && !server) {
-                return { ok: false, reason: "closed" };
-            }
-            if (server && server.gameId !== args.gameId) {
-                return { ok: false, reason: "unauthorized" };
-            }
-            if (server?.status === "closed")
-                return { ok: false, reason: "closed" };
-            let mayCreate = true;
-            if (!server) {
-                const joinable = [];
-                for (const status of ["running", "open"]) {
-                    const rows = await ctx.db
-                        .query("jgGameServers")
-                        .withIndex("by_game_and_status", (q) => q.eq("gameId", args.gameId).eq("status", status))
-                        .take(100);
-                    joinable.push(...rows);
-                }
-                // Two concurrent first-joins can both see an empty list here and both insert. Convex's OCC
-                // resolves it — the loser's read set is invalidated and its mutation retries against the
-                // winner's row — so the engine adds no lock. A `HostPersistence` backend without
-                // serializable-snapshot retry must supply that guarantee itself.
-                const target = selectJoinTarget(joinable, {
-                    userId: actorUserId,
-                    mode: matchmaking,
-                    slotsPerServer,
-                });
-                if (target.kind === "refuse")
-                    return { ok: false, reason: "full" };
-                server = target.kind === "join" ? target.row : null;
-                mayCreate = target.kind === "create";
-            }
-            if (!server && mayCreate) {
-                const serverId = await ctx.db.insert("jgGameServers", {
-                    gameId: args.gameId,
-                    status: "running",
-                    mode: args.mode,
-                    modeConfig: args.modeConfig,
-                    visibility: args.visibility ?? "public",
-                    joinCode: args.joinCode,
-                    topology: shared ? "shared" : "rooms",
-                    memberCount: 0,
-                    memberUserIds: [],
-                    slotsPerServer,
-                    save,
-                    serverState: defaultServerStateForGame(args.gameId),
-                    sessionPlayers: {},
-                    revision: 0,
-                    tickAnchorMs: now,
-                    createdAt: now,
-                    updatedAt: now,
-                });
-                server = await ctx.db.get("jgGameServers", serverId);
-                if (!server)
-                    throw new ConvexError("Failed to create server");
-            }
-            if (!server)
-                throw new ConvexError("No joinable server");
-            // Capacity and save policy live in host options, not in the row. Without this a long-lived
-            // world keeps whatever it was created with and raising the host option silently does nothing.
-            if (server.slotsPerServer !== slotsPerServer || JSON.stringify(server.save) !== JSON.stringify(save)) {
-                await ctx.db.patch(server._id, { slotsPerServer, save, updatedAt: now });
-                const reconciled = await ctx.db.get("jgGameServers", server._id);
-                if (!reconciled)
-                    throw new ConvexError("Server missing after reconcile");
-                server = reconciled;
-            }
-            if (!shared && isServerFull(server.memberUserIds, server.slotsPerServer, actorUserId)) {
-                return { ok: false, reason: "full" };
-            }
-            if (isPrivateJoinBlocked({
-                visibility: server.visibility,
-                memberUserIds: await hasMember(ctx, server, actorUserId) ? [actorUserId] : [],
-                userId: actorUserId,
-                joinCode: server.joinCode,
-                suppliedCode: args.joinCode,
-            })) {
-                return { ok: false, reason: "unauthorized" };
-            }
-            let profile = await ctx.db
-                .query("jgPlayerProfiles")
-                .withIndex("by_user_and_game", (q) => q.eq("userId", actorUserId).eq("gameId", args.gameId))
-                .unique();
-            if (shared && server.topology !== "shared") {
-                for (const userId of server.memberUserIds) {
-                    const member = await ctx.db.query("jgServerMembers").withIndex("by_server_and_user", q => q.eq("serverId", server._id).eq("userId", userId)).unique();
-                    if (!member)
-                        await ctx.db.insert("jgServerMembers", { serverId: server._id, userId, joinedAt: now });
-                    const state = server.sessionPlayers[userId];
-                    if (!state)
-                        continue;
-                    const stored = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", userId).eq("gameId", server.gameId)).unique();
-                    const patch = { sessionState: state.session ?? {}, sessionServerId: server._id };
-                    if (stored)
-                        await ctx.db.patch(stored._id, patch);
-                    else
-                        await ctx.db.insert("jgPlayerProfiles", { userId, gameId: server.gameId, playerState: state, revision: server.revision, createdAt: now, updatedAt: now, ...patch });
-                }
-                await ctx.db.patch(server._id, { topology: "shared", memberCount: server.memberUserIds.length, memberUserIds: [], sessionPlayers: {} });
-                server = (await ctx.db.get("jgGameServers", server._id));
-                profile = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", actorUserId).eq("gameId", args.gameId)).unique();
-            }
-            const isNew = profile === null;
-            const memberUserIds = withJoinedMember(server.memberUserIds, actorUserId);
-            if (shared) {
-                const capacity = await ensureServerCapacity(ctx, server);
-                const isMember = await hasMember(ctx, server, actorUserId);
-                await ctx.db.patch(capacity._id, {
-                    memberCount: capacity.memberCount + (isMember ? 0 : 1), status: "running", slotsPerServer,
-                });
-                if (!isMember)
-                    await ctx.db.insert("jgServerMembers", { serverId: server._id, userId: actorUserId, joinedAt: now });
-                if (server.status !== "running")
-                    await ctx.db.patch(server._id, { status: "running" });
-            }
-            else {
-                await ctx.db.patch(server._id, { memberUserIds, status: "running", updatedAt: now });
-            }
-            const refreshed = await ctx.db.get("jgGameServers", server._id);
-            if (!refreshed)
-                throw new ConvexError("Server missing after join");
-            let snapshot = await loadServerSnapshot(ctx, refreshed, runtime, scopeWithActor(runtime.joinScope(actorUserId, isNew), actorUserId));
-            snapshot = runtime.joinPlayer(snapshot, actorUserId, isNew, now);
-            await persistServerSnapshot(ctx, refreshed, snapshot, save);
-            return { ok: true, serverId: refreshed._id, isNew };
+            assertSessionId(args.sessionId);
+            const { externalId: _externalId, sessionId, ...joinArgs } = args;
+            return joinAs(ctx, actorUserId, joinArgs, sessionId);
         },
     });
     const leaveServer = mutation({
         args: {
             serverId: v.id("jgGameServers"),
             externalId: v.optional(v.string()),
+            sessionId: v.optional(v.string()),
         },
         returns: v.null(),
         handler: async (ctx, args) => {
             const actorUserId = await requireActor(ctx, args.externalId, mode);
+            assertSessionId(args.sessionId);
             const server = await requireServerMember(ctx, args.serverId, actorUserId);
             if (server === null)
                 return null;
+            if (args.sessionId !== undefined && server.topology === "shared") {
+                const member = await memberRow(ctx, server._id, actorUserId);
+                const live = member?.sessionIds ?? [];
+                // A leave for a session that is not live (a disposed join, or one trimmed by the bound) must not evict the sessions that are.
+                if (live.length > 0) {
+                    const remaining = live.filter((id) => id !== args.sessionId);
+                    if (remaining.length === live.length)
+                        return null;
+                    if (remaining.length > 0) {
+                        await ctx.db.patch(member._id, { sessionIds: remaining });
+                        return null;
+                    }
+                }
+            }
             const now = Date.now();
             const runtime = resolveRuntime(registry, server.gameId);
             // Flushes the leaver's own state before the roster drops them; nobody else's rows are touched.
@@ -718,6 +764,16 @@ export function createGameServerFunctions(options) {
         },
     });
     const helpers = {
+        async ensureJoined(ctx, args) {
+            const serverId = args.serverId;
+            if (serverId !== undefined) {
+                const server = await ctx.db.get("jgGameServers", serverId);
+                if (server && server.gameId === args.gameId && server.status !== "closed" && await hasMember(ctx, server, args.userId)) {
+                    return { ok: true, serverId: server._id, isNew: false };
+                }
+            }
+            return joinAs(ctx, args.userId, { gameId: args.gameId, serverId }, undefined);
+        },
         async ensureServer(ctx, gameId) {
             if (!shared || matchmaking !== "singleton")
                 throw new Error("ensureServer requires a shared singleton host");
@@ -738,18 +794,22 @@ export function createGameServerFunctions(options) {
             return server;
         },
         async resetPlayerProfile(ctx, serverId, userId) {
-            const server = await requireServerMember(ctx, serverId, userId);
+            const server = await ctx.db.get("jgGameServers", serverId);
             if (!server)
+                throw new ConvexError("Server not found");
+            const profile = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", userId).eq("gameId", server.gameId)).unique();
+            const member = await hasMember(ctx, server, userId);
+            // A player who left keeps a profile that host code (a scheduled wipe, an insolvency reset) must still be able to reset.
+            if (!member && profile === null)
                 throw new ConvexError("Not a member of this server");
             const state = initialPlayerState(resolveRuntime(registry, server.gameId), userId);
-            const profile = await ctx.db.query("jgPlayerProfiles").withIndex("by_user_and_game", q => q.eq("userId", userId).eq("gameId", server.gameId)).unique();
             const now = Date.now();
             const patch = { playerState: state, sessionState: state.session, sessionServerId: server._id, revision: (profile?.revision ?? 0) + 1, updatedAt: now };
             if (profile)
                 await ctx.db.patch(profile._id, patch);
             else
                 await ctx.db.insert("jgPlayerProfiles", { userId, gameId: server.gameId, createdAt: now, ...patch });
-            if (server.topology !== "shared")
+            if (server.topology !== "shared" && member)
                 await ctx.db.patch(server._id, { sessionPlayers: { ...server.sessionPlayers, [userId]: state } });
             return state;
         },
@@ -824,7 +884,13 @@ export function createGameServerFunctions(options) {
             })),
         },
         returns: v.union(v.object({ ok: v.literal(true) }), v.object({ ok: v.literal(false), reason: v.string() })),
-        handler: (ctx, args) => helpers.runCommand(ctx, { serverId: args.serverId, command: args.command, input: args.input, externalId: args.externalId }),
+        handler: async (ctx, args) => {
+            const server = await ctx.db.get("jgGameServers", args.serverId);
+            if (server !== null && resolveRuntime(registry, server.gameId).commandAccess(args.command) === "server") {
+                return { ok: false, reason: SERVER_ONLY_COMMAND_REASON };
+            }
+            return helpers.runCommand(ctx, { serverId: args.serverId, command: args.command, input: args.input, externalId: args.externalId });
+        },
     });
     const flushSave = mutation({
         args: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/convex",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Convex adapters for JGengine: game transport, presence transport, and backend wiring over @jgengine/core.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,7 +30,7 @@
     "check-types": "bun ../../scripts/check-types-preflight.ts && tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.18.1"
+    "@jgengine/core": "^0.19.0"
   },
   "peerDependencies": {
     "convex": "^1.31.2",

package/skills/ce-handoff/SKILL.md

@@ -143,7 +143,7 @@ When sufficient, return a concise orientation: objective, progress, decisions, c
 
 ## JGengine notes
 
-- Multi-session engine work often spans `docs/plans/`, GitHub issues, and stacked PRs — point at those; do not paste full plan bodies.
+- Multi-session engine work spans GitHub issues and PRs — point at those; do not paste full plan bodies.
 - Prefer `bun run agent:bootstrap --check` status, branch names, and PR links as state anchors.
 - Local parallelism uses `.claude/worktrees/`; never invent `C:\tmp\…` Codex-shared trees.
 - Durable process changes belong in skills, not only the handoff.

package/skills/jgengine/SKILL.md

@@ -5,7 +5,9 @@ description: Route game work to the smallest useful JGengine guidance set.
 
 # JGengine intake and router
 
-Read the JGengine README for package truth, commands, layering, and license — the repo-root [`README.md`](../../../README.md) in the monorepo, or [jgengine.com](https://jgengine.com) from a scaffolded consumer project (where the relative link does not resolve). This skill decides what to load; it is not an engine manual.
+This skill decides what to load; it is not an engine manual. Package map, commands, layering, and license live in the JGengine README (repo-root [`README.md`](../../../README.md) in the monorepo, [jgengine.com](https://jgengine.com) from a created project); open it when you need one of those facts.
+
+A created project installs only `jgengine`, `jgengine-editor`, `jgengine-verify`, `game-design`, and `jgengine-ui`. Run `npx jgengine skills -p --all` before loading any other domain named below. Those projects do not ship `api.md`; read exact signatures from the `.d.ts` files under `node_modules/@jgengine/<pkg>/dist/`.
 
 ## 1. Establish the target
 
@@ -20,7 +22,7 @@ Treat the pitch as a unique composition of needs, not a genre to fill in — nev
 - HUD/menu states and **custom** UI art direction (compose shipped building blocks + HudTheme; no unskinned stock face)
 - one observable completion scenario
 
-For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+Pick the dimension first: `create` defaults to a 3D world (terrain, sky, player model, editor scene); a grid, card, tile, or other board game with no 3D scene takes `create --2d` (a `board` world drawn by GameUI over `@jgengine/core/puzzle/cellGrid`). For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
 
 For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine upgrade` in the project first: it diffs installed `@jgengine/*` versions against the latest release and prints every Migrate step and Adopt-worthy addition in between (`--json` for structured output). Bump, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
 
@@ -46,9 +48,9 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
-0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
-1. Search `capabilities.md` by intent; it maps needs to imports. Outside the monorepo (or before a domain skill is even loaded), `npx jgengine find <intent>` greps every shipped capability index at once and prints the primitive + import — reach for it the moment you're tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. If you're writing a `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob, a shipped drop-in almost certainly exists (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
-2. Open `api.md` only when exact signatures or export inventory are needed.
+0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) (`combat-loop`, `loot`, `world-drops`, `click-target`, `ability-bar`, `hitscan-weapon`, `rolled-gear`, `enter-vehicle` and more); `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
+1. Search capabilities by intent; do not read `capabilities.md` top to bottom. `npx jgengine find <intent>` searches every domain's index and every recipe at once, installed or not, and prints the primitive and its import (or the recipe to open); in the monorepo, `grep -i "<intent>" .claude/skills/*/capabilities.md` does the same. Search the moment you are tempted to hand-roll a HUD window, inventory grid, paperdoll, hotkey listener, minimap, stat bar, or character motion. A `z-index`, a `keydown` for a panel, a `<div>` inventory, or a limb bob almost certainly has a shipped drop-in (`usePanels`/`PanelHost`, `InventoryGrid`, `CharacterSheet`/`Paperdoll`, `PartMotionRig`, `EntityPreview`); games own the *skin*, not the re-derivation.
+2. Open `api.md` (monorepo) or the package `.d.ts` only when exact signatures are needed; grep it, never read it whole.
 3. Open the linked reference only for a deeper recipe or trap.
 4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.