@jgengine/convex 0.18.1 → 0.21.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.21.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.21.0"
   },
   "peerDependencies": {
     "convex": "^1.31.2",

package/skills/ce-handoff/SKILL.md

@@ -25,7 +25,7 @@ Create one immutable handoff at the destination the user requested, or use the m
 ### Build the handoff
 
 1. Distill the current objective and the user's latest intent. If a focus was supplied, make it the `resume_focus`.
-2. Inspect only the workspace state needed to explain what exists now. Use JGengine project instructions already in context (`AGENTS.md` / `CLAUDE.md`, `workflow`, domain skills).
+2. Inspect only the workspace state needed to explain what exists now. Use JGengine project instructions already in context (`AGENTS.md`, `workflow`, domain skills).
 3. Point to plans, issues, commits, diffs, documentation, and relevant files instead of reproducing their contents. Prefer repository-relative paths (`docs/plans/…`, `packages/…`, `Games/…`).
 4. Redact secrets, credentials, tokens, and unrelated personal information. Preserve operational paths only when the next agent needs them.
 5. Write or publish with existing tools. If the user named another path, folder, format, or publication destination, honor it. Do not also create a managed-store copy unless asked.
@@ -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,25 @@ 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/`.
+
+Created projects pin their scaffolding CLI as a local devDependency, separately from SDK versions. Run `npx jgengine doctor` after SDK upgrades to check CLI compatibility. Skill installation preserves newer or differing unversioned copies; update the project CLI first, and use `skills -p --force` only when replacement is intended. Each packaged skill install records its CLI and SDK versions in `.jgengine-version.json`.
+
+## Framework-first decisions
+
+For every requested interaction, feature, fix or visual change, follow the boundary in
+[AGENTS.md](../../../AGENTS.md): discover the installed
+capability, adopt it, or improve its shared owner before adding reusable game-local code.
+Games keep unique rules, content, assets and presentation. Custom markup is not a reason
+to copy focus handling, input tracking, storage or model lifecycle.
+
+Check installed versions before recreating an upstream fix. A published upgrade may
+replace a workaround; a beta merge does not update consumers. In the games workspace,
+the root catalog owns SDK versions. After adoption, remove superseded local machinery
+and verify the actual game. Outside these repositories, report missing SDK contracts
+upstream rather than treating a local engine implementation as the finished solution.
 
 ## 1. Establish the target
 
@@ -20,10 +38,14 @@ 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.
 
+`doctor` and `upgrade` resolve Bun `catalog:` and `catalog:<name>` declarations from the nearest workspace's `workspaces.catalog` or `workspaces.catalogs`, and follow hoisted SDK installs. Missing or malformed catalog entries fail diagnostics. `upgrade` is read-only by default. For catalog-owned versions, run `upgrade --plan --to <published-version>` at the workspace root or in a game, review the whole root catalog plan and migrations, then run `upgrade --apply --to <published-version>`. Apply preserves per-game `catalog:` declarations, unrelated text, CLI/github versions, and a held editor override; it verifies published SDK targets and refuses files changed while planning. Apply changes declarations only: run `bun install` at the root, then `jgengine doctor --workspace --json` once there to check installed SDK identities across declared workspace owners. Rebuild, migrate, and verify game behavior afterward. `--json` includes exact before/after text; an apply prints its plan before writing and reports write status on stderr. A report without installed packages labels its resolved pins as a declared baseline.
+
+When a linked consumer renders differently despite matching root SDK versions, `doctor` checks direct consumers and SDK dependency/peer paths, including private copies with the same version. Review the reported importer and real paths, align the shared catalog and linked-consumer declarations, then reinstall at the root and rerun `doctor --workspace`; a root install may leave private linked-package installs intact. Restart running games after reinstall. Workspace mode checks installed identities only, reports coverage, and refuses unsupported patterns, escaped symlinks or exhausted traversal budgets. The default project audit stays scoped; neither mode covers custom bundler aliases or indirect non-SDK chains.
+
 ## 2. Select domains
 
 Load only rows the target needs. Do not preload every domain.
@@ -46,13 +68,13 @@ 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); agents can use `--json --limit 5` for ranked imports and recipes with total, partial-match, and truncation fields. In the monorepo, `rg -i "<intent>" .claude/skills/*/capabilities.md` does the same search. 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.
 
-If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.
+If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter and a reviewed consumer cleanup; coordinate a differently composed second consumer when applicable. Recipes wire SDK APIs, not copied implementations. If editor-owned content cannot be expressed, file the editor gap first; track any fallback and its removal path.
 
 ## 4. Build and finish