@stage5/lumine 0.2.76 → 0.2.79

package/lib/commands.js

@@ -1287,7 +1287,18 @@ export async function launch(options) {
 
 export function printCheck(result) {
   const checks = result.checks || {};
-  console.log(`Launch check: ${result.ok ? "ok" : "fail"}`);
+  console.log(`Saved project validation: ${result.ok ? "ok" : "fail"}`);
+  console.log(
+    `Publishing readiness: ${result.launchOk === true ? "ready" : "blocked"}`,
+  );
+  if (checks.canonicalBuild?.ok === false) {
+    console.log(
+      "This is a contribution branch. Validate local changes, save, then suggest the branch. The main app owner merges and publishes it.",
+    );
+  }
+  console.log(
+    "Saved checks use the server version; local workspace changes must be saved before these results describe them.",
+  );
   if (checks.canonicalBuild) {
     console.log(
       `- canonical build: ${checks.canonicalBuild.ok ? "ok" : "fail"}`,
@@ -1306,6 +1317,13 @@ export function printCheck(result) {
       console.log(`  ${checks.publishPermission.reason}`);
     }
   }
+  if (checks.rewardApproval) {
+    console.log(
+      `- XP/Coins approval: ${checks.rewardApproval.ok ? "ok" : "blocked"}`,
+    );
+    if (checks.rewardApproval.reason)
+      console.log(`  ${checks.rewardApproval.reason}`);
+  }
   if (typeof result.launchOk === "boolean") {
     console.log(`- launch gate: ${result.launchOk ? "ok" : "fail"}`);
   }
@@ -2882,9 +2900,10 @@ export function printHelp() {
   lumine admin sponsor integrity get <case-id> [--json]
   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 [--days <1..31>] [--build <id>] [--json]
+  lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
   lumine admin reward-review show <review-id> [--dir <path>] [--json]
-  lumine admin reward-review approve <review-id> [--config <rules.json>] [--reason <text>] [--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]
   lumine admin reward-review reject|revoke <review-id> --reason <text> [--json]
   lumine admin recommendations list [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin builds candidates [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--limit <number>] [--json]
@@ -2936,6 +2955,7 @@ export function printHelp() {
   lumine admin news submit --claim <claim.json> --file <editorial.json> [--model <name>] [--json]
   lumine admin notable status <user-id|username> [--json]
   lumine admin notable add <user-id|username> --note <text> [--json]
+  lumine admin notable remove <user-id|username> --note <text> [--json]
   lumine admin audit [list] [--run current|last|<run-id>] [--target <target>] [--actions <a,b>] [--full] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
 
 Examples:
@@ -2996,7 +3016,7 @@ Options:
   --preview-url <url>   Twinkle Build preview origin
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
-  --dir <path>          Directory for pulled project files or a reward-review source snapshot
+  --dir <path>          Directory for pulled project files, a reward-review source snapshot, or the edited snapshot a reward-review proposal sends
   --config <file>       Replacement earning rules JSON for reward-review approve (default: the app's own proposal)
   --provider <agent>    Subscription agent for lumine agent: codex or claude-code
   --provider-path <p>   Override the selected agent CLI executable

package/lib/constants.js

@@ -18,13 +18,19 @@ export const THUMBNAIL_CAPTURE_TIMEOUT_MS = 90 * 1000;
 export const GENERATE_MODEL_ALIASES = {
   "gpt-image-2.5-flare": "gpt-image-2.5-flare",
   "gpt-image-2.5-sunburst": "gpt-image-2.5-sunburst",
-  "flare": "gpt-image-2.5-flare",
-  "sunburst": "gpt-image-2.5-sunburst",
+  flare: "gpt-image-2.5-flare",
+  sunburst: "gpt-image-2.5-sunburst",
   "gpt-image-2": "gpt-image-2",
   "nano-banana": "gemini-3-pro-image-preview",
   "gemini-3-pro-image-preview": "gemini-3-pro-image-preview",
 };
-export const GENERATE_QUALITIES = new Set(["low", "medium", "high", "xhigh", "max"]);
+export const GENERATE_QUALITIES = new Set([
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+]);
 // Server accepts only these thumbnail content types (8MB max).
 export const THUMBNAIL_CONTENT_TYPE_BY_EXTENSION = {
   ".jpg": "image/jpeg",
@@ -119,6 +125,8 @@ export const BUNDLED_SDK_REFERENCE_URL = new URL(
   import.meta.url,
 );
 export const PACKAGE_METADATA_URL = new URL("../package.json", import.meta.url);
+export const LUMINE_MOBILE_SELECTION_GUIDANCE = `- Mobile long-press must not select game UI or open the browser's Copy/Look Up/image menu. The SDK protects standard buttons, button-like ARIA controls, and canvases. Mark the entire gameplay wrapper data-twinkle-no-select (including HUD, labels, scores, menus, controls, and empty play space); also apply user-select: none, -webkit-user-select: none, and -webkit-touch-callout: none for local previews. Protecting only one button or the canvas is insufficient.
+- Keep inputs/contenteditable usable. Mark genuinely copyable story/chat/user-written text data-twinkle-selectable and style it with user-select: text, -webkit-user-select: text, and -webkit-touch-callout: default. Do not blanket-disable selection on document/readers or preventDefault on document-wide touch/pointer events. Test holding controls, the HUD, and empty play space in mobile Safari and Chromium, then verify release/cancel, scrolling, typing, and copying. lumine check only detects a missing no-selection rule; a pass does not prove selector coverage or mobile behavior.`;
 export const LUMINE_WORLD_UPDATE_GUIDANCE = `- For Twinkle.world realtime presence, keep render/input loops local. Queue an update only when relevant state changes, replace any queued snapshot with the newest one, and flush on a fixed 5-15 updates-per-second schedule with at most one updatePresence request in flight. Never call or await updatePresence every animation frame, resend unchanged snapshots, overlap requests, or build a backlog.
 - Send Twinkle.world actions only when the discrete action happens; do not poll or automatically retry them. On WORLD_EVENT_RATE_LIMITED or another recoverable non-session-ended error, drop that attempted presence/action update without an immediate retry and keep the session. Reconnect with backoff only after session.ended or Twinkle.world.isSessionEndedError(error).`;
 export const SDK_REFERENCE_FALLBACK = `${LUMINE_SDK_REFERENCE_MARKER}
@@ -137,6 +145,7 @@ Use these current source-of-truth rules:
 - Use Twinkle.aiStories.list/search/get for existing AI Story passage text, story media, and questions.
 - Use Twinkle.ai.chat with history entries shaped as { role, content }, not { text }. Live web search is enabled by default; pass webSearch: false to disable it for the app.
 - Use Twinkle.preview for canvas, WebGL, Three.js, fullscreen, and game layout.
+${LUMINE_MOBILE_SELECTION_GUIDANCE}
 ${LUMINE_WORLD_UPDATE_GUIDANCE}
 - Prefer existing documented Twinkle.* methods over guessing names from old code.
 `;
@@ -307,7 +316,7 @@ lumine save --summary "Describe the change"
 
 - Use local project files with relative or root-local imports only. Do not add package imports, CDN scripts, external network calls, or app-local /api/* routes.
 - Build apps run in sandboxed iframes without allow-forms. Do not use <form> elements, native form submission, requestSubmit(), or browser form navigation. Build input flows with JavaScript-handled inputs and buttons instead.
-- Interface text must not be selectable on touch devices: long-pressing UI on mobile must not highlight it. Apply user-select: none plus -webkit-user-select: none and -webkit-touch-callout: none to interface text (HUD, buttons, labels, menus, scores, game controls). Keep text inputs and genuinely user-copyable content (story text, chat messages, user-written text) selectable. lumine check flags projects whose reachable files have clickable UI but no user-select: none rule.
+${LUMINE_MOBILE_SELECTION_GUIDANCE}
 - CAUTION: the preview runtime AUTO-DETECTS "game apps" — any <canvas> in the body (even a decorative background canvas) or game-y words in visible text switch the app to viewport-app mode: html/body get overflow:hidden !important and body becomes a centering flexbox, so tall document-flow pages clip and stop scrolling. Document-style apps that use a canvas must call Twinkle.preview.subscribe (or getLayout/reserveInsets) early at boot — any of those opts out of auto game mode — then pad by layout.safeInsets and scroll within layout.viewport.height.
 - For canvas, WebGL, Three.js, fullscreen, or game builds, use Twinkle.preview for layout. Do not size roots from 100vh, 100vw, 100dvh, 100dvw, window.innerWidth, window.innerHeight, visualViewport, or document viewport dimensions.
 ${LUMINE_THREE_VENDOR_GUIDANCE}

package/lib/rewards.js

@@ -34,11 +34,19 @@ async function readWorkspaceRewardsJson(options) {
   try {
     return { present: true, value: JSON.parse(raw), filePath };
   } catch (error) {
-    throw new Error(`${REWARDS_FILE} is not valid JSON: ${error?.message || error}`);
+    throw new Error(
+      `${REWARDS_FILE} is not valid JSON: ${error?.message || error}`,
+    );
   }
 }
 
-async function checkDeclaration({ options, auth, buildId, rewardsJson, sheet }) {
+async function checkDeclaration({
+  options,
+  auth,
+  buildId,
+  rewardsJson,
+  sheet,
+}) {
   return await requestJson({
     url: `${options.apiUrl}/cli/build/${buildId}/rewards/check`,
     method: "POST",
@@ -62,12 +70,16 @@ function printDeclaration(result, { prefix = "" } = {}) {
         rule.verifier === "completion"
           ? `completion · at least ${rule.minSeconds || 0}s`
           : `quiz · ${rule.questionSets} set(s)${rule.progression ? ` · ${rule.progression}` : ""}${rule.standingQuestions ? ` · ${rule.standingQuestions} standing` : ""}`;
-      console.log(`${prefix}  ${rule.id}: ${rule.title} · ${rule.xp} XP + ${rule.coins} Coins · ${what}`);
+      console.log(
+        `${prefix}  ${rule.id}: ${rule.title} · ${rule.xp} XP + ${rule.coins} Coins · ${what}`,
+      );
     }
+    if (result.nextStep) console.log(`${prefix}${result.nextStep}`);
     return;
   }
   console.log(`${prefix}Rewards declaration: NOT ready.`);
-  for (const error of result?.errors || []) console.log(`${prefix}  - ${error}`);
+  for (const error of result?.errors || [])
+    console.log(`${prefix}  - ${error}`);
 }
 
 // Part of `lumine check`: only speaks up when the workspace declares rewards
@@ -92,8 +104,15 @@ export async function reportRewardDeclaration({ options, auth, buildId }) {
     printDeclaration(result, { prefix: "Local check: " });
     if (!result.ok) process.exitCode = 1;
   } catch (error) {
-    const reason = String(error?.message || error).replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim().slice(0, 140);
-    console.error(`Local check warning: rewards declaration not verified (${reason}).`);
+    const reason = String(error?.message || error)
+      .replace(/<[^>]+>/g, " ")
+      .replace(/\s+/g, " ")
+      .trim()
+      .slice(0, 140);
+    console.error(
+      `Local check error: rewards declaration not verified (${reason}).`,
+    );
+    process.exitCode = 1;
   }
 }
 
@@ -114,7 +133,13 @@ export async function rewardsCommand(options) {
       rewardsJson: local.present ? local.value : undefined,
     });
     if (options.json) {
-      console.log(JSON.stringify({ ...result, source: local.present ? "workspace" : "saved" }, null, 2));
+      console.log(
+        JSON.stringify(
+          { ...result, source: local.present ? "workspace" : "saved" },
+          null,
+          2,
+        ),
+      );
     } else {
       console.log(
         local.present
@@ -134,20 +159,26 @@ export async function rewardsCommand(options) {
         timeoutMs: options.timeoutMs,
       });
       if (options.json) console.log(JSON.stringify(result, null, 2));
-      else if (!result.sheet) console.log("No question sheet on file for this app.");
+      else if (!result.sheet)
+        console.log("No question sheet on file for this app.");
       else {
         const rules = Object.entries(result.sheet.rules || {});
         console.log(`Question sheet on file: ${rules.length} rule(s).`);
         for (const [id, entry] of rules) {
           const sets = Array.isArray(entry.sets) ? entry.sets.length : 0;
-          const standing = Array.isArray(entry.questions) ? entry.questions.length : 0;
-          console.log(`  ${id}: ${sets} set(s), ${standing} standing question(s)`);
+          const standing = Array.isArray(entry.questions)
+            ? entry.questions.length
+            : 0;
+          console.log(
+            `  ${id}: ${sets} set(s), ${standing} standing question(s)`,
+          );
         }
       }
       return;
     }
     const file = options.positional?.[1];
-    if (!file) throw new Error("Usage: lumine rewards sheet <file.json> | --show");
+    if (!file)
+      throw new Error("Usage: lumine rewards sheet <file.json> | --show");
     await assertAuthScope({ options, auth, scope: "build:write" });
     let sheet;
     try {
@@ -164,7 +195,9 @@ export async function rewardsCommand(options) {
     });
     if (options.json) console.log(JSON.stringify(result, null, 2));
     else {
-      console.log(`Question sheet uploaded for Build ${buildId}. It is kept off the project files and merged with ${REWARDS_FILE} when you send the version for review.`);
+      console.log(
+        `Question sheet uploaded for Build ${buildId}. It is kept off the project files and merged with ${REWARDS_FILE} when you send the version for review.`,
+      );
       printDeclaration(result);
     }
     if (!result.ok) process.exitCode = 1;
@@ -183,6 +216,6 @@ function printRewardsHelp() {
 rewards.json (project root) declares the economy the reviewer approves:
   { "dailyXP", "dailyCoins", "userDailyXP", "userDailyCoins", "lifetimeXP", "lifetimeCoins", "userDailyClaims"?,
     "rules": [{ "id", "title", "xp", "coins", "verifier": "numeric-quiz" | "completion",
-                "maxAttempts"?, "retry"?: { "xpPercent", "coinsPercent" }, "minSeconds"? (completion), "progression"?: "dated" | "until-earned" (quiz) }] }
+                "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/lib/sdk.js

@@ -162,8 +162,8 @@ export const SDK_CLI_METHODS = {
   // token PLUS the server-issued published-runtime grant (fetched from the
   // canonical GET /build/:id/runtime payload, never minted locally). The CLI
   // holds no award logic; the server checks approval, version and budget.
-  // getStatus is read-only: the endpoint only accepts rewards:claim, so that
-  // scope is minted for it, but only the status operation is ever sent.
+  // Status and receipt reads use the endpoint's rewards:claim scope, but
+  // only their fixed read operation is sent.
   "rewards.getStatus": {
     path: "api/rewards/status",
     special: "rewards",
@@ -172,6 +172,14 @@ export const SDK_CLI_METHODS = {
     readOnly: true,
     mapArgs: () => ({}),
   },
+  "rewards.getReceipt": {
+    path: "api/rewards/receipt",
+    special: "rewards",
+    operation: "receipt",
+    scopes: ["rewards:claim"],
+    readOnly: true,
+    mapArgs: (args) => ({ challengeId: args.challengeId }),
+  },
   "rewards.start": {
     path: "api/rewards/start",
     special: "rewards",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.76",
+  "version": "0.2.79",
   "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.42.0
-Updated: 2026-09-12
-Generated: 2026-09-12T07:41:17.555Z
+Version: 1.45.0
+Updated: 2026-09-14
+Generated: 2026-09-14T06:42:36.041Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -24,16 +24,18 @@ Generated: 2026-09-12T07:41:17.555Z
 - Use Twinkle.characters.chat for real Zero/Ciel NPC dialogue with shared room context and AI Energy-aware thinking modes.
 - Twinkle.ai.chat history entries must use { role, content }; map local message.text fields to content before passing history.
 - Live web search is enabled by default for Twinkle.ai.chat and for Medium/High Twinkle.ai.generateObject and Twinkle.characters.chat requests. App authors can pass webSearch: false to disable it for their app. Search uses the provider's live web-search tool and is included in AI Energy usage; structured and character Lite Mode remains tool-free.
-- Interface text must not be selectable on touch devices: apply user-select: none plus -webkit-user-select: none and -webkit-touch-callout: none to interface text (HUD, buttons, labels, menus, scores, game controls) so mobile long-press does not highlight UI. Keep text inputs and genuinely user-copyable content selectable.
+- Mobile long-press must not select game UI or open browser Copy/Look Up/image menus. The SDK provides no-selection/callout defaults for standard buttons, button-like ARIA controls, and canvases. Mark the entire custom gameplay wrapper data-twinkle-no-select, including HUD, labels, scores, menus, controls, and empty play space; also style it with user-select: none, -webkit-user-select: none, and -webkit-touch-callout: none for local previews. Protecting only one button or the canvas is insufficient. This behavior is independent of Twinkle.preview layout mode.
+- Keep inputs/contenteditable usable. Mark genuinely copyable story/chat/user-written text data-twinkle-selectable and style it with user-select: text, -webkit-user-select: text, and -webkit-touch-callout: default. SDK defaults have low specificity so existing explicit copyable-text styles remain effective. Preserve document/reader selection; do not block document-wide touch/pointer events or disable scrolling/zoom to prevent selection.
+- Verify mobile long presses on controls, HUD, and empty play space in Safari and Chromium; confirm held controls still work and release/cancel correctly, and scrolling, typing, and copying still work. lumine check only detects a missing no-selection rule, not selector coverage or mobile behavior.
 - Build app tab mute is enforced by the host runtime automatically for standard media elements and Web Audio connections to AudioContext.destination. Apps with custom audio engines can also observe Twinkle.onAudioMuteChange and check Twinkle.isAudioMuted.
 - Use Twinkle.media for camera photos and camera-only two-second clips. Twinkle confirms each capture or paid processing action. Clips are processed to canonical 480p MP4 assets before they become visible; use sharedDb or privateDb to publish/store the returned asset metadata.
 - Static media published through sharedDb is app-owned feed data. A public user-generated feed must provide a visible report flow and owner removal, and must not claim that Twinkle globally moderates those posts.
 - Use Twinkle.live for one-way app livestreams and Twinkle.chat for the accompanying thread. Free livestreams require a verified host, end after at most 15 minutes, and issue at most 10 private viewer grants. Twinkle keeps platform-owned live-status/end controls above active hosts, so app code cannot hide or replace the broadcaster's Stop path.
 - Media Energy is separate from AI Energy. Replace Media Energy UI only from canonical mediaEnergy/getUsage responses; never decrement, reserve, or synthesize it in app code.
 - Twinkle.rewards awards real XP and Coins only in the current approved published release. Drafts, local previews, private apps and superseded releases cannot earn. The server supplies a published-runtime grant; app code cannot choose a recipient or award amount.
-- The creator's agent designs the rewards. Declare the economy in a project file `rewards.json` at the root: budgets (dailyXP, dailyCoins, userDailyXP, userDailyCoins, lifetimeXP, lifetimeCoins, optional userDailyClaims) and rules [{ id, title, xp, coins, verifier: 'numeric-quiz' | 'completion', maxAttempts?, retry?: { xpPercent, coinsPercent }, 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 Korean day, 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.
-- v1 verifies numeric quiz answers on the server; client scores, privateDb state, timers and completion booleans are not reward evidence. Daily limits reset at midnight in Korea. Each rule can be earned once per viewer per day, with three answer attempts per challenge. Challenge expiry is 30 minutes. Budgets apply across release changes.
+- The creator's agent designs the rewards. Declare the economy in a project file `rewards.json` at the root: budgets (dailyXP, dailyCoins, userDailyXP, userDailyCoins, lifetimeXP, lifetimeCoins, optional userDailyClaims) 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.
 
 ## Token Scopes
 files:read, media:read, media:write, live:read, live:write, user:read, users:read, dailyReflections:read, content:read, content:write, sharedDb:read, sharedDb:write, privateDb:read, privateDb:write, files:write, chat:read, chat:write, notifications:read, notifications:write, notifications:emit, reminders:read, reminders:write, rewards:claim
@@ -1012,23 +1014,27 @@ world.updatePresence({ x, y, z, facing });
 - 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 }
   - 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 Korean day 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 Korean midnight.
+  - 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.
+- 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.
+  - Reconcile a durable local reward outbox after a lost claim reply: awarded confirms the exact payment; pending means no receipt yet for a current unexpired challenge, so retry the same challengeId. expired or not_found confirms no paid receipt and no claim possible for that ID under the current release. Never refund app items just because getStatus history omitted an older claim or a network request failed. Preview has no durable paid receipts; keep it separate from live recovery.
 - await Twinkle.rewards.start({ ruleId }) | scopes: rewards:claim
   - Returns: { mode: "live", challengeId, questions: [{ prompt, hint?, guide? }], setKey, reward: { xp, coins }, retryReward: { xp, coins }, attempts, maxAttempts, attemptsRemaining, firstTryAvailable, expiresAt }
-  - Creates or resumes a server-issued challenge for the signed-in viewer. Render its questions (prompt and optional hint) and collect numeric answers in the same order. One daily challenge per rule/review; repeat starts cannot reset attempts. A challenge stays open until Korean midnight (expiresAt). Resuming after a wrong answer includes each question's guide.
+  - Creates or resumes a server-issued challenge for the signed-in viewer. Render its questions (prompt and optional hint) and collect numeric answers in the same order. One daily challenge per rule/review; repeat starts cannot reset attempts. A challenge stays open until the site's daily reset (UTC midnight, 9:00 AM in Korea) (expiresAt). Resuming after a wrong answer includes each question's guide.
   - 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).
 - await Twinkle.rewards.claim({ challengeId, answers?: [number] }) | scopes: rewards:claim
   - Returns: { awarded: false, attempts, attemptsRemaining, questions: [{ prompt, hint?, guide? }] } | { awarded: true, duplicate, receipt: { ruleId, xp, coins, attempt, firstTry }, questions: [{ prompt, hint?, guide? }], balances: { xp, coins } }
-  - Twinkle verifies every answer, approval, current published artifact and budget before atomically recording XP and Coins. The receipt’s xp/coins are what was actually paid: the full amounts on a first try, the retry share after a wrong answer (attempt > 1). Retry the same challengeId after a lost response; a confirmed claim returns its original receipt without another award. Never update balance UI optimistically.
+  - Twinkle verifies every answer, approval, current published artifact and budget before atomically recording XP and Coins. The receipt’s xp/coins are what was actually paid: the full amounts on a first try, the retry share after a wrong answer (attempt > 1). Retry the same challengeId after a lost response; a confirmed claim returns its original receipt without another award. Never update balance UI optimistically. Under retry.paidAttempts a correct answer past that attempt returns awarded: true with a zero receipt: solved, not paid.
   - Every claim response, wrong or right, returns the questions with their guides unlocked: show the teaching content right after the first answer. Answer keys are never returned.
   - 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.
 - 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 in Korea, 'week' the last 7 Korean days, 'all' (default) every day since approval. limit defaults to 20, max 100.
+  - 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.
   - available says which boards this app's approved rules can pay: show a Coins board only when available.coins is true (an app whose rules pay XP only has no Coins standings). me is the signed-in viewer's own standing even when they fall outside the page, or null when they earned nothing in the period.
   - Drafts and previews return mode 'preview' with no entries. Use Twinkle.leaderboards for app-defined scores; use this for real XP and Coins earned.
 

package/sdk/LUMINE_ADMIN.md

@@ -488,16 +488,24 @@ it never authorizes unrelated daily work or generic recommendation commands.
 
 Mikey added Math Lab question design and publishing to the full daily workflow
 on 2026-09-08. Follow [Math Lab daily question publishing](../../agent-guides/math-lab-daily.md)
-for the canonical Build 2460, owner account, 12-grade/36-question editorial
-process, verification, repeat-run recovery, release gates, and final reporting.
+for the canonical Build 2460, owner account, twelve grade queues of ordered
+until-earned puzzles, verification, repeat-run recovery, release gates, and
+final reporting. Every full daily run reports each grade's current question,
+whether it was cleared today, uncleared published questions remaining, and
+refill status. Count distinct cleared keys across all users and the app's full
+history against the live approved sheet; the recent usage window and draft
+additions are not the live inventory. At two or fewer remaining, prepare a
+refill to at least ten, with complete interactive guides, and track it until
+approved publication. Report one or zero remaining prominently. Details are
+in the linked guide's **Daily queue monitoring and refill** section.
 This is not part of Featured-only or newspaper-only work and is not a new
 scheduler, delegated API scope, or automatic extension of admin permissions.
 Use the expressly authorized owner Build workflow for Math Lab; retain the
 normal Zero/Ciel actor separation for other administration.
 
-The initial private draft must remain unpublished until Mikey authorizes its
-launch. After launch, routine content releases follow the standing duty but
-cannot bypass a reward-enabled app's exact-version approval gate. Local edits
+Mikey authorized Math Lab's initial launch, completed on 2026-09-12. Routine
+refills follow the standing duty but still need his exact-version approval
+and explicit publication authorization. Local edits
 and draft saves do not require release approval. Real XP/Coins may be changed
 only by the currently published, approved artifact through server-verified
 reward claims; private builds, previews, local tests, unpublished branches, and
@@ -507,6 +515,8 @@ has already been implemented. See the guide before adding reward capabilities.
 
 ## Escalation to Mikey
 
+Before closing a full run, reconcile three explicit handoffs: pending reward approvals (`rewardReviews` in intake/report), every carryover todo (with new evidence or a concrete blocker and next action), and earlier-day telemetry that meets a reopening condition. `carryoverWithoutProgressThisRun` in the report identifies surfaced todos without a progress update. A pending human decision can remain open; it must be named with its exact request/version, recommendation and next owner. Never equate reading a summary with inspecting frozen implementation, clearing a stuck flag with producing the intended image, or deploying code with verifying its live outcome. The September 14 omissions were execution failures under already explicit duties; these fields make them visible, not optional.
+
 A full daily management run is not finished when the mutations are done. Curation surfaces things only
 a human owner can decide, and a finding nobody reports is a finding that did not
 happen. **Every full run ends with an escalation list**, and it belongs in the run's
@@ -1055,9 +1065,16 @@ and answer keys from a private question sheet the creator's Lumine uploads with
 readable by every player). **Send for review** 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. These commands need no daily
-run and can be used whenever a request arrives (the reviewer also receives a
-DM card per request).
+farmed, change anything that is wrong, approve. **Approval publishes** (since
+2026-09-15): the exact frozen snapshot goes live in the same transaction, with
+no Publish click by the creator; the app's previous release stays up until
+that commit lands. Instead of approving, the reviewer may **propose changes**:
+edit a copy of the frozen snapshot and offer it as the condition of approval.
+The creator sees every changed line and either accepts (the proposed version
+is approved and published) or declines (the request is rejected). Nothing in
+that flow joins the creator's team. These commands need no daily run and can
+be used whenever a request arrives (the reviewer also receives a DM card per
+request).
 
 ```bash
 lumine admin reward-review list --json                       # pending (default)
@@ -1067,7 +1084,10 @@ lumine admin reward-review show 2 --json                     # summary + file si
 lumine admin reward-review show 2 --dir /private/tmp/reward-review-2 --json
 lumine admin reward-review approve 2 --json                  # approve exactly what the app proposed
 lumine admin reward-review approve 2 --config rules.json \
-  --reason "Halved the stage amounts" --json                 # approve with changes
+  --reason "Halved the stage amounts" --json                 # approve with changes (publishes)
+lumine admin reward-review show 2 --dir /private/tmp/reward-review-2 --json   # then edit that directory…
+lumine admin reward-review propose 2 --dir /private/tmp/reward-review-2 \
+  --config rules.json --reason "Moved the claim after the stage clears" --json  # …and offer it
 lumine admin reward-review reject 2 --reason "Rewards fire on game over; nothing is earned" --json
 lumine admin reward-review revoke 2 --reason "Farmable; pausing until redesigned" --json
 ```
@@ -1092,7 +1112,7 @@ Review questions to settle with Mikey before approving:
   day across twelve stages.
 - Quiz rules: fixed questions reachable in seconds are farmable; dated sets
   or `progression: "until-earned"` sets (a set stays up until somebody earns
-  it, then the next one comes up the following Korean day) keep them honest.
+  it, then the next one comes up the following site day (UTC midnight, 9:00 AM Korea)) keep them honest.
 - Do the rule IDs in `rewards.json` match what the code starts? Unknown IDs
   simply never pay.
 - Are the amounts and the per-user, per-app and lifetime budgets conservative
@@ -1122,7 +1142,7 @@ Rule fields (all server-enforced, none inferred from app code):
 - `verifier`: `numeric-quiz` (server-checked numeric answers) or `completion`
   (a finished activity; `minSeconds` is the only proof).
 - `sets`: question sets. Dated: `[{ "from": "2026-09-14", "to": "2026-09-14", "questions": [...] }]`
-  on Korean calendar days (inclusive, non-overlapping, up to 62). Until-earned
+  on site days (UTC) (inclusive, non-overlapping, up to 62). Until-earned
   (`"progression": "until-earned"`): ordered sets with optional `key`; the
   first set nobody earned before today is up, an unsolved set is never
   replaced, and a set earned today stays up for the rest of that day.
@@ -1130,11 +1150,11 @@ Rule fields (all server-enforced, none inferred from app code):
   after a wrong one, as a share of the rule's amounts (rounded down). Absent:
   every correct answer pays the full amounts.
 - `maxAttempts`: wrong answers allowed per challenge; `null` = unlimited until
-  Korean midnight (wrong answers are paced two seconds apart). Absent: 3.
+  the daily reset (UTC midnight, 9:00 AM Korea) (wrong answers are paced two seconds apart). Absent: 3.
 - Per question `hint` (public from the start, ≤ 300 chars) and `guide` (a JSON
   object ≤ 6,000 chars the app renders as the after-answer lesson). The server
   releases a guide only after the learner's first answer.
-- Top-level `userDailyClaims`: receipts one learner may earn per Korean day
+- Top-level `userDailyClaims`: receipts one learner may earn per site day
   across all rules. `1` is "one bounty a day".
 
 Math Lab's economy (Mikey, 2026-09-12): twelve level rules, one per grade per
@@ -1146,12 +1166,49 @@ Arcade Typing (Mikey, 2026-09-12): XP for clearing campaign stages, up to
 10,000 Coins per rule and per learner per day, 10,000,000 XP / 1,000,000 Coins
 per app per day, 1,000,000,000 XP / 100,000,000 Coins per app lifetime.
 
-Approval freezes these rules with the reviewed snapshot; an approval without at
-least one rule is refused. Rejection and revocation require a `--reason` the
-creator reads verbatim in their workspace. Approval never publishes: the creator
-publishes the approved version themselves, and a later code save needs a new
-request. Never approve without reading the code; never approve a request whose
-`isLatest` is false.
+Approval freezes these rules with the reviewed snapshot and publishes that
+snapshot immediately (the result carries `published.version`); an approval
+without at least one rule is refused, and an approval whose creator has saved
+past the frozen version is refused as `build_reward_review_stale` (the request
+also closes itself on that save). Rejection and revocation require a
+`--reason` the creator reads verbatim in their workspace. A later code save
+needs a new request. Never approve without reading the code; never approve a
+request whose `isLatest` is false.
+
+`propose <id> --dir <edited> --config rules.json [--reason]` sends the edited
+directory (text files only; dotfiles and tool folders skipped) as the
+reviewer's proposal: the review moves to `changes_offered`, the creator's card
+and workspace show the note and every changed line, and the creator's
+**Accept & go live** publishes exactly those files with these rules (their
+workspace is replaced by the accepted version). **No thanks** rejects the
+request (`declinedByCreator: true`). A proposal must still use the rewards
+SDK, must differ from the submitted snapshot, and is refused once the creator
+saves past the submitted version. Offering again replaces the earlier offer;
+approving or rejecting while an offer is out decides the request as
+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".
+
+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
+amounts as well as its file changes. Proposed rules stay separate from the
+submitted rules until acceptance, so `approve` without `--config` still uses
+the original submitted configuration. The CLI audits the offer atomically
+and includes file contents in its retry fingerprint.
+
+Approval also attempts a free preview thumbnail when the app has none. That
+capture uses the published version and cannot overwrite a later release or a
+thumbnail the creator chooses while it runs. It is best effort: a capture
+failure leaves publication successful and does not spend AI-image credits.
+
+The review copy carries independent copies of referenced uploaded media.
+Before freezing an offer, the server reuses the creator's original media and
+copies new reviewer media into the creator's library within their storage
+quota. Its final URLs are included in the comparison, so acceptance publishes
+those exact files and does not depend on keeping the review copy. Re-offers
+reuse the media; a failed transaction cleans up its copied objects. Declining
+leaves the offered media as unused uploads in the creator's library.
 
 ### Reward activity report (standing duty, every full daily review; added 2026-09-12)
 
@@ -1159,11 +1216,13 @@ Completion rewards (Arcade Typing's stage clears) prove nothing but elapsed
 time, so the run reads the shape of the week's claims instead of trusting them:
 
 ```bash
-lumine admin reward-activity --json                # last 7 Korean days, every app
+lumine admin reward-activity --json                # 7 UTC days INCLUDING today’s partial day
+lumine admin reward-activity --date 2026-09-13 --json # exactly this UTC day
+lumine admin reward-activity --date 2026-09-13 --days 7 --json # 7 days ending on this date
 lumine admin reward-activity --days 14 --build 333 --json
 ```
 
-Read-only, no run lease. The result lists every app that paid (claims,
+Read-only, no run lease. For yesterday, always pass its exact UTC `--date`; `--days 1` alone means the current partial day. `from`, `to`, `timezone`, and `includesCurrentDay` make the window explicit. Rules come from each claim’s frozen review, not the current app policy; `missingReviewIds` means rule-based flags lack context. The result lists every app that paid (claims,
 earners, XP, Coins) and the flagged player-days, worst first:
 
 - `fast`: a completion claim within 5 s of the rule's `minSeconds` — a human
@@ -3241,6 +3300,7 @@ farm-signal sections added that day; AI Card summon watch added 2026-08-24):
   canonical writer and returns only the resolved public account identity,
   current membership, and the roster rationale/timestamps when present; it
   does not expose the private roster fields.
+  When Mikey authorizes removal, use `lumine admin notable remove <userId|username> --note "<why removed>" --json`. It is run-independent, transactionally audited as `notable.remove`, verifies canonical absence, and is idempotent. Never use SQL to work around a missing CLI verb. Mikey is the administrator, not a Notable candidate; do not include him in blanket roster additions.
   **Always pass `--note`** with a concrete one-or-two-sentence record of what
   made them notable — real numbers and specifics from the brief window, not
   "active user". It lands in the management page's reason column, which is