@jgengine/convex 0.49.1 → 0.51.0

package/dist/server.js

@@ -1,8 +1,9 @@
 import { defineSchema, defineTable, internalMutationGeneric, mutationGeneric, queryGeneric, } from "convex/server";
 import { ConvexError, v } from "convex/values";
 import { validateChatMessage } from "@jgengine/core/chat/chat";
+import { definedOnly } from "@jgengine/core/data/definedOnly";
 import { createFeedWriteGate, validateFeedWrite, } from "@jgengine/core/multiplayer/feedWriteGate";
-import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, isPresenceExpired, pickReusablePresence, resolveActivePresence, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
+import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, isPresenceExpired, pickReusablePresence, resolveActivePresence, shouldPersistWorldSnapshot, spawnPresenceState, } from "@jgengine/core/multiplayer/presenceModel";
 import { SERVER_ONLY_COMMAND_REASON, commandScopeEscape, scopeWithActor } from "@jgengine/core/commands/commandRunner";
 import { createGameRuntime, initialPlayerState } from "@jgengine/core/runtime/gameRuntime";
 import { buildHydratePlayers, planServerPersist, shouldAutoSave, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
@@ -298,10 +299,10 @@ async function ensureServerCapacity(ctx, server) {
     const existing = await serverCapacity(ctx, server);
     if (existing)
         return existing;
-    const id = await ctx.db.insert("jgServerCapacity", {
+    const id = await ctx.db.insert("jgServerCapacity", definedOnly({
         serverId: server._id, gameId: server.gameId, status: server.status, mode: server.mode,
         memberCount: server.memberCount ?? server.memberUserIds.length, slotsPerServer: server.slotsPerServer,
-    });
+    }));
     return (await ctx.db.get("jgServerCapacity", id));
 }
 /**
@@ -387,7 +388,7 @@ export async function applyLeaderboardIncrements(ctx, gameId, entries) {
             await ctx.db.patch(existing._id, { value: existing.value + entry.by, updatedAt: now });
         }
         else {
-            await ctx.db.insert("jgLeaderboardRows", {
+            await ctx.db.insert("jgLeaderboardRows", definedOnly({
                 gameId,
                 stat: entry.stat,
                 scope: entry.scope,
@@ -395,7 +396,7 @@ export async function applyLeaderboardIncrements(ctx, gameId, entries) {
                 userId: entry.userId,
                 value: entry.by,
                 updatedAt: now,
-            });
+            }));
         }
     }
 }
@@ -475,7 +476,8 @@ export async function persistServerSnapshot(ctx, server, snapshot, save) {
             await ctx.db.insert("jgWorldChunks", {
                 serverId: server._id,
                 chunkKey: chunk.chunkKey,
-                ...chunkPatch,
+                snapshot: chunk.snapshot,
+                updatedAt: chunk.updatedAt,
             });
         }
     }
@@ -582,10 +584,10 @@ export function createGameServerFunctions(options) {
             const serverId = await ctx.db.insert("jgGameServers", {
                 gameId: args.gameId,
                 status: "running",
-                mode: args.mode,
+                ...(args.mode === undefined ? {} : { mode: args.mode }),
                 modeConfig: args.modeConfig,
                 visibility: args.visibility ?? "public",
-                joinCode: args.joinCode,
+                ...(args.joinCode === undefined ? {} : { joinCode: args.joinCode }),
                 topology: shared ? "shared" : "rooms",
                 memberCount: 0,
                 memberUserIds: [],
@@ -772,14 +774,22 @@ export function createGameServerFunctions(options) {
             }
             return joinAs(ctx, args.userId, { gameId: args.gameId, serverId }, undefined);
         },
-        async ensureServer(ctx, gameId) {
+        async findServer(ctx, gameId) {
             if (!shared || matchmaking !== "singleton")
-                throw new Error("ensureServer requires a shared singleton host");
+                throw new Error("findServer requires a shared singleton host");
             for (const status of ["running", "open"]) {
                 const existing = await ctx.db.query("jgGameServers").withIndex("by_game_and_status", q => q.eq("gameId", gameId).eq("status", status)).first();
                 if (existing)
                     return existing;
             }
+            return null;
+        },
+        async ensureServer(ctx, gameId) {
+            if (!shared || matchmaking !== "singleton")
+                throw new Error("ensureServer requires a shared singleton host");
+            const existing = await helpers.findServer(ctx, gameId);
+            if (existing)
+                return existing;
             const runtime = resolveRuntime(registry, gameId);
             const now = Date.now();
             const id = await ctx.db.insert("jgGameServers", {
@@ -930,7 +940,7 @@ export function createGameServerFunctions(options) {
                 _id: server._id,
                 gameId: server.gameId,
                 status: server.status,
-                mode: server.mode,
+                ...(server.mode === undefined ? {} : { mode: server.mode }),
                 memberUserIds: server.memberUserIds,
                 slotsPerServer: server.slotsPerServer,
                 save: server.save,
@@ -958,7 +968,7 @@ export function createGameServerFunctions(options) {
             memberCount: v.number(),
             slotsPerServer: v.number(),
         }), v.null()),
-        handler: (ctx, args) => withMember(ctx, mode, args, null, async (server) => ({
+        handler: (ctx, args) => withMember(ctx, mode, args, null, async (server) => definedOnly({
             _id: server._id,
             gameId: server.gameId,
             status: server.status,
@@ -983,10 +993,10 @@ export function createGameServerFunctions(options) {
                 const member = await ctx.db.query("jgServerMembers").withIndex("by_server_and_user", q => q.eq("serverId", args.serverId).eq("userId", actor)).unique();
                 if (!member)
                     return null;
-                return { _id: capacity.serverId, gameId: capacity.gameId, status: capacity.status, mode: capacity.mode, memberCount: capacity.memberCount, slotsPerServer: capacity.slotsPerServer };
+                return definedOnly({ _id: capacity.serverId, gameId: capacity.gameId, status: capacity.status, mode: capacity.mode, memberCount: capacity.memberCount, slotsPerServer: capacity.slotsPerServer });
             }
             const server = await requireServerMember(ctx, args.serverId, actor);
-            return server ? { _id: server._id, gameId: server.gameId, status: server.status, mode: server.mode, memberCount: server.memberUserIds.length, slotsPerServer: server.slotsPerServer } : null;
+            return server ? definedOnly({ _id: server._id, gameId: server.gameId, status: server.status, mode: server.mode, memberCount: server.memberUserIds.length, slotsPerServer: server.slotsPerServer }) : null;
         },
     });
     /**
@@ -1125,7 +1135,7 @@ export function createGameServerFunctions(options) {
             return Promise.all(rows
                 .filter((row) => isListablePublicly(row.visibility))
                 .slice(0, limit)
-                .map(async (row) => ({
+                .map(async (row) => definedOnly({
                 _id: row._id,
                 status: row.status,
                 memberCount: (await serverCapacity(ctx, row))?.memberCount ?? row.memberCount ?? row.memberUserIds.length,
@@ -1285,6 +1295,10 @@ export function createLeaderboardFunctions(options) {
  */
 export function createPresenceFunctions(options) {
     const mode = options?.auth ?? "required";
+    const checkpointIntervalMs = options?.checkpoint?.intervalMs ?? 30_000;
+    if (!Number.isFinite(checkpointIntervalMs) || checkpointIntervalMs < 0)
+        throw new Error("Invalid presence checkpoint interval");
+    const checkpointOf = (row) => definedOnly({ userId: row.userId, homeGameId: row.homeGameId, position: { x: row.x, y: row.y, z: row.z }, rotationY: row.rotationY });
     const freshWindowMs = options?.freshWindowMs ?? 10_000;
     const idleCutoffMs = options?.idleCutoffMs ?? 60_000;
     const maxReapPerRun = options?.maxReapPerRun ?? 256;
@@ -1327,7 +1341,7 @@ export function createPresenceFunctions(options) {
                 }
                 return rows
                     .filter((row) => row.revokedAt === undefined && row.updatedAt >= threshold)
-                    .map((row) => ({
+                    .map((row) => definedOnly({
                     userId: row.userId,
                     sessionId: row.sessionId,
                     kind: row.kind,
@@ -1410,9 +1424,15 @@ export function createPresenceFunctions(options) {
                 ...(args.label === undefined ? {} : { label: args.label }),
             };
             const displaced = existing?.revokedAt !== undefined;
+            const checkpoint = options?.checkpoint !== undefined
+                && shouldPersistWorldSnapshot(existing?.lastWorldSnapshotAt, now, checkpointIntervalMs);
+            if (checkpoint) {
+                await options?.checkpoint?.write(ctx, checkpointOf({ userId: actorUserId, homeGameId: existing?.homeGameId, ...pose }), now);
+            }
+            const stamp = checkpoint ? { lastWorldSnapshotAt: now } : {};
             if (existing) {
-                if (decision.changed || decision.refreshKeepAlive || displaced || Object.keys(identity).length > 0) {
-                    await ctx.db.patch(existing._id, { ...pose, ...identity, chunkKey: chunkKeyAt([pose.x, pose.y, pose.z]), updatedAt: now, revokedAt: undefined });
+                if (decision.changed || decision.refreshKeepAlive || displaced || checkpoint || Object.keys(identity).length > 0) {
+                    await ctx.db.patch(existing._id, { ...pose, ...identity, ...stamp, chunkKey: chunkKeyAt([pose.x, pose.y, pose.z]), updatedAt: now, revokedAt: undefined });
                 }
             }
             else {
@@ -1422,6 +1442,7 @@ export function createPresenceFunctions(options) {
                     ...pose,
                     chunkKey: chunkKeyAt([pose.x, pose.y, pose.z]),
                     ...identity,
+                    ...stamp,
                     updatedAt: now,
                 });
             }
@@ -1454,8 +1475,10 @@ export function createPresenceFunctions(options) {
             for (const row of rows) {
                 if (args.sessionId !== undefined && row.sessionId !== args.sessionId)
                     continue;
-                if (row.revokedAt === undefined)
-                    await ctx.db.patch(row._id, { revokedAt: now });
+                if (row.revokedAt !== undefined)
+                    continue;
+                await options?.checkpoint?.write(ctx, checkpointOf(row), now);
+                await ctx.db.patch(row._id, { revokedAt: now });
             }
             return null;
         },
@@ -1550,7 +1573,7 @@ export async function sendChatMessage(ctx, args) {
     const gate = await rateLimit(ctx, { key: JSON.stringify(["chat", args.serverId, args.userId]), windowMs: args.minIntervalMs ?? 2000, max: 1 });
     if (!gate.ok)
         return { ok: false, reason: "rate_limited" };
-    await ctx.db.insert("jgChatMessages", { serverId: args.serverId, channelId: args.channelId ?? "global", userId: args.userId, body: validation.text, authorName: args.authorName, at: Date.now() });
+    await ctx.db.insert("jgChatMessages", definedOnly({ serverId: args.serverId, channelId: args.channelId ?? "global", userId: args.userId, body: validation.text, authorName: args.authorName, at: Date.now() }));
     return { ok: true };
 }
 /**
@@ -1620,6 +1643,7 @@ export function createChatFunctions(options) {
             id: v.string(),
             channelId: v.string(),
             fromUserId: v.string(),
+            fromLabel: v.optional(v.string()),
             body: v.string(),
             at: v.number(),
         })),
@@ -1632,10 +1656,11 @@ export function createChatFunctions(options) {
             return rows
                 .slice()
                 .reverse()
-                .map((row) => ({
+                .map((row) => definedOnly({
                 id: row._id,
                 channelId: row.channelId,
                 fromUserId: row.userId,
+                fromLabel: row.authorName,
                 body: row.body,
                 at: row.at,
             }));
@@ -1664,8 +1689,8 @@ export function createChatFunctions(options) {
                 .withIndex("by_server_channel", (q) => q.eq("serverId", args.serverId).eq("channelId", args.channelId))
                 .order("desc")
                 .take(historyLimit * 2 + 16);
-            for (let i = historyLimit * 2; i < recent.length; i += 1) {
-                await ctx.db.delete(recent[i]._id);
+            for (const stale of recent.slice(historyLimit * 2)) {
+                await ctx.db.delete(stale._id);
             }
             return { ok: true };
         },

package/dist/worldPresence.d.ts

@@ -18,7 +18,7 @@ export interface WorldPresenceRecord extends PresenceResidentRow {
     rotationY: number;
     rotationPitch: number;
     lastSeenAt: number;
-    lastWorldSnapshotAt?: number;
+    lastWorldSnapshotAt?: number | undefined;
 }
 /** World chunk size and host-owned pose, checkpoint and retention policies. */
 export interface WorldPresenceOptions {

package/dist/worldPresence.js

@@ -1,3 +1,4 @@
+import { definedOnly } from "@jgengine/core/data/definedOnly";
 import { DEFAULT_POSE_SYNC_RULES, decidePoseSync, shouldPersistWorldSnapshot } from "@jgengine/core/multiplayer/presenceModel";
 import { chunkKeyAt, chunkKeysAround, parseChunkKey, DEFAULT_CHUNK_SIZE } from "@jgengine/core/runtime/worldChunks";
 function record(row) {
@@ -47,7 +48,7 @@ export function createWorldPresenceStore(options = {}) {
                 label: args.label ?? existing?.label, x: args.position.x, y: args.position.y, z: args.position.z,
                 rotationY: 0, rotationPitch: 0, chunkKey: chunkKeyAt([args.position.x, args.position.y, args.position.z], size),
                 updatedAt: nowMs, revokedAt: undefined };
-            const id = existing ? existing._id : await ctx.db.insert("jgPoses", patch);
+            const id = existing ? existing._id : await ctx.db.insert("jgPoses", definedOnly(patch));
             if (existing)
                 await ctx.db.patch(id, patch);
             return record((await ctx.db.get("jgPoses", id)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/convex",
-  "version": "0.49.1",
+  "version": "0.51.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": "tsgo --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@jgengine/core": "^0.49.1"
+    "@jgengine/core": "^0.51.0"
   },
   "peerDependencies": {
     "convex": "^1.31.2",

package/skills/jgengine/SKILL.md

@@ -3,82 +3,62 @@ name: jgengine
 description: Route game work to the smallest useful JGengine guidance set.
 ---
 
-# JGengine intake and router
+# JGengine router
 
-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.
+JGengine is a TypeScript SDK of small general systems that combine into any game. Rules live in [AGENTS.md](../../../AGENTS.md); packages, layering and commands in [README.md](../../../README.md) (jgengine.com from a created project). Load only the domain a task needs.
 
-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/`.
+A created project ships `jgengine`, `create-game-jg`, `jgengine-editor`, `jgengine-verify`, `game-design` and `jgengine-ui`; `npx jgengine skills -p --all` adds the rest, with no `api.md` (read `node_modules/@jgengine/<pkg>/dist/*.d.ts`). Upgrading a project, `doctor` and `sync`: `jgengine-editor`.
 
-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`.
+## Start
 
-## Framework-first decisions
+A new game or big feature starts with `create-game-jg`: it owns the create flow, `PLAN.md` and milestones. Never copy `games/*` or reach for a genre kit or preset. Pitch to testable promise: `game-design`; authored spaces and encounters: `level-design`.
 
-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.
+## The parts
 
-Check engine `beta` before recreating an upstream fix: games run the engine source from
-the same commit, so a fix that exists is adopted by importing it. After adoption, remove
-superseded local machinery and verify the actual game. Outside this repository, report
-missing SDK contracts upstream rather than treating a local engine implementation as the
-finished solution.
+Break every feature into these before looking anything up: "supply drop" is a Schedule, Placement, Ladder, Requirement, Table and Motion track. One home each; `@jgengine/core/parts` re-exports their model layers.
 
-## 1. Establish the target
+| Part | Home |
+| --- | --- |
+| Meter | `stats/statPool.ts` |
+| Ladder | `threshold/thresholds.ts` |
+| Phases | `time/stateSchedule.ts` |
+| Schedule | `time/pacedSchedule.ts` |
+| Slots | `time/refillSlots.ts` |
+| Placement | `world/spatialSample.ts`, `game/spawnPoints.ts` |
+| Table | `random/pick.ts` |
+| Requirement | `rules/predicate.ts` |
+| Modifiers | `progression/statGraph.ts` |
+| Inheritance | `inheritance/inheritance.ts` |
+| Motion track | `movement/motionTrack.ts` |
 
-Before building a game or a big feature, plan it: `npx jgengine plan <game> --brief "<brief>"` writes `PLAN.md`; list every feature the brief implies under `## Features` and run `npx jgengine plan <game>` again to fill each feature's engine owner and the gaps; then order `## Milestones`, one PR each, and tick each as it lands. For greenfield builds, also write `src/art-direction.md` before any code.
+The cookbook shows each common feature built from these in a few lines: [recipes/cookbook.md](recipes/cookbook.md).
 
-Treat the pitch as a unique composition of needs, not a genre to fill in — never reach for a genre kit, preset, archetype, or class template ("default sports car", "default RPG", "default FPS") in the SDK or skills (see [AGENTS.md](../../../AGENTS.md)). Use `game-design` to turn the pitch into a testable player promise, verbs, loops, progression, failure, and completion scenario. Use `level-design` when play depends on authored spaces, routes, encounters, exploration, or spatial pacing. Capture only decisions that change architecture:
+## Domains
 
-- player point of view and controls
-- world shape and authored content
-- core loop, interaction, combat, and progression
-- solo, local, hosted, or persistent multiplayer
-- HUD/menu states and **custom** UI art direction (compose shipped building blocks + HudTheme; no unskinned stock face)
-- one observable completion scenario
+| Load | When |
+| --- | --- |
+| `jgengine-editor` | anything visible in the world: placement, terrain, paths, assets; project upgrades |
+| `jgengine-world` | runtime movement, input, interaction, AI, navigation, audio |
+| `jgengine-gameplay` | state, systems, inventory, crafting, quests, economy, turns |
+| `jgengine-combat` | targeting, stats, damage, effects, abilities, loot |
+| `jgengine-ui` | HUD, menus, layout, accessibility, touch |
+| `jgengine-assets` | models, sprites, audio files, licensing, catalogs |
+| `jgengine-multiplayer` | authority, replication, sessions, persistence |
+| `game-improvement` | deepening an existing game |
+| `jgengine-verify` | before any claim that a change works |
+| `workflow` | landing a change (monorepo) |
+| `improve` | backlog passes |
 
-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 --template 2d` (a `board` world drawn by GameUI over `@jgengine/core/puzzle/cellGrid`). `create --template 3d|2d|builder` is the one way to start a game, in this monorepo too (`bun run jgengine create "<Title>"` lands in `games/`); never copy `games/*`. The game's `jgengine.json` says what it is and uses (template, editor, `@jgengine` packages, and in-repo its adoption debt and boot probes). Change what a game uses by editing it, then run `jgengine sync`, which also brings a game up to the running engine: its `@jgengine` versions and its template's shared files (wiring, page, tooling scripts, AGENTS.md). A shared file the game rewrote goes in its `owns` list so sync leaves it alone.
+World content is editor-first: anything that adds, moves or restyles something visible starts in `jgengine-editor`, and `jgengine-world` consumes the document.
 
-For an existing game asked to pick up a new engine release ("jgengine published a new version, grab it"), run `npx jgengine@latest sync` in the project (or at its workspace root): it moves every `@jgengine` pin and catalog entry to that release, refreshes the template's files, and prints every Migrate step and Adopt-worthy addition in between. Install, migrate oldest-first, then work the Adopt lists instead of reconstructing the changelog by hand.
+## Discover before writing
 
-`doctor` resolves Bun `catalog:` and `catalog:<name>` declarations from the nearest workspace's `workspaces.catalog` or `workspaces.catalogs` and follows hoisted SDK installs; missing or malformed catalog entries fail diagnostics. `sync` at a workspace root moves the catalog pins (preserving per-game `catalog:` declarations, CLI/github versions and a held editor override) and changes declarations only: run `bun install` at the root, then `jgengine doctor --workspace --json` once there.
+1. `npx jgengine has "<feature>" ...` answers many features at once (covered, partial or gap, with imports). `npx jgengine find <intent>` names the home folder, primitives, recipes and assets. Search the moment you would hand-roll a HUD window, inventory grid, hotkey, minimap, stat bar or character motion.
+2. `npx jgengine recipe <name>` prints a typechecked snippet; `npx jgengine recipe` lists them. [recipes/minimal-game.md](recipes/minimal-game.md) is the whole-game walkthrough; each domain has `recipes/`.
+3. Open `api.md` or a `.d.ts` only for exact signatures, with grep.
 
-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.
+If nothing fits, name the shared owner first (AGENTS.md, "Reusable capability goes upstream first"); report SDK gaps upstream outside this repo.
 
-## 2. Select domains
+## Finish
 
-Load only rows the target needs. Do not preload every domain.
-
-| Need | Skill | Owner |
-| --- | --- | --- |
-| player promise, pillars, verbs, loops, economy, progression, balance | `game-design` | experience and rule intent |
-| substantial existing-game improvement across depth, world and presentation | `game-improvement` | ordered improvement plan and per-game completion |
-| metrics, topology, encounters, navigation, spatial pacing | `level-design` | playable space intent |
-| scene placement, terrain painting, paths, asset authoring | `jgengine-editor` | editor document and authoring tools |
-| runtime world, movement, input, interaction, AI, navigation, audio | `jgengine-world` | spatial simulation and world runtime |
-| game state, systems, inventory, crafting, quests, economy, turns | `jgengine-gameplay` | non-combat rules and state |
-| targeting, stats, damage, effects, abilities, projectiles, loot | `jgengine-combat` | combat resolution |
-| HUD, menus, layout, accessibility, touch presentation | `jgengine-ui` | player-facing interface |
-| models, sprites, materials, audio files, source licensing | `jgengine-assets` | asset discovery and catalogs |
-| authority, transport, replication, sessions, host persistence | `jgengine-multiplayer` | network topology and persistence adapters |
-
-World content routes editor-first: any request that adds, moves, restyles, or removes something visible in the world — however phrased ("design this world", "place the enemies", "make it look better") — starts in `jgengine-editor`; the other domains consume the authored document. Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
-
-## 3. Discover before designing
-
-Within each selected domain:
-
-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. Several features at once: `npx jgengine has torpor riding "snap building"` answers each (covered, partial or gap, with folders and imports) as one JSON document. `npx jgengine find <intent>` names the concept's home folder in each layer (read from the engine source or the installed packages), searches every domain's index and every recipe at once, and prints the primitive and its import (or the recipe to open) and matching assets; 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 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
-
-Keep scene coordinates in the editor document, state serializable, randomness injected, and hot-path work bounded. Use `jgengine-verify` for evidence appropriate to the change. Inside this monorepo, `workflow` owns issue/PR completion. Visual polish work also uses the `jgengine-ui` quality reference.
-
-**Required asset pass — completion is gated on real models.** A game is not done while its entities and props are still primitive markers or box placeholders when real models are available for them. Before claiming completion, run an asset pass: every placed entity has its `entityModels` set and every prop its `objectModels` set to real, resolved model refs — not primitive-shape markers. Scaffolds ship with `jgengine-assets` and `npx jgengine assets pull` installed but never auto-triggered, so this step is on you to run explicitly. `jgengine-assets` owns the how-to (sourcing, licensing, `assets pull`, catalog indexing, and resolving refs); load it for the workflow. If a game genuinely wants primitive shapes as its art direction, say so — otherwise unresolved markers/box props are unfinished, not a style.
+Keep scene coordinates in the editor document, state serializable, randomness injected. A game is not done while its entities and props are box markers: run the asset pass in `jgengine-assets`. Prove it with `jgengine-verify`.