@stage5/lumine 0.2.86 → 0.2.87

package/lib/sdk.js

@@ -22,6 +22,12 @@ export const SDK_CLI_METHODS = {
   "aiCards.get": { path: "api/content/ai-card", scopes: ["content:read"] },
   "grammarbles.listQuestions": { path: "api/content/grammarbles/questions", scopes: ["content:read"] },
   "grammarbles.getMyQuestionHistory": { path: "api/content/grammarbles/history", scopes: ["content:read"] },
+  "minecraft.getWorlds": { path: "api/minecraft/worlds", scopes: ["content:read"] },
+  "minecraft.getOnlinePlayers": { path: "api/minecraft/players", scopes: ["content:read"] },
+  "minecraft.getZero": { path: "api/minecraft/zero", scopes: ["content:read"] },
+  "minecraft.getZeroBuilds": { path: "api/minecraft/zero/builds", scopes: ["content:read"] },
+  "minecraft.getPeople": { path: "api/minecraft/people", scopes: ["content:read"] },
+  "minecraft.setPlayerRole": { path: "api/minecraft/people/role", scopes: ["content:write"], write: true },
   "subjects.getMySubjects": { path: "api/content/my-subjects", scopes: ["content:read"] },
   "subjects.search": { path: "api/content/subjects/search", scopes: ["content:read"] },
   "subjects.getSubject": { path: "api/content/subject", scopes: ["content:read"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.86",
+  "version": "0.2.87",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.47.0
-Updated: 2026-09-21
-Generated: 2026-09-23T02:44:06.901Z
+Version: 1.49.0
+Updated: 2026-09-23
+Generated: 2026-09-23T16:01:40.924Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -761,6 +761,47 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - A quiet edition with no editorial events does not call an AI provider and does not consume AI Energy.
   - A failed attempt may be queued again on the same day. A ready edition is immutable for ordinary viewers.
 
+### Twinkle.minecraft
+- async getWorlds() | scopes: content:read
+  - Returns: { worlds: [{ id, name, dimension, spawn: { x, z } | null, map: { tileUrlTemplate, minZoom, maxZoom, tilePixels, blocksPerTileAtMaxZoom, renderedAt } | null }], stale }
+  - List the server's worlds (world, world1, world2, world_nether, world_the_end) with squaremap tile info for drawing a top-down map.
+  - Tiles are 512x512 PNGs over HTTPS from www.twinklemc.site. At maxZoom one pixel is one block; blocksPerTile = blocksPerTileAtMaxZoom * 2 ** (maxZoom - z); tile x/y = floor(block x/z / blocksPerTile). Fill {z}, {x}, {y}. map.renderedAt tells how fresh the tiles are.
+  - Limited rollout: apps not enabled yet get 403 with code minecraft_sdk_not_enabled.
+  - stale: true means the Minecraft server was briefly unreachable and the data is a recent cached copy.
+  - Example: const { worlds } = await Twinkle.minecraft.getWorlds(); const w = worlds.find((x) => x.id === 'world'); const z = w.map.maxZoom; const blocksPerTile = w.map.blocksPerTileAtMaxZoom * 2 ** (w.map.maxZoom - z); const tx = Math.floor(blockX / blocksPerTile), ty = Math.floor(blockZ / blocksPerTile); const url = w.map.tileUrlTemplate.replace('{z}', z).replace('{x}', tx).replace('{y}', ty);
+- async getOnlinePlayers() | scopes: content:read
+  - Returns: { players: [{ name, world, x, y, z, isZero }], count, stale }
+  - List players currently online with their world and block coordinates. Zero appears with isZero: true and is not counted in count.
+  - Cached for about 5 seconds; poll no faster than every 5 seconds.
+  - Names are Minecraft usernames, not Twinkle usernames.
+  - Example: const { players, count } = await Twinkle.minecraft.getOnlinePlayers();
+- async getZero() | scopes: content:read
+  - Returns: { zero: { online, world, position: { x, y, z } | null, activity: 'idle'|'thinking'|'building'|'workshop', currentBuild: { id, title, status, placed, total, requester, world, bounds } | null, queue: [build], workshop: { world, min, max } | null, updatedAt }, stale }
+  - Where Zero is and what he is doing right now, including the build in progress and its progress.
+  - Cached for about 3 seconds.
+  - bounds are { min: [x, y, z], max: [x, y, z] } in world block coordinates.
+  - Example: const { zero } = await Twinkle.minecraft.getZero(); if (zero.currentBuild) console.log(zero.currentBuild.title, zero.currentBuild.placed + '/' + zero.currentBuild.total);
+- async getZeroBuilds({ limit, kind } = {}) | scopes: content:read
+  - Returns: { builds: [{ id, kind: 'helper'|'workshop', title, status, placed, total, requester, world, bounds, createdAt }], stale }
+  - Zero's recent builds, newest first: builds for players (helper) and his own workshop projects (workshop).
+  - limit is 1-50 (default 10). kind filters to helper or workshop builds.
+  - Example: const { builds } = await Twinkle.minecraft.getZeroBuilds({ limit: 10, kind: 'workshop' });
+- async getPeople() | scopes: content:read
+  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', groups, op, online, banned, protected, firstSeenAt, lastSeenAt, isZero }], roles }
+  - Everyone who has joined the server with their in-game role, for the server owner's role management screen.
+  - Only the server owner, in an app they own, gets the list; everyone else gets { canManage: false, people: [] } without an error, so hide the feature when canManage is false.
+  - Roles: visitor (play and chat), member (/tpa, /home, /back, may ask Zero to build), builder (member + /fly and creative/survival), moderator (builder + teleport others, CoreProtect rollback, /kick). op: true players are server operators and have every power regardless of role.
+  - protected: true players (the owner and Zero's account) can't be changed from the app. Sorted online first, then most recently seen.
+  - Not cached; call on screen open or after a change, not on a timer.
+  - Example: const { canManage, people } = await Twinkle.minecraft.getPeople(); if (!canManage) hidePeopleTab();
+- async setPlayerRole({ uuid, role }) | scopes: content:write
+  - Returns: { player: { uuid, name, role, op } }
+  - Change a player's in-game role; it applies immediately, even while they are online.
+  - Server owner only, in an app they own; others get 403 with code minecraft_roles_forbidden.
+  - role is visitor, member, builder or moderator. 400 codes: minecraft_bad_uuid, minecraft_bad_role, minecraft_protected_player, minecraft_unknown_player. 503 minecraft_unavailable while the server restarts.
+  - Every change is logged on the server and emailed to the owner; the player is told in game.
+  - Example: await Twinkle.minecraft.setPlayerRole({ uuid: person.uuid, role: 'builder' });
+
 ### Twinkle.leaderboards
 - async get({ boardKey = 'default', limit, cursor } = {}) | scopes: none
   - Returns: { entries: [{ rank, id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt }], scores, cursor, hasMore, personalBest: { id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt } | null }

package/sdk/LUMINE_ADMIN.md

@@ -3008,7 +3008,10 @@ disagreements and the `jev_reply_gate_audit`, `jev_chat_routing_audit` and
 missing evidence. Report fallback rates and reasons instead. Auto rows served
 without a comparison carry `baselineStatus: not_run`; its fallback LLM spend is
 `lumine_model_fallback`. The eight comparison-only routing families below are
-unchanged. The rest of this section describes the pre-September-23 pilot.
+unchanged. Chat routing is also off since September 23
+(`JEV_CHAT_ROUTING_ENABLED`, default off; Jev served ~1% of chats and could not
+judge when a reply needs older history), so zero chat serving rows is expected.
+The rest of this section describes the pre-September-23 pilot.
 
 Read `data.jevPilot` from `lumine admin brief --json` and carry it into
 the full report for Mikey. The active `daily-run report --json` also includes