@stage5/lumine 0.2.88 → 0.2.90

package/lib/chatlog.js

@@ -0,0 +1,108 @@
+// lumine chatlog: what players said in a Build app's realtime world, for the
+// app's owner (or an admin). Logging is off until switched on per app:
+//
+//   lumine chatlog [build] [--since 2h] [--limit 100] [--instance <id>] [--json]
+//   lumine chatlog enable [build]     (players see a notice while it is on)
+//   lumine chatlog disable [build]
+import { requestJson } from "./http.js";
+import { ensureAuth, assertAuthScope } from "./auth.js";
+import { resolveRequiredBuildId } from "./util.js";
+import { resolveRequiredBuildIdOrSelected } from "./commands.js";
+
+const ACTIONS = new Set(["enable", "disable", "show"]);
+
+async function resolveTarget(options, auth, rawTarget) {
+  if (rawTarget) {
+    const buildId = resolveRequiredBuildId(rawTarget);
+    if (!Number.isSafeInteger(buildId) || buildId <= 0) {
+      throw new Error("Pass a Twinkle build URL or positive integer build id.");
+    }
+    return buildId;
+  }
+  return await resolveRequiredBuildIdOrSelected(options, auth);
+}
+
+function formatTime(unixSeconds) {
+  const d = new Date(Number(unixSeconds) * 1000);
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+export async function chatlogCommand(options) {
+  const positional = options.positional || [];
+  const action = ACTIONS.has(String(positional[0] || ""))
+    ? String(positional[0])
+    : "show";
+  const rawTarget = String(
+    options.target && !ACTIONS.has(options.target)
+      ? options.target
+      : action === "show"
+        ? positional[0] || ""
+        : positional[1] || "",
+  ).trim();
+  const auth = await ensureAuth(options);
+  await assertAuthScope({
+    options,
+    auth,
+    scope: action === "show" ? "build:read" : "build:write",
+  });
+  const buildId = await resolveTarget(options, auth, rawTarget);
+
+  if (action !== "show") {
+    const enabled = action === "enable";
+    const result = await requestJson({
+      method: "PUT",
+      url: `${options.apiUrl}/build/${buildId}/chat-log-setting`,
+      authToken: auth.token,
+      body: { enabled },
+      timeoutMs: options.timeoutMs,
+    });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(
+      enabled
+        ? `Chat logging is ON for ${result.title} (#${result.buildId}). Lines are kept ${result.retentionDays} days, and players see a notice while it is on.`
+        : `Chat logging is OFF for ${result.title} (#${result.buildId}). Nothing new is stored; saved lines expire after ${result.retentionDays} days.`,
+    );
+    return;
+  }
+
+  const query = new URLSearchParams();
+  query.set("since", String(options.chatlogSince || "24h"));
+  const limit = Math.floor(Number(options.chatlogLimit || 100));
+  query.set("limit", String(Number.isFinite(limit) && limit > 0 ? limit : 100));
+  if (options.chatlogInstance) query.set("instance", options.chatlogInstance);
+  if (options.cursor) query.set("cursor", String(options.cursor));
+  const result = await requestJson({
+    method: "GET",
+    url: `${options.apiUrl}/build/${buildId}/chat-log?${query.toString()}`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const messages = Array.isArray(result.messages) ? result.messages : [];
+  console.log(
+    `Chat log for ${result.title} (#${result.buildId}): logging ${result.enabled ? "ON" : "OFF"}, kept ${result.retentionDays} days.`,
+  );
+  if (!messages.length) {
+    console.log(
+      result.enabled
+        ? `No chat since ${query.get("since")}.`
+        : "Nothing logged. Turn it on with: lumine chatlog enable",
+    );
+    return;
+  }
+  // oldest first, like reading a conversation
+  for (const m of [...messages].reverse()) {
+    const who = m.username || (m.guest ? "Guest" : `user ${m.userId}`);
+    console.log(`${formatTime(m.createdAt)}  [${m.instanceId || "-"}]  ${who}: ${m.text}`);
+  }
+  if (result.nextCursor) {
+    console.log(`Older lines: lumine chatlog ${result.buildId} --since ${query.get("since")} --cursor ${result.nextCursor}`);
+  }
+}

package/lib/commands.js

@@ -58,6 +58,7 @@ import {
 } from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
 import { rewardsCommand, reportRewardDeclaration } from "./rewards.js";
+import { chatlogCommand } from "./chatlog.js";
 import {
   assertAuthScope,
   ensureAuth,
@@ -275,6 +276,10 @@ export async function main() {
     await assetsCommand(options);
     return;
   }
+  if (options.command === "chatlog") {
+    await chatlogCommand(options);
+    return;
+  }
   if (options.command === "rewards") {
     await rewardsCommand(options);
     return;
@@ -2472,6 +2477,9 @@ export function parseArgs(args) {
             : ""),
       ).trim() || "",
     cursor: Math.max(0, Math.floor(Number(raw.cursor) || 0)),
+    chatlogSince: raw.since ? String(raw.since) : "",
+    chatlogLimit: raw.limit ? String(raw.limit) : "",
+    chatlogInstance: raw.instance ? String(raw.instance) : "",
     adminCursor: raw.cursor ? String(raw.cursor) : "",
     adminAfter: raw.after ? String(raw.after) : "",
     adminPostedAfter: raw.postedAfter ? String(raw.postedAfter) : "",
@@ -2939,9 +2947,12 @@ export function printHelp() {
   lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>
   lumine assets delete <assetId>
   lumine assets prune [--yes]
+  lumine chatlog [build] [--since 2h] [--limit 100] [--instance <id>] [--json]
+  lumine chatlog enable|disable [build]
   lumine rewards check
   lumine rewards sheet <file.json>
   lumine rewards sheet --show
+  lumine rewards review
   lumine thumbnail set <file>
   lumine thumbnail capture [--out <file>]
   lumine thumbnail generate ["<prompt>"] --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>

package/lib/constants.js

@@ -447,6 +447,7 @@ export const COMMANDS = new Set([
   "sdk",
   "assets",
   "rewards",
+  "chatlog",
   "thumbnail",
   "doctor",
   "help",

package/lib/rewards.js

@@ -203,6 +203,28 @@ export async function rewardsCommand(options) {
     if (!result.ok) process.exitCode = 1;
     return;
   }
+  if (action === "review") {
+    await assertAuthScope({ options, auth, scope: "build:write" });
+    const result = await requestJson({
+      url: `${options.apiUrl}/build/${buildId}/rewards/reviews`,
+      method: "POST",
+      authToken: auth.token,
+      timeoutMs: options.timeoutMs,
+      body: {},
+    });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const reviewId = result?.policy?.latestReviewId;
+    console.log(
+      `Sent Build ${buildId} for reward review${reviewId ? ` (request #${reviewId})` : ""}. State: ${result?.state || "unknown"}.`,
+    );
+    console.log(
+      "The saved version and the question sheet on file are frozen for the reviewer. Saving again closes this request; send it again after the save.",
+    );
+    return;
+  }
   printRewardsHelp();
   throw new Error(`Unknown rewards action: ${action}`);
 }
@@ -212,6 +234,7 @@ function printRewardsHelp() {
   lumine rewards check              Validate rewards.json (workspace or saved) against the question sheet on file
   lumine rewards sheet <file.json>  Upload the private question sheet ({ rules: { <ruleId>: { questions?, sets? } } })
   lumine rewards sheet --show       Summarize the sheet on file (never prints answer keys)
+  lumine rewards review             Send the saved version (with the sheet on file) for XP/Coin review, like "Send for review" on the website
 
 rewards.json (project root) declares the economy the reviewer approves:
   { "userDailyXP", "userDailyCoins", "userDailyClaims"?,

package/lib/sdk.js

@@ -35,6 +35,22 @@ export const SDK_CLI_METHODS = {
   "minecraft.getMyLink": { path: "api/minecraft/link", scopes: ["content:read"] },
   "minecraft.createLinkCode": { path: "api/minecraft/link/code", scopes: ["content:write"], write: true },
   "minecraft.unlinkMinecraft": { path: "api/minecraft/link/unlink", scopes: ["content:write"], write: true },
+  "minecraft.getDesigns": { path: "api/minecraft/designs", scopes: ["content:read"] },
+  "minecraft.getDesign": { path: "api/minecraft/design", scopes: ["content:read"] },
+  "minecraft.saveDesign": { path: "api/minecraft/designs/save", scopes: ["content:write"], write: true },
+  "minecraft.updateDesign": { path: "api/minecraft/designs/update", scopes: ["content:write"], write: true },
+  "minecraft.deleteDesign": { path: "api/minecraft/designs/delete", scopes: ["content:write"], write: true },
+  "minecraft.checkPlacement": { path: "api/minecraft/placement/check", scopes: ["content:read"] },
+  "minecraft.buildDesign": { path: "api/minecraft/placement/build", scopes: ["content:write"], write: true },
+  "minecraft.stopZero": { path: "api/minecraft/zero/stop", scopes: ["content:write"], write: true },
+  "minecraft.undoBuild": { path: "api/minecraft/zero/undo", scopes: ["content:write"], write: true },
+  "minecraft.getSnaps": { path: "api/minecraft/snaps", scopes: ["content:read"] },
+  "minecraft.getSnap": { path: "api/minecraft/snap", scopes: ["content:read"] },
+  "minecraft.deleteSnap": { path: "api/minecraft/snaps/delete", scopes: ["content:write"], write: true },
+  "minecraft.getServerLogs": { path: "api/minecraft/logs", scopes: ["content:read"] },
+  "minecraft.getArrivalPoints": { path: "api/minecraft/homes", scopes: ["content:read"] },
+  "minecraft.setArrivalPoint": { path: "api/minecraft/homes/set", scopes: ["content:write"], write: true },
+  "minecraft.clearArrivalPoint": { path: "api/minecraft/homes/clear", 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.88",
+  "version": "0.2.90",
   "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.51.0
-Updated: 2026-09-24
-Generated: 2026-09-24T00:08:02.260Z
+Version: 1.59.0
+Updated: 2026-09-26
+Generated: 2026-09-26T05:55:48.545Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -488,9 +488,10 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Errors include invalid_ai_decision (bad input), ai_decision_unavailable, ai_decision_timeout, ai_decision_rate_limited, ai_decision_invalid_response, and ai_usage_unavailable, plus the existing auth, access, Energy, and rate-limit errors. Invalid answers are rejected. An answer that fails validation is retried once on the server within the same deadline; there is no other provider retry, fabricated answer, or paid LLM fallback. Do not automatically retry a rejected request.
   - Call on meaningful app events with bounded frequency, batch questions, and keep rendering and deterministic game rules in local code. Ignore a result if the app state or turn changed while it was pending. Test uncertain inputs and choose a fallback appropriate to the experience; confidence is not a correctness guarantee.
   - Example: const { answers } = await Twinkle.ai.decide({ state: { playerRequest, availableActions }, questions: { action: { type: 'choice', instructions: 'Which available companion action best fits playerRequest? Use wait when unclear.', criteria: { follow: 'Follow the player', guard: 'Stay and keep watch', wait: 'Do nothing until clarified' } }, needsClarification: { type: 'noul', instructions: 'Is playerRequest too ambiguous to act on?' } } }); const action = answers.needsClarification.noul > 0.5 ? 'wait' : answers.action.choice;
-- async generateObject({ prompt, expectedStructure, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus, onReasoning } = {}) | scopes: none
+- async generateObject({ prompt, expectedStructure, images, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus, onReasoning } = {}) | scopes: none
   - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, requestedModel, webSearch, aiUsagePolicy }
   - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic, with optional live output/status callbacks and web search.
+  - images: up to 3 reference image URLs the model looks at along with the prompt (a sketch, a photo, a screenshot). They must be Twinkle-hosted uploads (Twinkle.files.pickAndUpload / uploadGenerated asset URLs; PNG, JPEG, WebP or GIF); anything else is refused with 400 before any model call. Image input counts toward the AI Energy of the call like any other input.
   - Signed-in viewers only.
   - Use this instead of asking Twinkle.ai.chat to return JSON.
   - expectedStructure must be a JSON object that describes the exact returned object shape.
@@ -532,6 +533,20 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - GPT Image 2.5 battery spending uses actual image-model input and output token usage. The confirmation shows an image-output estimate; prompts and reference images use additional energy.
   - responseId and imageId are opaque continuation handles. Pass them back unchanged to edit a prior result; do not assume an OpenAI ID format. Existing GPT Image 2 continuations remain usable.
   - Example: const result = await Twinkle.ai.generateImage({ prompt: 'Create a fashion guide portrait for this face with flattering colors and outfit ideas', referenceImageB64, quality: 'high', onStatus: (status) => console.log(status.stage) });
+- async generateMusic({ prompt, length, instrumental, requestId, timeoutMs } = {}) | scopes: none
+  - Returns: { success, asset, url, mimeType, structure, length, instrumental, model, requestId, replayed?, aiUsagePolicy }
+  - Generate a finished piece of music (rendered audio, not notes) from a text description with Google Lyria. The audio is saved to the viewer's own Twinkle.files and returned as an asset URL.
+  - Signed-in viewers only. Call it directly from an explicit viewer action such as a button click; calls from page load, timers or programmatic retries are rejected (USER_ACTIVATION_REQUIRED).
+  - Twinkle shows a host-owned confirmation with the battery cost for every generation. One approval authorizes exactly one request.
+  - length: 'full' (default) is a complete song of about two to three minutes (Lyria 3.5); 'clip' is a 30-second piece (Lyria 3 Clip) at half the cost.
+  - Describe genre, mood, instruments, tempo and structure in the prompt; ask for vocals or pass instrumental: true for no vocals. Duration and vocals have no other controls.
+  - Prompts naming artists, bands, songs or copyrighted lyrics are refused with code music_prompt_blocked and cost nothing: show the viewer the error message so they can reword it.
+  - The result is a normal Twinkle.files asset (asset.id, asset.url, audio/mpeg) owned by the viewer and counted against their file storage; it also appears in Twinkle.files lists. Store asset.url (e.g. in privateDb/sharedDb) to play it later.
+  - structure is the model's song-structure text (section markers, and lyrics when there are vocals).
+  - AI Energy is charged only after the music is saved. Failures, timeouts and refusals are not charged.
+  - Only one music generation per viewer may run at a time (code ai_music_generation_in_progress). A retry with the same requestId returns the finished result without paying again (replayed: true), or code music_in_progress while it is still being made.
+  - Generation usually takes one to three minutes; the SDK timeout defaults to 600000ms. Show progress UI while waiting.
+  - Example: const song = await Twinkle.ai.generateMusic({ prompt: 'Warm lo-fi hip hop with dusty drums, a mellow Rhodes and rain in the background', instrumental: true }); audio.src = song.url;
 - onImageGenerationStatus(listener) | scopes: none
   - Returns: unsubscribe function
   - Subscribe to real-time image generation status events forwarded into the build iframe.
@@ -787,14 +802,14 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - 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, twinkle: { userId, username } | null }], 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.
+  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', op, online, isZero, twinkle: { userId, username } | null, ...owner: groups, banned, protected, firstSeenAt, lastSeenAt | ...others: seen: 'online'|'today'|'week'|'month'|'older'|null }], roles }
+  - Everyone who has joined the server with their in-game rank, for a player directory; the server owner also gets the full records for role management.
+  - Every viewer gets the list. Only the server owner, in an app they own, gets canManage: true with full records (groups, bans, exact first/last seen); everyone else gets canManage: false and the public view: banned players left out, and seen is a rough bucket instead of exact times. Show role controls only when canManage is true.
   - 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.
   - twinkle is the Twinkle account linked to that player with /link, or null.
-  - Example: const { canManage, people } = await Twinkle.minecraft.getPeople(); if (!canManage) hidePeopleTab();
+  - Example: const { canManage, people } = await Twinkle.minecraft.getPeople(); renderDirectory(people, { editable: canManage });
 - 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.
@@ -845,6 +860,175 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Remove one of the viewer's own linked Minecraft accounts.
   - Only the viewer's own links; removed is false when there was nothing to remove.
   - Example: await Twinkle.minecraft.unlinkMinecraft({ uuid: link.uuid });
+- async getDesigns({ query } = {}) | scopes: content:read
+  - Returns: { designs: [{ id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt }], access: { rank, linked, canOrder, canModerate, isOwner, canKeepPrivate } | null }
+  - Zero's design library: published designs plus the viewer's own private ones.
+  - Built-in designs (redstone devices and so on) have no author and are public.
+  - previewUrl is an image set with updateDesign, or null.
+  - access says what this viewer may do: canOrder shows placement tools (builders, moderators, the owner).
+  - Example: const { designs } = await Twinkle.minecraft.getDesigns({ query: 'castle' });
+- async getDesign({ id }) | scopes: content:read
+  - Returns: { design: { id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt }, size: [w, h, d], palette: [blockState], cells: number[] }
+  - A design's blocks for a 3D preview.
+  - cells is a flat list of [x, y, z, paletteIndex] numbers; air is left out. palette entries are block states like "oak_stairs[facing=north,half=bottom]".
+  - Private designs are only returned to their designer.
+  - Example: const { size, palette, cells } = await Twinkle.minecraft.getDesign({ id: 'harbor_house' }); for (let i = 0; i < cells.length; i += 4) addCube(cells[i], cells[i + 1], cells[i + 2], palette[cells[i + 3]]);
+- async saveDesign({ id, name, summary, category, tags, visibility, parts }) | scopes: content:write
+  - Returns: { design: { id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt } }
+  - Save a design (or a new version of your design) from blueprint parts.
+  - parts use Zero's blueprint shapes: box, hollow_box, walls, floor, line, block, cylinder, sphere, gable_roof, pyramid_roof; offsets x = east, y = up, z = south; later parts override earlier ones (carve doors/windows with "air"). Up to 60,000 blocks and 96 blocks in each direction.
+  - category is building, decor, farm or path. visibility private (default) or public. Saving the same id again adds a version; only its designer can do that. Rejections come back as 400 minecraft_studio_rejected with a readable message.
+  - Who may: any signed-in viewer; they own what they save (they can change or delete it). Only builders and above (access.canKeepPrivate from getDesigns) may keep a design private; for anyone else visibility must be 'public' (omitted means public) or the call fails with 403 minecraft_private_needs_builder. Builders and above save private designs when visibility is omitted. Players have a limit on how many designs they keep.
+  - Example: await Twinkle.minecraft.saveDesign({ id: 'harbor_house', name: 'Harbor house', category: 'building', visibility: 'private', parts: [{ shape: 'floor', from: [0, 0, 0], to: [8, 0, 6], block: 'stone_bricks' }, { shape: 'walls', from: [0, 1, 0], to: [8, 4, 6], block: 'spruce_planks' }] });
+- async updateDesign({ id, visibility, previewUrl, name, summary }) | scopes: content:write
+  - Returns: { design: { id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt } }
+  - Publish or unpublish a design, set its preview image, or rename it.
+  - previewUrl is typically a Twinkle.files upload of a rendered preview.
+  - Who may: a design's own designer; moderators (by linked account) and the server owner may change or delete anyone's. Only builders and above may set visibility 'private' (403 minecraft_private_needs_builder otherwise).
+  - Example: await Twinkle.minecraft.updateDesign({ id: 'harbor_house', visibility: 'public' });
+- async deleteDesign({ id }) | scopes: content:write
+  - Returns: { deleted }
+  - Remove one of your designs from the library.
+  - Built-in designs can't be deleted.
+  - Who may: a design's own designer; moderators (by linked account) and the server owner may change or delete anyone's.
+  - Example: await Twinkle.minecraft.deleteDesign({ id: 'old_test' });
+- async checkPlacement({ designId, world, x, z, y?, facing?: 'north'|'east'|'south'|'west' }) | scopes: content:read
+  - Returns: { check: { clear, reasons, world, facing, anchor, bounds: { min, max }, ground: { y, min, max, water }, builtBlocks, builtSamples, placedBy: [{ name, blocks }], design } }
+  - Check a building site for a design: where it would sit and whether it would touch anyone's builds.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - The footprint is centred on x/z and turned to face facing; without y it sits on the ground. clear is false when built (non-natural) blocks stand in the footprint or 3 blocks around it, the ground is very uneven, or it would leave the world; reasons explains. placedBy lists players CoreProtect recorded placing blocks there.
+  - Call on a user action (drop or rotate), not while dragging.
+  - Example: const { check } = await Twinkle.minecraft.checkPlacement({ designId: 'harbor_house', world: 'world', x: 1200, z: 700, facing: 'south' }); outline.color = check.clear ? 'green' : 'red';
+- async buildDesign({ ...placement, force }) | scopes: content:write
+  - Returns: { jobId, check, priority }
+  - Order Zero to build a design at a site; he switches to creative and builds it before other work.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Follow progress with getZero() (currentBuild) and getZeroBuilds().
+  - Builders: one order waiting or building at a time, published designs or their own, and orders wait in the normal queue (priority false). Moderators: up to 3 orders, ahead of other work. The owner: no limit. force (build on a site that isn't clear) is owner-only.
+  - Example: const { jobId } = await Twinkle.minecraft.buildDesign({ designId: 'harbor_house', world: 'world', x: 1200, z: 700, facing: 'south' });
+- async stopZero() | scopes: content:write
+  - Returns: { stopped, message }
+  - Stop the build Zero is doing right now (placed blocks stay).
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Anyone may stop or undo their own builds; moderators also builders' and members' builds and Zero's own projects; the owner anything.
+  - Example: await Twinkle.minecraft.stopZero();
+- async undoBuild({ jobId }) | scopes: content:write
+  - Returns: { undone, title, message }
+  - Undo one of Zero's builds, putting back what was there before.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Anyone may stop or undo their own builds; moderators also builders' and members' builds and Zero's own projects; the owner anything.
+  - Example: await Twinkle.minecraft.undoBuild({ jobId });
+- async getSnaps({ before, limit, uuid } = {}) | scopes: content:read
+  - Returns: { snaps: [{ id, takenAt, name, uuid, world, x, y, z, caption, blocks, players, twinkleUserId }] }
+  - The /snap Gallery: 3D scenes players took in game with /snap, newest first.
+  - Every viewer gets the list. before is a time in ms (the takenAt of the last snap you have) for paging; limit 1-60 (default 30); uuid filters to one player's snaps.
+  - Example: const { snaps } = await Twinkle.minecraft.getSnaps({ limit: 30 });
+- async getSnap({ id }) | scopes: content:read
+  - Returns: { scene: { version, id, at, by, caption, origin: [x, y, z], size: [w, h, d], palette, count, blocks, light, biomes: { palette, grid }, camera: { x, y, z, yaw, pitch, fov }, world: { name, environment, time, moonPhase, storm, thunder }, players: [{ name, uuid, x, y, z, yaw, pitch, bodyYaw, pose, sneaking, self, zero, slim, skin }] } }
+  - One snap's scene, to render in 3D from where it was taken.
+  - blocks is base64 of 5 bytes per visible block: x, y, z (relative to origin) and the palette index as a big-endian uint16. palette entries are block states like oak_stairs[facing=east,half=bottom,shape=straight,waterlogged=false].
+  - light is base64 of 7 bytes per block, in the same order: the light each face receives (+x, -x, +y, -y, +z, -z) and the block's own cell, each sky << 4 | block (0-15).
+  - biomes.grid is base64 of one byte per column (x-major: index = x * depth + z) into biomes.palette (biome ids like plains, cherry_grove).
+  - camera is in world coordinates (subtract origin for scene space); yaw 0 looks toward +z (south), 90 toward -x; pitch is positive looking down. world.time is the tick of day (0 sunrise, 6000 noon, 18000 midnight).
+  - players[].skin is a data: URL of the 64x64 skin PNG when known; slim means the thin-armed model.
+  - Scenes are large (up to a few MB); fetch one at a time.
+  - Example: const { scene } = await Twinkle.minecraft.getSnap({ id });
+- async deleteSnap({ id }) | scopes: content:write
+  - Returns: { deleted }
+  - Delete a snap from the Gallery.
+  - Who may: the player who took it (by a linked Minecraft account), moderators, and the server owner. Others get 403 minecraft_snap_forbidden.
+  - Example: await Twinkle.minecraft.deleteSnap({ id });
+- async getArrivalPoints() | scopes: content:read
+  - Returns: { accounts: [{ uuid, name, online, world, worldLabel, points: [{ world, label, x, y, z, savedAt }] }] }
+  - The viewer's private arrival points: where the Twinkle Gate portals drop their linked Minecraft account in each world.
+  - Only the caller's own linked accounts; 400 minecraft_not_linked when none is linked.
+  - online/world tell whether setArrivalPoint can use the player's current spot right now.
+  - Example: const { accounts } = await Twinkle.minecraft.getArrivalPoints();
+- async setArrivalPoint({ uuid } = {}) | scopes: content:write
+  - Returns: { uuid, name, world, worldLabel, points }
+  - Save where the viewer's Minecraft player is standing right now as their arrival point in that world (the Twinkle Gate portal to that world lands them there).
+  - The player must be online; the spot is their current position, never typed coordinates (so nobody can land inside places they could not walk to).
+  - 400 minecraft_arrival_rejected when not online or the spot is unsafe (no floor, no room, lava); uuid picks one of several linked accounts.
+  - Example: const { worldLabel } = await Twinkle.minecraft.setArrivalPoint();
+- async clearArrivalPoint({ world, uuid }) | scopes: content:write
+  - Returns: { cleared, points }
+  - Remove the viewer's arrival point in a world (back to the shared arrival).
+  - world is a world id such as world, world1, world3, world_nether.
+  - Example: await Twinkle.minecraft.clearArrivalPoint({ world: 'world3' });
+- async getPlayAreas() | scopes: content:read
+  - Returns: { levels: [{ id, name, world, box: [x0,y0,z0,x1,y1,z1], spawn: [x,y,z], by, createdAt, status: 'capturing'|'ready'|'failed', chunkCount, done, blocks }] }
+  - Play areas: captured Minecraft builds (a castle, a cathedral) that apps turn into first-person games, newest first.
+  - Anyone can read. box is inclusive world coordinates; status 'capturing' areas are still being saved (done of chunkCount).
+  - Example: const { levels } = await Twinkle.minecraft.getPlayAreas();
+- async getPlayArea({ id }) | scopes: content:read
+  - Returns: { level: { ...getPlayAreas fields, chunks: [[cx, cz, visibleBlocks]] } }
+  - One play area with its list of captured chunk columns, to stream with getPlayAreaChunk.
+  - Chunk columns are 16x16 blocks (cx = floor(x / 16)); load the ones near the player first.
+  - Example: const { level } = await Twinkle.minecraft.getPlayArea({ id: 'twinkle-keep' });
+- async getPlayAreaChunks({ id, chunks: [[cx, cz], ...] }) | scopes: content:read
+  - Returns: { scenes: [{ cx, cz, scene: { origin: [x,y,z], size: [w,h,d], palette, blocks, light, biomes, count, ... } | null }] }
+  - Up to 9 chunk columns of a play area in the /snap scene format (packed visible blocks with per-face light), cropped to the area's box. Stream the ones around the player.
+  - Same scene format as getSnap; only blocks with a visible face inside the area are included. scene is null for a chunk that is not part of the area.
+  - At most 9 chunks per call; reads share the 180-per-minute build read limit, so cache chunks and load the nearest first.
+  - Example: const { scenes } = await Twinkle.minecraft.getPlayAreaChunks({ id: level.id, chunks: [[64, 29], [65, 29]] });
+- async createPlayArea({ name, world, box, spawn, id }) | scopes: content:write
+  - Returns: { level }
+  - Capture a box of a Minecraft world as a new play area (or re-capture an existing id). Runs in the background: poll getPlayArea until status is 'ready'.
+  - Moderators and the server owner only; others get 403 minecraft_level_forbidden.
+  - At most 320 blocks across each way and 255 tall. spawn [x,y,z] is where players start (default: top centre of the box).
+  - Example: await Twinkle.minecraft.createPlayArea({ name: 'Sand Castle', world: 'world', box: [900, 60, 400, 980, 130, 470] });
+- async getBuildQueue() | scopes: content:read
+  - Returns: { active: job | null, queue: [{ id, title, kind, status, requester, world, bounds: { min, max }, designId, position, priority, mine, placed, total }], campaign: { id, title, active, steps, done, skipped, percent, current, resumeAt, world, steps: [{ index, title, status, designId, anchor, bounds, blocks }] } | null, noBuildWorlds, access: { rank, linked, canOrder, canModerate, isOwner } | null }
+  - Zero's build queue: the build he is on, the orders waiting (in the order he will take them) and the campaign steps he works through when no order waits. For an RTS-style build panel and for drawing queued footprints on a map.
+  - Everyone can read it; mine marks the viewer's own orders (linked account). Orders always run before campaign steps.
+  - noBuildWorlds lists worlds Zero never builds in (World 3, World 4): don't offer placement there.
+  - Example: const { active, queue, campaign, access } = await Twinkle.minecraft.getBuildQueue();
+- async moveQueuedBuild({ jobId, to }) | scopes: content:write
+  - Returns: same as getBuildQueue
+  - Server owner: move a waiting order to position `to` (0 = next).
+  - Owner only (403 minecraft_queue_owner_only).
+  - Example: await Twinkle.minecraft.moveQueuedBuild({ jobId: 142, to: 0 });
+- async removeQueuedBuild({ jobId }) | scopes: content:write
+  - Returns: same as getBuildQueue
+  - Take an order out of the queue (stops it if Zero is already building it). Your own orders; moderators also lower ranks'; the owner any.
+  - Builders and up with a linked account; the rank rule is the same as stopZero.
+  - Example: await Twinkle.minecraft.removeQueuedBuild({ jobId: 142 });
+- async moveCampaignStep({ index, before }) | scopes: content:write
+  - Returns: same as getBuildQueue
+  - Server owner: move a campaign step that has not started to just before the step at index `before` (null = last). Indexes are the step.index values from getBuildQueue.
+  - Owner only.
+  - Example: await Twinkle.minecraft.moveCampaignStep({ index: 17, before: 15 });
+- async skipCampaignStep({ index, skip = true }) | scopes: content:write
+  - Returns: same as getBuildQueue
+  - Server owner: skip a campaign step, or bring a skipped or failed one back (skip: false).
+  - Owner only. A step Zero is building has to be stopped first.
+  - Example: await Twinkle.minecraft.skipCampaignStep({ index: 18 });
+- async setCampaignActive({ active }) | scopes: content:write
+  - Returns: same as getBuildQueue
+  - Server owner: pause or resume Zero's campaign (a paused campaign waits; orders still run).
+  - Owner only.
+  - Example: await Twinkle.minecraft.setCampaignActive({ active: false });
+- async getServerLogs({ days, kinds, query, limit } = {}) | scopes: content:read
+  - Returns: { total, lines: [{ at, kind: 'join'|'leave'|'kick'|'command'|'warn'|'error'|'zero'|'server', level, text }] }
+  - The Minecraft server log for the server owner: joins, kicks, commands, warnings, errors and Zero's lines, newest first, IP addresses removed.
+  - Server owner only, in an app they own; everyone else gets 403 minecraft_roles_forbidden.
+  - days 1-7 (default 1); kinds any of join, leave, kick, command, warn, error, zero, server (default all); query filters by text; limit 1-1000 (default 300). Chat is not included (getChat and getChatHistory have it).
+  - Example: const { lines } = await Twinkle.minecraft.getServerLogs({ days: 2, kinds: ['kick', 'error'] });
+- async getNews({ limit } = {}) | scopes: content:read
+  - Returns: { posts: [{ id, title, body, author, at }], canPost }
+  - Server news: short posts about what's new on Twinkle Minecraft, newest first (players see the newest on join and all of it with /news in game).
+  - Every viewer reads the news. at is the post time in ms; limit 1-50 (default 20). canPost is true for moderators and the server owner (they can call addNews and deleteNews).
+  - Example: const { posts, canPost } = await Twinkle.minecraft.getNews({ limit: 10 });
+- async addNews({ title, body }) | scopes: content:write
+  - Returns: { post: { id, title, body, author, at } }
+  - Post server news (moderators and the server owner). Players in game see the headline right away.
+  - title up to 120 characters (required), body up to 2000. Others get 403 minecraft_news_forbidden. The author is the signed-in viewer's Twinkle username.
+  - Example: await Twinkle.minecraft.addNews({ title: 'World 3 reopens', body: 'Come build!' });
+- async deleteNews({ id }) | scopes: content:write
+  - Returns: { deleted }
+  - Remove a news post (moderators and the server owner).
+  - Others get 403 minecraft_news_forbidden.
+  - Example: await Twinkle.minecraft.deleteNews({ id: post.id });
 
 ### Twinkle.leaderboards
 - async get({ boardKey = 'default', limit, cursor } = {}) | scopes: none

package/sdk/LUMINE_ADMIN.md

@@ -1090,7 +1090,7 @@ app declares its economy in `rewards.json` at the project root (rule ids,
 titles, XP, Coins, tries, retry share, budgets); quiz rules get their questions
 and answer keys from a private question sheet the creator's Lumine uploads with
 `lumine rewards sheet <file.json>` (never a project file: published source is
-readable by every player). **Send for review** freezes the code and proposes
+readable by every player). **Send for review** (website, or `lumine rewards review` from the workspace) freezes the code and proposes
 `rewards.json` merged with the sheet. Approval is Mikey's decision: read the
 frozen code, check that the amounts are right and that the app cannot be
 farmed, change anything that is wrong, approve. **Approval publishes** (since
@@ -1218,6 +1218,19 @@ submitted. The website equivalent is the Management panel's "Edit a copy to
 propose changes" (a private workspace copy owned by the reviewer) followed by
 "Offer my copy with these rules".
 
+**Try this version (since 2026-09-26, API 3c08af5d / vite 2.2.86).** While an
+offer is `changes_offered`, the creator and the reviewer (and nobody else) get
+a **Try this version** button on the chat card, in the creator's reward
+settings and in the Management approvals panel. It plays the offered
+`proposalSnapshot` as a normal app preview through
+`GET /build/preview/build/:buildId/reward-proposal/:reviewId`, with a token of
+its own scope (`reward-proposal:preview`, bound to viewer, build, review and
+revision; re-checked on every file request). XP and Coins inside it are
+simulated against the offered rules and never pay. The app's own SDK data
+calls (privateDb, sharedDb…) still reach the build's real data as the viewer,
+like a draft preview, and the modal says so. A newer revision or an answered
+offer closes the preview (409).
+
 Each offer has a server-owned revision. Changing the files, rules or note
 creates a new revision; a creator looking at an older comparison or decline
 confirmation cannot answer the replacement offer. The creator sees its reward
@@ -3290,6 +3303,16 @@ acting, `off` disables):
 Separately from JEV, a run that reaches its round cap with nothing saved while
 Energy remains gets one extra apply-only round (`applyOnlyRound`).
 
+Before any JEV question (since 2026-09-26, API ea257c0a): when the remaining
+Energy, after the model's hand-off reserve, cannot cover two typical rounds
+(one read and one edit, `LUMINE_MIN_ROUNDS_FOR_PROJECT_EDIT`) on the chosen
+model but can on a lighter one, the run does not start and shows the
+switch-model card; nothing is spent. Lineage metadata records
+`tooTightForAnEdit`, `roundsOnThisModel` and `lighterModelRounds`. The
+composer checks the same arithmetic up front (model options carry
+`handoffReserveEnergyUnits`): it offers a one-tap switch, and it disables
+sending with an explanation when no model can afford even one step.
+
 Every UTC day in `lumine admin energy-budget --json` now carries `pacing`.
 Report in **"Insights for Mikey"** in every full run, for the last completed
 day and the in-progress day while the feature is new: