@stage5/lumine 0.2.89 → 0.2.91

package/lib/admin.js

@@ -138,6 +138,8 @@ function readBuildReviewContextFile(filePath) {
 
 const MAX_REWARD_CONFIG_FILE_BYTES = 256 * 1024;
 const REWARD_REVIEW_STATUSES = ["pending", "approved", "all"];
+const CHAT_REPORT_STATUSES = ["open", "reviewing", "resolved", "dismissed"];
+const CHAT_REPORT_LIST_STATUSES = ["pending", ...CHAT_REPORT_STATUSES, "all"];
 const REWARD_REVIEW_DECISIONS = ["approve", "reject", "revoke"];
 const REWARD_PROPOSAL_MAX_FILES = 500;
 const REWARD_PROPOSAL_MAX_BYTES = 5 * 1024 * 1024;
@@ -648,6 +650,29 @@ export async function adminCommand(options) {
       },
     };
   }
+  if (operation.name === "chat-reports.export" && operation.evidenceDir) {
+    // The package goes to disk only; the printed result keeps paths, sizes
+    // and hashes, never the evidence itself.
+    const written = writeEvidencePackage({
+      directory: operation.evidenceDir,
+      files: result?.data?.files,
+    });
+    const { files: _files, manifest: _manifest, ...summary } = result?.data || {};
+    if (
+      summary.manifestSha256 &&
+      summary.manifestSha256 !== written.manifestSha256
+    ) {
+      const error = new Error(
+        "The written manifest.json does not match the hash the server recorded. Export again into a new directory.",
+      );
+      error.code = "LUMINE_ADMIN_EVIDENCE_HASH_MISMATCH";
+      throw error;
+    }
+    result = {
+      ...result,
+      data: { ...summary, evidenceDirectory: written.directory, files: written.files },
+    };
+  }
   if (operation.name === "news.claim") {
     const artifacts = writeNewsClaimArtifacts({
       result,
@@ -1295,6 +1320,86 @@ function noActiveRunError() {
   return error;
 }
 
+function requireChatSafetyNote(value) {
+  const note = String(value || "").trim();
+  if (!note) {
+    throw cliValidationError(
+      "Say why with --note <text>; it is kept in the safety audit trail.",
+    );
+  }
+  if (note.length > 2000) {
+    throw cliValidationError("--note must be at most 2000 characters.");
+  }
+  return note;
+}
+
+function parseIdList(value, label) {
+  const ids = String(value || "")
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => parseRequiredInteger(part, label, 1));
+  if (!ids.length) throw cliValidationError(`${label} needs at least one id.`);
+  return Array.from(new Set(ids));
+}
+
+// Writes a child-safety evidence package into a new or empty private
+// directory and checks every written file against the server's SHA-256
+// manifest, so what lands on disk is exactly what the server hashed.
+export function writeEvidencePackage({ directory, files }) {
+  const list = Array.isArray(files) ? files : [];
+  const manifestFile = list.find((file) => file?.path === "manifest.json");
+  if (!manifestFile) {
+    throw cliValidationError("The evidence package has no manifest.json.");
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(String(manifestFile.content || ""));
+  } catch {
+    throw cliValidationError("The evidence manifest is not valid JSON.");
+  }
+  let written;
+  try {
+    written = writeRewardReviewSnapshot({ directory, files: list });
+  } catch (error) {
+    error.message = String(error.message || "").replaceAll("--dir", "--out");
+    throw error;
+  }
+  const sha = (text) => createHash("sha256").update(text).digest("hex");
+  const mismatches = [];
+  for (const entry of manifest.files || []) {
+    const target = path.join(written.directory, entry.path);
+    const actual = existsSync(target) ? sha(readFileSync(target)) : "missing";
+    if (actual !== entry.sha256) mismatches.push(entry.path);
+  }
+  const listed = new Set((manifest.files || []).map((entry) => entry.path));
+  for (const file of list) {
+    if (file.path !== "manifest.json" && !listed.has(file.path)) {
+      mismatches.push(file.path);
+    }
+  }
+  if (mismatches.length) {
+    const error = new Error(
+      `The evidence package in ${written.directory} does not match its manifest (${mismatches.join(", ")}). Do not hand it over; export again into a new directory.`,
+    );
+    error.code = "LUMINE_ADMIN_EVIDENCE_HASH_MISMATCH";
+    throw error;
+  }
+  return {
+    directory: written.directory,
+    manifestSha256: sha(readFileSync(path.join(written.directory, "manifest.json"))),
+    files: written.files.map((file) => ({
+      path: file.path.replace(/^\//, ""),
+      bytes: file.bytes,
+      sha256:
+        file.path === "/manifest.json"
+          ? null
+          : (manifest.files || []).find((entry) => `/${entry.path}` === file.path)
+              ?.sha256 || null,
+    })),
+  };
+}
+
 export function parseAdminOperation(options) {
   const [namespace = "", action = "", target = "", extra = ""] =
     options.positional;
@@ -1594,6 +1699,159 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "chat-reports" || namespace === "chat-report") {
+    // Members' in-chat message reports. Like reward reviews they are handled
+    // any time, never inside a daily-run lease; recording an outcome only
+    // annotates the report and never acts against a member.
+    if (!action || action === "list") {
+      return readOperation(
+        "chat-reports.list",
+        withQuery("/cli/admin/chat-reports", {
+          status: parseChoice(
+            options.adminStatus || "pending",
+            "--status",
+            CHAT_REPORT_LIST_STATUSES,
+          ),
+          beforeId: options.adminCursor
+            ? parseRequiredInteger(options.adminCursor, "--cursor", 1)
+            : "",
+          limit: options.limit,
+        }),
+        { requiresRun: false },
+      );
+    }
+    if (action === "show" || action === "get") {
+      const reportId = parseRequiredInteger(target, "Chat report ID", 1);
+      return readOperation(
+        "chat-reports.show",
+        `/cli/admin/chat-reports/${reportId}`,
+        { requiresRun: false },
+      );
+    }
+    if (action === "set") {
+      const reportId = parseRequiredInteger(target, "Chat report ID", 1);
+      const status = parseChoice(
+        options.adminStatus,
+        "--status",
+        CHAT_REPORT_STATUSES,
+      );
+      const note = String(options.note || "").trim();
+      if (!note) {
+        throw cliValidationError(
+          "Record what was decided or done with --note <text>.",
+        );
+      }
+      if (note.length > 2000) {
+        throw cliValidationError("--note must be at most 2000 characters.");
+      }
+      return writeOperation(
+        "chat-reports.set",
+        "PUT",
+        `/cli/admin/chat-reports/${reportId}`,
+        { status, note },
+        { requiresRun: false, reportId },
+      );
+    }
+    // Child-safety holds, evidence export and suspension (owner only; the
+    // API admits only the owner's login). A hold keeps a protected copy of
+    // anything the held conversation or members delete or edit.
+    if (action === "hold") {
+      const note = requireChatSafetyNote(options.note);
+      const body = { note };
+      if (target) body.reportId = parseRequiredInteger(target, "Chat report ID", 1);
+      if (options.adminUser) {
+        body.userIds = parseIdList(options.adminUser, "--user");
+      }
+      if (options.adminChannel) {
+        body.channelId = parseRequiredInteger(options.adminChannel, "--channel", 1);
+      }
+      if (!body.reportId && !body.userIds && !body.channelId) {
+        throw cliValidationError(
+          "Usage: lumine admin chat-reports hold <report-id> | --user <id>[,<id>] [--channel <id>] | --channel <id> --note <why>.",
+        );
+      }
+      return writeOperation(
+        "chat-reports.hold",
+        "POST",
+        "/cli/admin/chat-reports/holds",
+        body,
+        { requiresRun: false },
+      );
+    }
+    if (action === "release") {
+      const holdId = parseRequiredInteger(
+        target || options.adminHold,
+        "Safety hold ID",
+        1,
+      );
+      return writeOperation(
+        "chat-reports.release",
+        "PUT",
+        `/cli/admin/chat-reports/holds/${holdId}/release`,
+        { note: requireChatSafetyNote(options.note) },
+        { requiresRun: false, holdId },
+      );
+    }
+    if (action === "list-holds" || action === "holds") {
+      return readOperation(
+        "chat-reports.list-holds",
+        withQuery("/cli/admin/chat-reports/holds", {
+          status: parseChoice(
+            options.adminStatus || "active",
+            "--status",
+            ["active", "released", "all"],
+          ),
+        }),
+        { requiresRun: false },
+      );
+    }
+    if (action === "export") {
+      const out = String(options.out || "").trim();
+      if (!out) {
+        throw cliValidationError(
+          "Pass a new or empty directory with --out <dir> for the evidence package.",
+        );
+      }
+      if (target && options.adminHold) {
+        throw cliValidationError("Export either one report ID or one --hold <id>, not both.");
+      }
+      const body = target
+        ? { reportId: parseRequiredInteger(target, "Chat report ID", 1) }
+        : options.adminHold
+          ? { holdId: parseRequiredInteger(options.adminHold, "--hold", 1) }
+          : null;
+      if (!body) {
+        throw cliValidationError(
+          "Usage: lumine admin chat-reports export <report-id> | --hold <hold-id> --out <dir>.",
+        );
+      }
+      // A POST because the export is audited server-side (who, when, the
+      // manifest hash); it changes no member data.
+      return writeOperation(
+        "chat-reports.export",
+        "POST",
+        "/cli/admin/chat-reports/export",
+        body,
+        { requiresRun: false, evidenceDir: out },
+      );
+    }
+    if (action === "suspend") {
+      return writeOperation(
+        "chat-reports.suspend",
+        "POST",
+        "/cli/admin/chat-reports/suspend",
+        {
+          userId: parseRequiredInteger(options.adminUser || target, "--user", 1),
+          note: requireChatSafetyNote(options.note),
+        },
+        { requiresRun: false },
+      );
+    }
+    throw cliValidationError(
+      "Usage: lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] | show <id> | set <id> --status reviewing|resolved|dismissed|open --note <decision> | hold <report-id>|--user <id>|--channel <id> --note <why> | release <hold-id> --note <why> | list-holds [--status active|released|all] | export <report-id>|--hold <id> --out <dir> | suspend --user <id> --note <why>.",
+    );
+  }
+
   if (namespace === "reward-activity" || namespace === "reward-telemetry") {
     // Read-only claim telemetry for the daily run: no run lease, no mutation.
     const date = options.adminDate
@@ -4037,8 +4295,53 @@ function printRewardActivity(data) {
   );
 }
 
+function describeSafetyHold(hold) {
+  const covers = [
+    ...(hold.channelIds || []).map((id) => `channel ${id}`),
+    ...(hold.userIds || []).map((id) => `user ${id}`),
+  ].join(", ");
+  const placed = hold.placedAt
+    ? new Date(hold.placedAt * 1000).toISOString()
+    : "unknown";
+  return `Hold #${hold.id} ${hold.status} (${hold.source}, placed ${placed}${hold.placedByUserId ? ` by user ${hold.placedByUserId}` : " automatically"}): ${covers || "nothing"}; reports ${(hold.reportIds || []).map((id) => `#${id}`).join(", ") || "none"}; ${hold.preservedRecords || 0} preserved cop${hold.preservedRecords === 1 ? "y" : "ies"}. ${hold.reason || ""}`;
+}
+
+function printChatSafetyResult({ operation, data }) {
+  if (operation.name === "chat-reports.hold" || operation.name === "chat-reports.release") {
+    if (data.hold) console.log(describeSafetyHold(data.hold));
+    return true;
+  }
+  if (operation.name === "chat-reports.list-holds") {
+    const holds = data.holds || [];
+    console.log(`${holds.length} ${data.filter || ""} safety hold(s).`);
+    for (const hold of holds) console.log(`  ${describeSafetyHold(hold)}`);
+    return true;
+  }
+  if (operation.name === "chat-reports.export") {
+    console.log(
+      `Evidence package written to ${data.evidenceDirectory} (${(data.files || []).length} files, hashes verified).`,
+    );
+    console.log(`manifest.json SHA-256: ${data.manifestSha256}`);
+    for (const file of data.files || []) {
+      console.log(`  ${file.path}  ${file.bytes} bytes${file.sha256 ? `  ${file.sha256}` : ""}`);
+    }
+    console.log(
+      "Keep this folder private. Give it only to police or child-protection staff handling the case, and write the manifest hash in your records.",
+    );
+    return true;
+  }
+  if (operation.name === "chat-reports.suspend") {
+    console.log(
+      `${data.user?.username || "user"} (user ${data.user?.id}) ${data.alreadySuspended ? "was already" : "is now"} suspended (full ban: signed out, cannot use the site).${(data.holdIds || []).length ? ` Safety hold(s): #${data.holdIds.join(", #")}.` : " No safety hold covers this account yet; place one with chat-reports hold."}`,
+    );
+    return true;
+  }
+  return false;
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (printChatSafetyResult({ operation, data })) return;
   if (operation.name === "reward-activity.report") {
     printRewardActivity(data);
     return;

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) : "",
@@ -2570,6 +2578,9 @@ export function parseArgs(args) {
     adminBucketId: raw.bucketId ? String(raw.bucketId) : "",
     adminLabel: raw.label ? String(raw.label) : "",
     adminUserIds: raw.userIds ? String(raw.userIds) : "",
+    adminUser: raw.user ? String(raw.user) : "",
+    adminChannel: raw.channel ? String(raw.channel) : "",
+    adminHold: raw.hold ? String(raw.hold) : "",
     adminEmail: raw.email ? String(raw.email) : "",
     adminMode: raw.mode ? String(raw.mode) : "",
     adminType: raw.type ? String(raw.type) : "",
@@ -2939,9 +2950,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>
@@ -2973,6 +2987,14 @@ export function printHelp() {
   lumine admin sponsor integrity review <case-id> --decision clear|hold|flag|disqualify [--note <evidence>] [--json]
   lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] [--json]
   lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
+  lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] [--json]
+  lumine admin chat-reports show <report-id> [--json]   (reported message snapshot + surrounding context)
+  lumine admin chat-reports set <report-id> --status reviewing|resolved|dismissed|open --note <what was decided> [--json]
+  lumine admin chat-reports hold <report-id> | --user <id>[,<id>] [--channel <id>] | --channel <id> --note <why> [--json]   (child-safety evidence hold)
+  lumine admin chat-reports release <hold-id> --note <why> [--json]
+  lumine admin chat-reports list-holds [--status active|released|all] [--json]
+  lumine admin chat-reports export <report-id> | --hold <hold-id> --out <new-dir> [--json]   (evidence package + SHA-256 manifest)
+  lumine admin chat-reports suspend --user <id> --note <why> [--json]   (full ban: signs them out)
   lumine admin reward-review show <review-id> [--dir <path>] [--json]
   lumine admin reward-review approve <review-id> [--config <rules.json>] [--reason <text>] [--json]   (approval publishes the approved version)
   lumine admin reward-review propose <review-id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--json]

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,10 +234,11 @@ 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"?,
-    "rules": [{ "id", "title", "xp", "coins", "verifier": "numeric-quiz" | "completion",
+    "rules": [{ "id", "title", "howTo"? (how to earn it, in the player's words), "xp", "coins", "verifier": "numeric-quiz" | "completion",
                 "maxAttempts"?, "retry"?: { "xpPercent", "coinsPercent", "paidAttempts"? }, "minSeconds"? (completion), "progression"?: "dated" | "until-earned" (quiz) }] }
 Questions and answer keys never go in project files; they belong in the sheet.`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.89",
+  "version": "0.2.91",
   "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.55.0
-Updated: 2026-09-24
-Generated: 2026-09-24T11:41:42.326Z
+Version: 1.60.0
+Updated: 2026-09-27
+Generated: 2026-09-27T07:17:40.033Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -36,7 +36,7 @@ Generated: 2026-09-24T11:41:42.326Z
 - The creator's agent designs the rewards. Declare the economy in a project file `rewards.json` at the root: budgets (userDailyXP, userDailyCoins, optional userDailyClaims; there is no app-wide daily or lifetime budget, only what one learner can earn per day) and rules [{ id, title, xp, coins, verifier: 'numeric-quiz' | 'completion', maxAttempts?, retry?: { xpPercent, coinsPercent, paidAttempts? }, minSeconds? (completion), progression?: 'dated' | 'until-earned' (quiz) }]. Wire the matching Twinkle.rewards calls with those literal rule ids. Questions and answer keys NEVER go in project files (published source is readable by every player): quiz rules get them from the private question sheet uploaded with `lumine rewards sheet <file.json>` ({ rules: { <ruleId>: { questions?, sets? } } }); `lumine rewards check` validates both together. A review request freezes the code and proposes rewards.json merged with the sheet; the administrator reads the code, checks the amounts and whether the app is exploitable, may change any amount, and approves. Creators are kids and teens: show approval status and one Send for review action; do not ask them to fill in technical forms. Every code update that retains rewards needs a new approval before publishing. Removing the SDK automatically clears its gate. Apps read amounts, tries and sets from getStatus, never from their own file.
 - Verifiers: 'numeric-quiz' pays for server-checked numeric answers (retry share, attempt limits, dated sets or until-earned sets that stay up until somebody earns them, after-answer guides). 'completion' pays when the app reports an activity finished — a cleared stage, a finished round — at least minSeconds after start({ ruleId }); the server checks only the elapsed time, once per learner per site day (UTC midnight), and the budgets. Call start when the activity begins and claim({ challengeId }) with no answers when it ends; keep completion amounts and userDailyXP small enough that a player scripting the calls would not matter, because nothing else is verified.
 - Numeric quiz answers are verified on the server; client scores, privateDb state, timers and completion booleans are not verified reward evidence. Limits reset at UTC midnight. Rules are earned once per viewer per UTC day; attempt limits and retry payouts come from the approved rule. Challenges expire at the UTC day boundary. Budgets apply across release changes.
-- Optional reward rule controls: maxLifetimeClaims caps one learner’s receipts for that rule across every day and release; completionProof: classic-tower-v1 requires a server-simulated Classic Tower finish in addition to minSeconds. These are server-enforced controls. Existing completion rules without completionProof still verify elapsed time only. Registered proof profiles also include breadface-v1, breadface-v2 and breadface-v3 (server-simulated Breadface inputs; each is one reviewed release's exact physics, chosen by the reviewer) study-record-v1 (a private study record reviewed by JEV, billed to the learner’s AI Energy), and Groove Lab's groove-lab-song-v1 (a song the learner published today, checked on the server for length, notes and originality) and groove-lab-heard-v1 (three established accounts finished the learner's songs today). Profiles are platform-owned; an app cannot invent a verifier or authorize its own reward.
+- Optional reward rule controls: maxLifetimeClaims caps one learner’s receipts for that rule across every day and release; completionProof: classic-tower-v1 requires a server-simulated Classic Tower finish in addition to minSeconds. These are server-enforced controls. Existing completion rules without completionProof still verify elapsed time only. Registered proof profiles also include breadface-v1, breadface-v2 and breadface-v3 (server-simulated Breadface inputs; each is one reviewed release's exact physics, chosen by the reviewer) study-record-v1 (a private study record reviewed by JEV, billed to the learner’s AI Energy), and Groove Lab's groove-lab-song-v1 (a song the learner published today, checked on the server for length, notes and originality) and groove-lab-heard-v1 (three established accounts finished the learner's songs today), Ashen Vigil's vigil-guest-coplay-v1 (a new guest spent 10 minutes with the learner in a private world room, measured by the world relay; each guest pays once) and minecraft-first-link-v1 (the learner is the first Twinkle account ever linked to that Minecraft player; each player pays once). Profiles are platform-owned; an app cannot invent a verifier or authorize its own reward.
 
 ## AI decision design
 - When planning a new app or an improvement, consider whether model-based judgments would materially improve the requested experience. Twinkle.ai.decide runs JEV, a model for narrow decisions over supplied text or structured state. Potential uses include interpreting a player's request to an NPC, choosing among legal game actions, classifying user content, ranking supplied candidates, and adapting an activity to evidence about the learner. These are examples to reason from, not a keyword checklist or a requirement to add AI to every app.
@@ -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.
@@ -593,9 +608,10 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Returns subject ids plus rootType/rootId metadata for picker UIs. Empty queries return an empty result set.
   - Example: const { subjects } = await Twinkle.subjects.search({ query: searchText, limit: 12 });
 - async getSubject(subjectId) | scopes: content:read
-  - Returns: { subject: { id, title, description, filePath, fileName, fileSize, thumbUrl, secretAnswer, secretAttachment, timeStamp, userId, username, profilePicUrl, rootType, rootId, rewardLevel } }
+  - Returns: { subject: { id, title, description, filePath, fileName, fileSize, thumbUrl, secretAnswer, secretAttachment, hasSecretAnswer, hasSecretAttachment, secretShown, timeStamp, userId, username, profilePicUrl, rootType, rootId, rewardLevel } }
   - Returns full detail for a single subject, including uploader info and attachments.
   - Any subject can be fetched (not limited to viewer's own).
+  - secretAnswer and secretAttachment follow the site's rule: they are filled only when the viewer posted the subject or has responded to it (secretShown true). Otherwise they are null and hasSecretAnswer / hasSecretAttachment say a secret exists.
 - async getSubjectComments(subjectId, { limit, cursor } = {}) | scopes: content:read
   - Returns: { comments: [{ id, content, filePath, fileName, fileSize, thumbUrl, timeStamp }], cursor? }
   - Returns only the current viewer's own comments on the given subject.
@@ -646,6 +662,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Lists completed existing AI Stories newest first by default; order:'oldest' is allowed only with difficulty, type, and topicKey for chronological book pages.
   - Use difficulty with type and topicKey to load one exact AI Story book without scanning the full corpus in the iframe.
   - Filter with hasImage or hasQuestions when building visual galleries or quiz apps.
+  - A story the signed-in viewer is still playing (an AI Story attempt they have not submitted) comes back without answerIndex on its questions; the site reveals that key only after the viewer submits.
   - Example: const { stories } = await Twinkle.aiStories.list({ difficulty: 1, type: 'science', topicKey: 'Astronomy', order: 'oldest', limit: 20 });
 - async chapters({ limit, cursor, groupBy, difficulty, type, topicKey, storyBy, isListening, userId, hasImage, hasQuestions } = {}) | scopes: content:read
   - Returns: Default (groupBy:'topicKey'): { chapters: [{ difficulty, type, topicKey, title, sampleTopic, storyCount, readingCount, listeningCount, imageCount, questionCount, latestStoryId, latestTimeStamp }], cursor?, pagination, filters }. groupBy:'type': { books: [{ difficulty, type, title, sampleTopic, chapterCount, storyCount, readingCount, listeningCount, imageCount, questionCount, latestStoryId, latestTimeStamp }], ... } — one row per (level, topic) book. groupBy:'author': { authors: [{ storyBy, title, bookCount, chapterCount, storyCount, minDifficulty, maxDifficulty, latestStoryId }], ... } — one row per generating model (the story's author); an index-only landing, so it omits media counts (use a scoped books/chapters call for those).
@@ -661,29 +678,41 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Searches completed existing AI Stories by topic/story text.
   - Use difficulty, type, and topicKey to search within one book of the AI Story corpus; order:'oldest' is rejected without all three filters.
   - Returned questions are normalized to an array even when stored as JSON text.
+  - A story the signed-in viewer is still playing (an AI Story attempt they have not submitted) comes back without answerIndex on its questions; the site reveals that key only after the viewer submits.
   - Example: const { stories } = await Twinkle.aiStories.search({ query: searchText, difficulty: 2, type: 'history', topicKey: 'Ancient Rome', order: 'oldest', limit: 12 });
 - async get(storyId) | scopes: content:read
   - Returns: { story: { id, contentType, contentId, topic, topicKey, type, story, explanation, difficulty, isListening, imagePath, imageUrl, audioPath, audioUrl, questions, questionsBy, hasImage, hasQuestions, userId, username, profilePicUrl, timeStamp } }
   - Fetch one completed existing AI Story by id, including story text for passage typing, media URLs, and normalized questions when available.
   - Fetches one completed existing AI Story by id.
+  - A story the signed-in viewer is still playing (an AI Story attempt they have not submitted) comes back without answerIndex on its questions; the site reveals that key only after the viewer submits.
   - This namespace is read-only and does not generate new AI Stories.
   - Example: const { story } = await Twinkle.aiStories.get(storyId);
 
 ### Twinkle.grammarbles
 - async listQuestions({ level, limit, cursor } = {}) | scopes: content:read
-  - Returns: { questions: [{ id, level, rating, question, choices, answerIndex, correctChoice, correctChoiceKey, isChecked, explanation }], cursor?, pagination: { level, limit, hasMore, nextCursor } }
-  - Read public Grammarbles questions and answers by level with rating/id cursor pagination.
-  - Questions are public Grammarbles training data and include the canonical answer.
+  - Returns: { questions: [{ id, level, rating, question, choices, isChecked }], cursor?, pagination: { level, limit, hasMore, nextCursor } }
+  - Read Grammarbles questions and choices by level with rating/id cursor pagination; answers stay on the server.
+  - Questions do not include the answer, answerIndex or explanation: Grammarbles is a rewarded game, so its key stays on the server. Check a pick with Twinkle.grammarbles.checkAnswer.
+  - Each question's choices come in a fixed order; pass the index of the picked choice in that order to checkAnswer.
   - level is clamped from 1 through 5.
   - Pagination is stable by rating then id. Pass cursor from the previous response to load more questions in the same level.
   - This method does not expose daily attempt state, XP, coins, or daily-task progression.
   - Example: const page = await Twinkle.grammarbles.listQuestions({ level: 3, limit: 100 }); const question = page.questions[Math.floor(Math.random() * page.questions.length)];
+- async checkAnswer({ questionId, choiceIndex }) | scopes: content:read
+  - Returns: { questionId, choiceIndex, isCorrect, explanation }
+  - Check one Grammarbles pick on the server: right or wrong, plus the review explanation on a right pick.
+  - choiceIndex is 0-3 in the order listQuestions returned the choices.
+  - The right position is never returned. Let the learner try again until the pick is right, as Grammarbles itself does.
+  - explanation is null unless the pick is right and the question has a reviewed explanation.
+  - Each viewer has a daily allowance of answer checks (500 per UTC day); past it the call fails with code grammarbles_check_limit.
+  - Checking pays nothing and does not touch daily Grammarbles attempts, XP, coins, or daily tasks.
+  - Example: const { isCorrect, explanation } = await Twinkle.grammarbles.checkAnswer({ questionId: question.id, choiceIndex: pickedIndex }); if (!isCorrect) showTryAgain(); else showCorrect(explanation);
 - async getMyQuestionHistory({ level, limit, cursor } = {}) | scopes: content:read
   - Returns: { attempts: [{ id, questionId, level, grade, gradeRank, isCorrect, attemptNumber, timeStamp }], cursor?, pagination: { level, limit, hasMore, nextCursor } }
   - Read the signed-in viewer's real Grammarbles attempt rows for trainer filtering.
   - Returns real Grammarbles attempt outcome rows for the signed-in viewer, newest first.
   - History rows intentionally omit choice indexes because real Grammarbles choices are shuffled per run and the per-run shuffle order is not persisted.
-  - Use Twinkle.grammarbles.listQuestions for canonical question text, choices, and answers.
+  - Use Twinkle.grammarbles.listQuestions for question text and choices, and Twinkle.grammarbles.checkAnswer to check a pick.
   - Use app-private history in Twinkle.privateDb for trainer-only results, and combine it with this method only when the viewer chooses to include real Grammarbles history.
   - This method is read-only and does not submit, cancel, or mutate daily Grammarbles attempts.
   - Example: const history = await Twinkle.grammarbles.getMyQuestionHistory({ level: selectedLevel, limit: 500 }); const answeredIds = new Set(history.attempts.map((attempt) => attempt.questionId));
@@ -787,19 +816,20 @@ 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', op, online, isZero, twinkle: { userId, username } | null, ...owner: groups, banned, protected, firstSeenAt, lastSeenAt | ...others: seen: 'online'|'today'|'week'|'month'|'older'|null }], roles }
+  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', op, online, isZero, twinkle: { userId, username } | null, ...owner: groups, banned, protected, firstSeenAt, lastSeenAt, endorsements: [{ voucherName, voucherUuid, endorsedAt }] | ...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.
+  - endorsements (owner view only) lists who backed this player's Builder application: a moderator or anyone above typed /vouch for a player already on Twinkle. voucherUuid is the voucher's Minecraft uuid (null when endorsed from the app or console); endorsedAt is an ISO time. Empty when there are none, or when the server's vouch list could not be read.
   - 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.
   - 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.
+  - role is visitor, member, builder, moderator, or a Partner rank above moderator: associate, senior_associate, partner, senior_partner (each keeps every moderator power). A promotion also sends the player's linked Twinkle account a DM, and the player gets a title and perks list in game. 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' });
 - async getChat({ since } = {}) | scopes: content:read
@@ -846,7 +876,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - 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 } | null }
+  - 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.
@@ -863,13 +893,13 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - 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: the server owner, and any signed-in viewer with a linked Minecraft account (Twinkle.minecraft.createLinkCode + /link); others get 403 minecraft_not_linked. Designs are private unless visibility is 'public'. Players have a limit on how many designs they keep.
+  - 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.
+  - 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 }
@@ -923,6 +953,23 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - 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 getRecruitTours() | scopes: content:read
+  - Returns: { enabled, title, landmarks: [{ id, name, world, x, z, radius }], requirements: { playHours, days }, tours: [{ uuid, name, introducerUuid, introducerName, startedAt, completedAt, visited: [landmarkId], playSeconds, days }] }
+  - Recruit tours: each player someone brought to the server, who brought them, and their progress (landmarks visited, hours and days played). A completed tour is one recruiter point for the introducer.
+  - Everyone can read it; one shared copy refreshes every 15 seconds.
+  - The landmark list and requirements come from the server's config, so show them from here rather than hard-coding them.
+  - Example: const { landmarks, tours } = await Twinkle.minecraft.getRecruitTours();
+- async startRecruitTour({ uuid, introducerUuid }) | scopes: content:write
+  - Returns: { uuid, introducerUuid }
+  - Server owner only: record that introducerUuid brought player uuid to the server and start that player's landmark tour (a quest list in game).
+  - 403 minecraft_roles_forbidden for anyone but the server owner.
+  - 400 minecraft_already_credited when someone else was already credited; minecraft_self_introduced for the same player; minecraft_unknown_player when either never joined.
+  - Example: await Twinkle.minecraft.startRecruitTour({ uuid: recruit.uuid, introducerUuid: friend.uuid });
+- async cancelRecruitTour({ uuid }) | scopes: content:write
+  - Returns: { removed }
+  - Server owner only: remove a player's recruit tour (a mistaken credit).
+  - 403 minecraft_roles_forbidden for anyone but the server owner.
+  - Example: await Twinkle.minecraft.cancelRecruitTour({ uuid });
 - 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.
@@ -940,12 +987,80 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - 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
@@ -1220,12 +1335,13 @@ world.updatePresence({ x, y, z, facing });
 
 ### Twinkle.rewards
 - await Twinkle.rewards.getStatus() | scopes: rewards:claim
-  - Returns: { mode: "live", dayKey, userDailyClaims, claimsToday, budgets: { userDailyXP, userDailyCoins }, rules: [{ id, title, xp, coins, verifier: "numeric-quiz" | "completion", minSeconds?, progression?, retryReward: { xp, coins }, maxAttempts, available, setKey, questionCount }], challenges: [{ challengeId, ruleId, attempts, attemptsRemaining, state: "open" | "finished" | "earned", setKey, questions: [{ prompt, hint?, guide? }] }], history: [{ ruleId, xp, coins, attempt, createdAt }], balances: { xp, coins } } | { mode: "preview", dayKey?, rules, challenges: [], history: [], balances?, problems?: string[], message }
+  - Returns: { mode: "live", dayKey, userDailyClaims, claimsToday, budgets: { userDailyXP, userDailyCoins }, rules: [{ id, title, howTo?, xp, coins, verifier: "numeric-quiz" | "completion", minSeconds?, progression?, retryReward: { xp, coins }, maxAttempts, available, setKey, questionCount }], challenges: [{ challengeId, ruleId, attempts, attemptsRemaining, state: "open" | "finished" | "earned", setKey, questions: [{ prompt, hint?, guide? }] }], history: [{ ruleId, xp, coins, attempt, createdAt }], balances: { xp, coins } } | { mode: "preview", dayKey?, rules, challenges: [], history: [], balances?, problems?: string[], message }
   - Read canonical earning rules (without answer keys), today’s started challenges, today’s receipts and balances. Drafts return preview mode: for the app's owner the rules come from the draft's own rewards.json and question sheet (problems lists what is still wrong with them); anyone else sees no rules. Unapproved or revoked published releases return an error.
   - rules[].available is false on a site day (UTC) the reviewer scheduled no questions for; show the rule as not available instead of starting it. xp/coins are the first-try amounts; retryReward is what a correct answer pays after a wrong one (equal to xp/coins unless the reviewer set a retry share). maxAttempts null means unlimited wrong answers until the site's daily reset (UTC midnight, 9:00 AM in Korea). retry.paidAttempts, when set, is the last attempt number a correct answer is still paid on: a later correct answer is recorded as solved (receipt xp 0, coins 0) and pays nothing — tell the learner before they pass it.
   - challenges lists challenges this viewer already started today with their questions, so an app can resume after a reload without calling start. A question's guide (reviewer-approved JSON teaching content: explanation, interactive-model configuration) is present only once the viewer has answered at least once, right or wrong; render it as the after-attempt lesson. claimsToday against userDailyClaims (null = uncapped) tells whether another bounty can still pay today.
   - Under progression 'until-earned' the same set stays up day after day until somebody earns it; setKey names the set currently up. Completion rules are always available and have questionCount 0.
   - Rules may set maxLifetimeClaims, a per-learner limit for that rule across days and releases. rules[].lifetime contains the server-confirmed limit and remaining claims. App storage never enforces this limit.
+  - howTo is the rule's optional plain-words steps from rewards.json (up to 300 characters, e.g. "Save a new design of at least 64 blocks in Designs"). The Earn page shows it under the title; show it in the app's own rewards list too so players always know exactly what earns each reward.
 - await Twinkle.rewards.getReceipt({ challengeId }) | scopes: rewards:claim
   - Returns: { mode: "live", status: "awarded" | "pending" | "expired" | "not_found", receipt: { id, challengeId, ruleId, reviewId, artifactVersionId, dayKey, xp, coins, attempt, createdAt } | null, balances: { xp, coins } } | { mode: "preview", status: "not_found", receipt: null, message }
   - Read an existing receipt for this app and signed-in viewer by server-issued challengeId, including previous UTC days and previous approved versions. Requires the current approved published release and runtime grant; a stale frame must reload first. Never awards, retries a claim, returns answer keys, or restores removed rewards permission.
@@ -1236,7 +1352,7 @@ world.updatePresence({ x, y, z, facing });
   - Errors: build_reward_not_scheduled when the rule has no questions for today; build_reward_daily_claims_reached when the viewer already earned today’s cap. attemptsRemaining is null for unlimited rules.
   - For a completion rule call start when the activity begins (the moment the stage starts); the challenge's age is what the claim is measured against. In preview mode start also works for the owner (a stateless simulation).
   - For completionProof: classic-tower-v1, start also returns completion { profile, token, maxFrames, completed, failed }. A new start resets only the simulated climb to its canonical spawn; it cannot reset daily or lifetime rewards. Record inputs from the first physics frame. The completion token is bound to the viewer, challenge, rule and published release.
-  - For breadface-v1, breadface-v2 and breadface-v3, pass the zero-based canonical levelIndex. Record [dt, inputBits] from the first physics frame; start returns its server token and maxFrames. For study-record-v1, start returns completion { profile, usesAiEnergy: true }; there is no client-authored proof token. For groove-lab-song-v1 and groove-lab-heard-v1, start returns completion { profile }; there is no progress step.
+  - For breadface-v1, breadface-v2 and breadface-v3, pass the zero-based canonical levelIndex. Record [dt, inputBits] from the first physics frame; start returns its server token and maxFrames. For study-record-v1, start returns completion { profile, usesAiEnergy: true }; there is no client-authored proof token. For groove-lab-song-v1, groove-lab-heard-v1, vigil-guest-coplay-v1 and minecraft-first-link-v1, start returns completion { profile }; there is no progress step.
 - await Twinkle.rewards.progress({ challengeId, completionToken?, frames?, record?, requestId? }) | scopes: rewards:claim
   - Returns: { mode: "live" | "preview", completion: { profile, token?, completed, failed?, decision?, message?, maxFrames? }, aiUsagePolicy? }
   - Verify a bounded batch of inputs for an approved server-simulated climb.
@@ -1252,7 +1368,7 @@ world.updatePresence({ x, y, z, facing });
   - A wrong answer within two seconds of the previous one is refused with build_reward_throttled (HTTP 429) and does not count; wait for the person to try again rather than retry-looping.
   - Completion rules take no answers: claim({ challengeId }) when the activity is finished. build_reward_too_fast (HTTP 409) means fewer than minSeconds passed since start; show nothing and let play continue. In preview mode the receipt carries preview: true and nothing is paid.
   - A completionProof rule also requires the signed completionToken from a successful rewards.progress response. The server simulates the registered game physics and must reach the goal. A timer, forged position, client win flag, altered inventory or token from another viewer, challenge or release cannot authorize payment. maxLifetimeClaims is enforced from receipts in the same award transaction. build_reward_lifetime_claims_reached means all rewards for this rule have been collected; do not retry it.
-  - For study-record-v1, the server verifies the settled private review row and its viewer, app, exact release, challenge and day binding. It never trusts the client’s decision, requested award amount or AI answer. Each successful daily study record is claimable once; display only canonical receipt/balances. For groove-lab-song-v1, pass completionToken as the published song's sharedDb entry id; for groove-lab-heard-v1, pass none. The server reads the app's own groove-lab-songs, groove-lab-song-parts and groove-lab-listens rows and refuses with build_reward_completion_proof_required and a plain reason when the song or listeners do not qualify.
+  - For study-record-v1, the server verifies the settled private review row and its viewer, app, exact release, challenge and day binding. It never trusts the client’s decision, requested award amount or AI answer. Each successful daily study record is claimable once; display only canonical receipt/balances. For groove-lab-song-v1, pass completionToken as the published song's sharedDb entry id; for groove-lab-heard-v1, pass none; for vigil-guest-coplay-v1, pass the guest's world guestId (from world events) or the co-play record id; for minecraft-first-link-v1, pass nothing or the Minecraft UUID to use. The server reads the app's own groove-lab-songs, groove-lab-song-parts and groove-lab-listens rows and refuses with build_reward_completion_proof_required and a plain reason when the song or listeners do not qualify.
 - await Twinkle.rewards.getLeaderboard({ metric?: "xp" | "coins", period?: "day" | "week" | "all", limit? }) | scopes: rewards:claim
   - Returns: { mode: "live", metric, period, limit, dayKey, from, available: { xp, coins }, entries: [{ rank, userId, username, profilePicUrl, xp, coins, claims, lastAt }], me: { rank, xp, coins, claims } | null } | { mode: "preview", metric, period, available, entries: [], me: null, message }
   - Standings of who earned the most XP or Coins in THIS app, computed by Twinkle from its own receipts (never from anything the app submits). period 'day' is today (site day, UTC), 'week' the last 7 site days, 'all' (default) every day since approval. limit defaults to 20, max 100.

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
@@ -1286,6 +1299,109 @@ ids (`reward-review show <id>` lists its events). An `accept` without a
 the comparison; mention it, it is not a fault. Refusals are the concurrency
 guards working; report them, and escalate only a repeated pattern on one app.
 
+### Members' chat reports (any time; also a full-daily-review duty, added 2026-09-27)
+
+Any member can report another member's chat message from the message's "…"
+menu (reasons: bullying or harassment, sexual content, asking for personal
+info, spam or scam, something else; optional note). The API snapshots the
+message and a few messages around it, so a later edit or delete does not
+erase the evidence, and Zero DMs Mikey on the first report of each message.
+The reporter only sees "Thanks. Our team will look at this."; the reported
+member is never told. The full-run intake and report carry `chatReports`
+(pending = `open` + `reviewing`), like `rewardReviews`. These commands need no
+daily run:
+
+```bash
+lumine admin chat-reports list --json                    # pending (default)
+lumine admin chat-reports list --status all --cursor 40 --json
+lumine admin chat-reports show 12 --json                 # snapshot + context
+lumine admin chat-reports set 12 --status resolved --note "What was decided or done" --json
+```
+
+Read every pending report's snapshot and context in each full run. A report
+about a child's safety or wellbeing (sexual content, requests for personal
+information or photos, threats, targeted bullying) belongs at the top of the
+escalation list for Mikey with the report id, both usernames and a one-line
+summary; set it to `reviewing` with a note saying so. Spam, obvious
+misclicks and ordinary disagreements can be `dismissed` with a note.
+Recording a status only annotates the report: never message, ban or
+otherwise act against either member without Mikey's explicit go-ahead.
+
+### Child-safety holds, evidence export and incident runbook (Mikey only, added 2026-09-27)
+
+> Not legal advice. Have a Korean lawyer review this procedure.
+
+Mikey, 2026-09-27: "if someone did something wrong - especially if for
+example a teacher was being inappropriate to a kid - shouldnt we be able to
+help police investigate?"
+
+**Automatic holds.** A report for sexual content or asking for personal
+info, or any report between a minor and an adult where both ages are known
+(an admin-approved birthdate, otherwise the birthdate on the profile), places
+a safety hold on the whole conversation and on both accounts. A second such
+report in the same conversation joins the existing hold. Zero, Ciel and the
+site-wide General channel are never held (a General report holds the two
+accounts). Zero's alert DM to Mikey says when a hold was placed, and
+`chat-reports show <id>` lists `safetyHoldIds`.
+
+**What a hold does**, silently, until it is released: a member's delete or
+edit still works for everyone, but the message row stays and the text before
+an edit (or the row at deletion) is copied to the hold; topic edits, removed
+archived profile pictures and removed previous usernames are copied too.
+Permanent deletion of a held message or of a held member's post or comment is
+refused with a neutral "can't be permanently deleted right now". Twinkle has
+no account deletion, so accounts are never erased. Nothing about a hold is
+shown to members.
+
+These commands are for Mikey. A daily run may read `list-holds` and report
+it, but never places, releases or exports a hold or suspends anyone without
+Mikey's explicit instruction for that case:
+
+```bash
+lumine admin chat-reports hold 12 --note "Why this case is held" --json
+lumine admin chat-reports hold --user 7,9 --channel 40 --note "Parent phoned" --json
+lumine admin chat-reports list-holds [--status active|released|all] --json
+lumine admin chat-reports suspend --user 7 --note "Adult under investigation" --json
+lumine admin chat-reports export 12 --out ~/twinkle-case-12 --json   # or --hold <id>
+lumine admin chat-reports release 3 --note "Police closed the case" --json
+```
+
+Every hold, release, export and suspension is recorded with who and when
+(`chat_safety_actions`), and released holds keep their copies.
+
+**Incident runbook** (for example, an adult or a teacher being inappropriate
+to a child):
+
+1. **Suspend the adult's access**: `chat-reports suspend --user <id> --note
+   <why>`. This is the website's full ban: it signs them out and blocks the
+   site. Lift it later from the website's Management ban editor.
+2. **Place or confirm the hold**: `chat-reports hold <report-id> --note <why>`
+   (or `--user`/`--channel` when there is no report yet, for example after a
+   parent's call), then `list-holds` to check that it covers the conversation
+   and both accounts.
+3. **Export the evidence**: `chat-reports export <report-id> --out <new
+   folder>`. The folder holds the whole conversation with UTC and KST times,
+   deletions and held edits; both accounts (username, id, join date, verified
+   email, birthdates, username history, linked Minecraft players, and the IP
+   addresses the site stores for logouts, searches and page visits); the
+   report(s); the actions taken; and `manifest.json` with each file's
+   SHA-256. Write down the printed manifest hash, keep the folder private,
+   and never edit it. Attachments are listed by storage key, not included.
+4. **Contact the police**: 112 for an emergency or ongoing danger, or the
+   cyber crime report system at https://ecrm.police.go.kr. Give them the
+   export when they ask for it.
+5. **Contact child protection**: report suspected child abuse to 112 (the
+   national child-abuse report line), which connects to the local
+   아동보호전문기관 (child protection agency).
+6. **Teachers and academy staff are mandatory reporters**: under Korea's Act
+   on Special Cases Concerning the Punishment of Child Abuse Crimes, teachers
+   and academy (hagwon) staff must report suspected child abuse. If the adult
+   is a teacher, their employer may also need to be told; ask the lawyer.
+7. **Do not** confront or warn the adult, delete anything, or share the
+   evidence with anyone but the police or child-protection staff.
+8. **Release the hold** only after the case is closed: `chat-reports release
+   <hold-id> --note <why>`.
+
 ## Private carry-over todos
 
 ```bash
@@ -3290,6 +3406,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: