@stage5/lumine 0.2.75 → 0.2.78

package/README.md

@@ -167,6 +167,10 @@ rewards.getStatus '{}' --build <id>` is read-only and works without
 `--allow-write` (the endpoint accepts only the `rewards:claim` scope, which is
 minted for it as a deliberate exception to the read-only rule, but only the
 status operation is sent).
+`rewards.getReceipt '{"challengeId":"..."}'` is also read-only: it checks
+the exact receipt after an interrupted claim, including earlier days or
+approved versions, without awarding again. It requires the current published
+runtime grant and returns canonical balances with the receipt status.
 `rewards.start '{"ruleId":"..."}'` and
 `rewards.claim '{"challengeId":"...","answers":[1,2]}'` mutate real XP/Coins
 state and require `--allow-write`. Every rewards call first reads the

package/lib/admin.js

@@ -31,8 +31,14 @@ import {
   runManagedBuildReview,
 } from "./build-review.js";
 import { runAdminRuntimeLogWorkflow } from "./admin-runtime-logs.js";
-import { readApprovedFeaturedPlan, runFeaturedWorkflow } from "./admin-featured.js";
-import { FEATURED_HISTORY_BATCH_SIZE, runBatchedFeaturedHistory } from "./admin-featured-history.js";
+import {
+  readApprovedFeaturedPlan,
+  runFeaturedWorkflow,
+} from "./admin-featured.js";
+import {
+  FEATURED_HISTORY_BATCH_SIZE,
+  runBatchedFeaturedHistory,
+} from "./admin-featured-history.js";
 
 const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
 const MAX_COMPOSED_TEXT_FILE_BYTES = 64 * 1024;
@@ -166,7 +172,7 @@ export function readRewardConfigFile(filePath) {
   }
   if (!Array.isArray(parsed.rules) || parsed.rules.length === 0) {
     throw cliValidationError(
-      "Approval needs at least one earning rule in rules[] (id, title, xp, coins, verifier: \"numeric-quiz\", questions[{prompt, answer}] and/or sets[{from, to?, questions}], optional maxAttempts (null = unlimited) and retry {xpPercent, coinsPercent}).",
+      'Approval needs at least one earning rule in rules[] (id, title, xp, coins, verifier: "numeric-quiz", questions[{prompt, answer}] and/or sets[{from, to?, questions}], optional maxAttempts (null = unlimited) and retry {xpPercent, coinsPercent}).',
     );
   }
   return parsed;
@@ -178,18 +184,26 @@ export function readRewardConfigFile(filePath) {
 export function writeRewardReviewSnapshot({ directory, files }) {
   const requested = String(directory || "").trim();
   if (!requested) {
-    throw cliValidationError("Pass a new or empty directory with --dir <path>.");
+    throw cliValidationError(
+      "Pass a new or empty directory with --dir <path>.",
+    );
   }
   const root = path.resolve(requested);
   if (root === path.resolve("/")) {
-    throw cliValidationError("Pass a new or empty directory with --dir <path>.");
+    throw cliValidationError(
+      "Pass a new or empty directory with --dir <path>.",
+    );
   }
   // The snapshot must land in a directory that holds nothing else, so the
   // reviewer never reads stale files from another review or clobbers a real
   // workspace, and so no pre-existing symlink can redirect a write.
   if (existsSync(root)) {
     const stat = lstatSync(root);
-    if (stat.isSymbolicLink() || !stat.isDirectory() || readdirSync(root).length) {
+    if (
+      stat.isSymbolicLink() ||
+      !stat.isDirectory() ||
+      readdirSync(root).length
+    ) {
       throw cliValidationError(
         `--dir ${root} must be a new or empty directory (not a symlink, file, or populated folder).`,
       );
@@ -382,7 +396,12 @@ export async function adminCommand(options) {
         viewFilter,
       });
     if (operation.featuredWorkflow) {
-      result = await runFeaturedWorkflow({ options, operation, authToken: auth.token, runId });
+      result = await runFeaturedWorkflow({
+        options,
+        operation,
+        authToken: auth.token,
+        runId,
+      });
     } else if (operation.name === "build.review") {
       result = await runManagedBuildReview({
         options,
@@ -409,9 +428,12 @@ export async function adminCommand(options) {
           "Use --resume with the scan checkpoint instead of combining --all with --cursor.",
         );
       }
-      const paginate = operation.name === "featured.history" &&
-        operation.pagination.filters.subjectIds.length > FEATURED_HISTORY_BATCH_SIZE
-        ? runBatchedFeaturedHistory : runAutomaticPagination;
+      const paginate =
+        operation.name === "featured.history" &&
+        operation.pagination.filters.subjectIds.length >
+          FEATURED_HISTORY_BATCH_SIZE
+          ? runBatchedFeaturedHistory
+          : runAutomaticPagination;
       result = await paginate({
         options,
         operation,
@@ -443,11 +465,16 @@ export async function adminCommand(options) {
   } catch (error) {
     if (operation.name === "runtime.evidence" && error.status === 404) {
       error.code = "CLI_ADMIN_RUNTIME_EVIDENCE_NOT_DEPLOYED";
-      error.message = "The runtime evidence route is not deployed on the requested host. Evidence is unknown; deploy the matching API and activate the collector in an authorized primary-generation release. No restart or host substitution was attempted.";
+      error.message =
+        "The runtime evidence route is not deployed on the requested host. Evidence is unknown; deploy the matching API and activate the collector in an authorized primary-generation release. No restart or host substitution was attempted.";
       error.data = {
         ok: false,
         status: "unavailable",
-        error: { code: error.code, message: error.message, details: { httpStatus: 404 } },
+        error: {
+          code: error.code,
+          message: error.message,
+          details: { httpStatus: 404 },
+        },
       };
     }
     if (operation.featuredWorkflow && error.featuredProgress) {
@@ -456,12 +483,18 @@ export async function adminCommand(options) {
         ok: false,
         status: "partial_failure",
         error: {
-          code: serverError?.code || error.code || "LUMINE_ADMIN_FEATURED_WORKFLOW_FAILED",
+          code:
+            serverError?.code ||
+            error.code ||
+            "LUMINE_ADMIN_FEATURED_WORKFLOW_FAILED",
           message: error.message,
           details: {
-            ...(serverError && typeof serverError === "object" ? serverError.details : {}),
+            ...(serverError && typeof serverError === "object"
+              ? serverError.details
+              : {}),
             ...error.featuredProgress,
-            retryInstruction: "Resume the exact command with --resume; confirmed items are not replayed.",
+            retryInstruction:
+              "Resume the exact command with --resume; confirmed items are not replayed.",
           },
         },
       };
@@ -649,7 +682,11 @@ async function finishAdminOutput({ options, operation, result }) {
     operation.name !== "news.claim" &&
     operation.name !== "post.skip-batch"
   ) {
-    writeAdminResultOutput({ filePath: options.adminOutput, result, operation });
+    writeAdminResultOutput({
+      filePath: options.adminOutput,
+      result,
+      operation,
+    });
   }
   if (options.json) {
     if (paginationStorage) {
@@ -1098,8 +1135,16 @@ export function assertAdminOperationAllowedForRunScope({
 }) {
   if (runScope === "newspaper") {
     if (
-      ["news.status", "news.claim", "news.submit", "news.print", "daily-run.complete", "daily-run.fail"].includes(operation.name)
-    ) return;
+      [
+        "news.status",
+        "news.claim",
+        "news.submit",
+        "news.print",
+        "daily-run.complete",
+        "daily-run.fail",
+      ].includes(operation.name)
+    )
+      return;
     throw cliValidationError(
       `A newspaper-only run does not authorize ${operation.name}.`,
     );
@@ -1137,6 +1182,7 @@ function adminOperationRequiresRun(operation) {
       "escalation.list",
       "escalation.set",
       "notable.add",
+      "notable.remove",
       "notable.status",
       "runtime-logs.start",
       "runtime-logs.status",
@@ -1393,7 +1439,9 @@ export function parseAdminOperation(options) {
     if (action === "show" || action === "get") {
       const reviewId = parseRequiredInteger(target, "Reward review ID", 1);
       if (options.dir && !snapshotDir) {
-        throw cliValidationError("Pass a new or empty directory with --dir <path>.");
+        throw cliValidationError(
+          "Pass a new or empty directory with --dir <path>.",
+        );
       }
       return readOperation(
         "reward-review.show",
@@ -1420,7 +1468,8 @@ export function parseAdminOperation(options) {
       if (action === "approve") {
         // Without --config the app's own proposal (rewards.json + sheet, frozen
         // in the request) is approved as it stands; --config replaces it.
-        if (options.adminConfigFile) body.config = readRewardConfigFile(options.adminConfigFile);
+        if (options.adminConfigFile)
+          body.config = readRewardConfigFile(options.adminConfigFile);
       } else if (options.adminConfigFile) {
         throw cliValidationError(
           "--config is only used with approve; rejections and revocations take --reason.",
@@ -1441,13 +1490,23 @@ export function parseAdminOperation(options) {
 
   if (namespace === "reward-activity" || namespace === "reward-telemetry") {
     // Read-only claim telemetry for the daily run: no run lease, no mutation.
-    const days = options.adminDays ? parseRequiredInteger(options.adminDays, "--days", 1) : 7;
+    const date = options.adminDate
+      ? parseUtcDayKey(options.adminDate)
+      : undefined;
+    const days = options.adminDays
+      ? parseRequiredInteger(options.adminDays, "--days", 1)
+      : date
+        ? 1
+        : 7;
     if (days > 31) throw cliValidationError("--days must be at most 31.");
     return readOperation(
       "reward-activity.report",
       withQuery("/cli/admin/reward-activity", {
         days: String(days),
-        buildId: options.buildIdFlag ? String(parseRequiredInteger(options.buildIdFlag, "--build", 1)) : "",
+        date,
+        buildId: options.buildIdFlag
+          ? String(parseRequiredInteger(options.buildIdFlag, "--build", 1))
+          : "",
       }),
       { requiresRun: false },
     );
@@ -1623,9 +1682,7 @@ export function parseAdminOperation(options) {
       const runScope = parseDailyRunScope(options.adminScope || "full");
       const commentMode = parseCommentMode(options.commentMode || "off");
       if (runScope !== "full" && commentMode !== "off") {
-        throw cliValidationError(
-          "A scoped run requires --comment-mode off.",
-        );
+        throw cliValidationError("A scoped run requires --comment-mode off.");
       }
       return writeOperation(
         "daily-run.start",
@@ -1899,27 +1956,68 @@ export function parseAdminOperation(options) {
   if (namespace === "featured") {
     if (action === "comments") {
       if (!["scan", "acknowledge", "recommend", "report"].includes(target)) {
-        throw cliValidationError("Usage: featured comments scan|acknowledge|recommend|report --checkpoint <file>.");
+        throw cliValidationError(
+          "Usage: featured comments scan|acknowledge|recommend|report --checkpoint <file>.",
+        );
       }
-      if (options.adminAll || options.adminCursor || options.adminUnviewed || options.adminViewed || options.adminAfter) {
-        throw cliValidationError("The Featured review covers every comment; filtered or caller-supplied cursors are not supported.");
+      if (
+        options.adminAll ||
+        options.adminCursor ||
+        options.adminUnviewed ||
+        options.adminViewed ||
+        options.adminAfter
+      ) {
+        throw cliValidationError(
+          "The Featured review covers every comment; filtered or caller-supplied cursors are not supported.",
+        );
       }
-      return { ...writeOperation(`featured.comments.${target}`, "POST", "/cli/admin/subjects/featured/reviews", {}),
-        mutates: target !== "report", featuredWorkflow: target };
+      return {
+        ...writeOperation(
+          `featured.comments.${target}`,
+          "POST",
+          "/cli/admin/subjects/featured/reviews",
+          {},
+        ),
+        mutates: target !== "report",
+        featuredWorkflow: target,
+      };
     }
     if (action === "plan") {
-      if (!options.adminPostedAfter) throw cliValidationError("A Featured plan requires --posted-after <timestamp>.");
-      return writeOperation("featured.plan", "POST", "/cli/admin/subjects/featured/plan", {
-        removeIds: parseFeaturedSubjectIds(options.adminRemoveIds, "--remove-subject-ids"),
-        addIds: parseFeaturedSubjectIds(options.adminAddIds, "--add-subject-ids"),
-        ...(options.adminIds ? { finalIds: parseOrderedIds(options.adminIds) } : {}),
-        postedAfter: options.adminPostedAfter,
-      });
+      if (!options.adminPostedAfter)
+        throw cliValidationError(
+          "A Featured plan requires --posted-after <timestamp>.",
+        );
+      return writeOperation(
+        "featured.plan",
+        "POST",
+        "/cli/admin/subjects/featured/plan",
+        {
+          removeIds: parseFeaturedSubjectIds(
+            options.adminRemoveIds,
+            "--remove-subject-ids",
+          ),
+          addIds: parseFeaturedSubjectIds(
+            options.adminAddIds,
+            "--add-subject-ids",
+          ),
+          ...(options.adminIds
+            ? { finalIds: parseOrderedIds(options.adminIds) }
+            : {}),
+          postedAfter: options.adminPostedAfter,
+        },
+      );
     }
     if (action === "apply") {
       readApprovedFeaturedPlan(options.adminFile, options.adminApprove);
-      return { ...writeOperation("featured.apply", "POST", "/cli/admin/subjects/featured/plan/apply", {}),
-        featuredWorkflow: "apply" };
+      return {
+        ...writeOperation(
+          "featured.apply",
+          "POST",
+          "/cli/admin/subjects/featured/plan/apply",
+          {},
+        ),
+        featuredWorkflow: "apply",
+      };
     }
     if (action === "list") {
       return readOperation("featured.list", "/cli/admin/subjects/featured");
@@ -1930,10 +2028,17 @@ export function parseAdminOperation(options) {
         "--subject-ids",
       );
       if (subjectIds.length > 20_000) {
-        throw cliValidationError("Featured history accepts at most 20000 subject IDs per CLI scan.");
+        throw cliValidationError(
+          "Featured history accepts at most 20000 subject IDs per CLI scan.",
+        );
       }
-      if (subjectIds.length > FEATURED_HISTORY_BATCH_SIZE && !options.adminAll) {
-        throw cliValidationError("Pass --all to automatically batch history reads larger than 100 subjects.");
+      if (
+        subjectIds.length > FEATURED_HISTORY_BATCH_SIZE &&
+        !options.adminAll
+      ) {
+        throw cliValidationError(
+          "Pass --all to automatically batch history reads larger than 100 subjects.",
+        );
       }
       return readOperation(
         "featured.history",
@@ -2118,11 +2223,11 @@ export function parseAdminOperation(options) {
     );
   }
 
-  if (namespace === "notable" && action === "add") {
+  if (namespace === "notable" && ["add", "remove"].includes(action) && !extra) {
     const rawTarget = String(target || "").trim();
     if (!rawTarget) {
       throw cliValidationError(
-        "Usage: lumine admin notable add <userId|username> --note <text>.",
+        `Usage: lumine admin notable ${action} <userId|username> --note <text>.`,
       );
     }
     const body = /^\d+$/.test(rawTarget)
@@ -2133,7 +2238,9 @@ export function parseAdminOperation(options) {
     const note = String(options.note || "").trim();
     if (!note) {
       throw cliValidationError(
-        "Pass what made this user notable with --note <text>.",
+        action === "remove"
+          ? "Explain why this user should be removed with --note <text>."
+          : "Pass what made this user notable with --note <text>.",
       );
     }
     if (note.length > MAX_NOTABLE_NOTE_LENGTH) {
@@ -2143,8 +2250,8 @@ export function parseAdminOperation(options) {
     }
     body.note = note;
     return writeOperation(
-      "notable.add",
-      "POST",
+      `notable.${action}`,
+      action === "remove" ? "DELETE" : "POST",
       "/cli/admin/notable-users",
       body,
     );
@@ -2218,8 +2325,14 @@ export function parseAdminOperation(options) {
   }
 
   if (namespace === "runtime") {
-    if (action !== "evidence" || !["primary", "target"].includes(target) || extra) {
-      throw cliValidationError("Usage: lumine admin runtime evidence primary|target [--days 1..7].");
+    if (
+      action !== "evidence" ||
+      !["primary", "target"].includes(target) ||
+      extra
+    ) {
+      throw cliValidationError(
+        "Usage: lumine admin runtime evidence primary|target [--days 1..7].",
+      );
     }
     return readOperation(
       "runtime.evidence",
@@ -2233,7 +2346,8 @@ export function parseAdminOperation(options) {
   if (namespace === "runtime-logs") {
     if (
       (action === "start" || action === "status" || action === "read") &&
-      (!target || (action === "start" && ["primary", "target"].includes(target))) &&
+      (!target ||
+        (action === "start" && ["primary", "target"].includes(target))) &&
       !extra
     ) {
       if (
@@ -2679,7 +2793,9 @@ function featuredRotateOperation(options) {
     {
       removeIds,
       addIds,
-      ...(options.adminPostedAfter ? { postedAfter: options.adminPostedAfter } : {}),
+      ...(options.adminPostedAfter
+        ? { postedAfter: options.adminPostedAfter }
+        : {}),
     },
   );
 }
@@ -3398,7 +3514,9 @@ function printAdminEnergyBudget(energyBudget) {
       `AI Energy budget health, last completed UTC day ${headline.dayKey}: ${formatAdminUsd(headline.chargedUsd)} charged, ${formatAdminUsd(headline.overflowUsd)} overflow, ${headline.users} user(s), ${headline.recharges} recharge(s), ${headline.runs.total.runs} run(s), ${headline.telemetry.metrics.busy_refusal.count} busy refusal(s).`,
     );
   } else {
-    console.log("AI Energy budget health: no completed UTC day in the requested window.");
+    console.log(
+      "AI Energy budget health: no completed UTC day in the requested window.",
+    );
   }
   console.log(
     "day        | charged | overflow | users | rechg | runs | calls/run avg/p90 | $/run avg/p90 | stops chg/unchg | busy | telemetry rows",
@@ -3416,7 +3534,9 @@ function printAdminEnergyBudget(energyBudget) {
     console.log("Flags: none.");
     return;
   }
-  console.log(`Flags (${flags.length}) — record each as a carry-over todo and escalate; never auto-enforce:`);
+  console.log(
+    `Flags (${flags.length}) — record each as a carry-over todo and escalate; never auto-enforce:`,
+  );
   for (const flag of flags) {
     console.log(`  ${flag.dayKey} ${flag.code}: ${flag.message}`);
   }
@@ -3616,25 +3736,41 @@ function formatRewardReviewLine(review) {
 }
 
 // One reviewer-facing line per earning rule: amounts, what a later try pays,
-// how many tries, and which Korean days the dated sets cover.
+// how many tries, and which site days (UTC) the dated sets cover.
 export function formatRewardRuleLine(rule) {
-  const parts = [`rule ${rule.id}: ${rule.title} · ${rule.xp} XP + ${rule.coins} Coins`];
+  const parts = [
+    `rule ${rule.id}: ${rule.title} · ${rule.xp} XP + ${rule.coins} Coins`,
+  ];
   if (rule.verifier === "completion") {
-    parts.push(`completion · pays when the app reports it finished at least ${rule.minSeconds || 0}s after start · once per learner per day`);
+    parts.push(
+      `completion · pays when the app reports it finished at least ${rule.minSeconds || 0}s after start · once per learner per day`,
+    );
     return parts.join(" · ");
   }
   if (rule.retry) {
-    parts.push(`retry pays ${Math.floor((rule.xp * rule.retry.xpPercent) / 100)} XP + ${Math.floor((rule.coins * rule.retry.coinsPercent) / 100)} Coins`);
+    parts.push(
+      `retry pays ${Math.floor((rule.xp * rule.retry.xpPercent) / 100)} XP + ${Math.floor((rule.coins * rule.retry.coinsPercent) / 100)} Coins${rule.retry.paidAttempts ? ` through try ${rule.retry.paidAttempts} (later solves pay nothing)` : ""}`,
+    );
   }
-  parts.push(rule.maxAttempts === null ? "unlimited tries" : `${rule.maxAttempts ?? 3} tries`);
+  parts.push(
+    rule.maxAttempts === null
+      ? "unlimited tries"
+      : `${rule.maxAttempts ?? 3} tries`,
+  );
   const standing = Array.isArray(rule.questions) ? rule.questions.length : 0;
   const sets = Array.isArray(rule.sets) ? rule.sets : [];
   if (sets.length && rule.progression === "until-earned") {
     const keys = sets.map((set, index) => set.key || `set-${index + 1}`);
-    parts.push(`${sets.length} until-earned set(s) in order: ${keys.join(", ")}${standing ? ` · ${standing} standing question(s)` : ""}`);
+    parts.push(
+      `${sets.length} until-earned set(s) in order: ${keys.join(", ")}${standing ? ` · ${standing} standing question(s)` : ""}`,
+    );
   } else if (sets.length) {
-    const days = sets.map((set) => (set.to && set.to !== set.from ? `${set.from}..${set.to}` : set.from));
-    parts.push(`${sets.length} dated set(s): ${days.join(", ")}${standing ? ` · ${standing} standing question(s)` : " · no standing questions"}`);
+    const days = sets.map((set) =>
+      set.to && set.to !== set.from ? `${set.from}..${set.to}` : set.from,
+    );
+    parts.push(
+      `${sets.length} dated set(s): ${days.join(", ")}${standing ? ` · ${standing} standing question(s)` : " · no standing questions"}`,
+    );
   } else {
     parts.push(`${standing} question(s)`);
   }
@@ -3644,32 +3780,53 @@ export function formatRewardRuleLine(rule) {
 function printRewardReviewResult({ operation, data }) {
   if (operation.name === "reward-review.list") {
     const reviews = Array.isArray(data.reviews) ? data.reviews : [];
-    console.log(`${reviews.length} reward review(s) (${data.filter || "pending"}):`);
-    for (const review of reviews) console.log(`  ${formatRewardReviewLine(review)}`);
+    console.log(
+      `${reviews.length} reward review(s) (${data.filter || "pending"}):`,
+    );
+    for (const review of reviews)
+      console.log(`  ${formatRewardReviewLine(review)}`);
     if (data.nextCursor) console.log(`More: --cursor ${data.nextCursor}`);
     return;
   }
   const review = data.review || {};
   console.log(formatRewardReviewLine(review));
   if (operation.name === "reward-review.decide") {
-    console.log(`Decision recorded: ${operation.decision}. ${review.reason ? `Reason: ${review.reason}` : ""}`.trim());
+    console.log(
+      `Decision recorded: ${operation.decision}. ${review.reason ? `Reason: ${review.reason}` : ""}`.trim(),
+    );
   }
   if (Array.isArray(review.detectedRuleIds)) {
-    console.log(`Rule IDs found in source (heuristic): ${review.detectedRuleIds.join(", ") || "none"}`);
+    console.log(
+      `Rule IDs found in source (heuristic): ${review.detectedRuleIds.join(", ") || "none"}`,
+    );
   }
-  if (review.isLatest === false) console.log("WARNING: a newer request exists for this app; decide on the latest one.");
-  if (review.isLive) console.log("This review is the live approval currently paying out.");
+  if (review.isLatest === false)
+    console.log(
+      "WARNING: a newer request exists for this app; decide on the latest one.",
+    );
+  if (review.isLive)
+    console.log("This review is the live approval currently paying out.");
   if (review.awarded) {
-    console.log(`Paid by this review: ${review.awarded.awards} awards to ${review.awarded.earners} people · ${review.awarded.xp} XP · ${review.awarded.coins} Coins (app lifetime ${review.appLifetime?.xp ?? 0} XP / ${review.appLifetime?.coins ?? 0} Coins)`);
+    console.log(
+      `Paid by this review: ${review.awarded.awards} awards to ${review.awarded.earners} people · ${review.awarded.xp} XP · ${review.awarded.coins} Coins (app lifetime ${review.appLifetime?.xp ?? 0} XP / ${review.appLifetime?.coins ?? 0} Coins)`,
+    );
   }
   const config = review.config || {};
   if (Array.isArray(config.rules)) {
-    console.log(`Budgets: day ${config.dailyXP} XP/${config.dailyCoins} Coins · per user/day ${config.userDailyXP} XP/${config.userDailyCoins} Coins${config.userDailyClaims ? ` · ${config.userDailyClaims} claim(s)` : ""} · lifetime ${config.lifetimeXP} XP/${config.lifetimeCoins} Coins`);
-    for (const rule of config.rules) console.log(`  ${formatRewardRuleLine(rule)}`);
+    console.log(
+      `Budgets: day ${config.dailyXP} XP/${config.dailyCoins} Coins · per user/day ${config.userDailyXP} XP/${config.userDailyCoins} Coins${config.userDailyClaims ? ` · ${config.userDailyClaims} claim(s)` : ""} · lifetime ${config.lifetimeXP} XP/${config.lifetimeCoins} Coins`,
+    );
+    for (const rule of config.rules)
+      console.log(`  ${formatRewardRuleLine(rule)}`);
   }
   if (Array.isArray(review.files)) {
-    console.log(`Source: ${review.files.length} file(s)${data.snapshotDirectory ? ` written to ${data.snapshotDirectory}` : " (pass --dir <path> to write the snapshot)"}`);
-    for (const file of review.files) console.log(`  ${file.path} (${file.bytes ?? Buffer.byteLength(String(file.content || ""), "utf8")} bytes)`);
+    console.log(
+      `Source: ${review.files.length} file(s)${data.snapshotDirectory ? ` written to ${data.snapshotDirectory}` : " (pass --dir <path> to write the snapshot)"}`,
+    );
+    for (const file of review.files)
+      console.log(
+        `  ${file.path} (${file.bytes ?? Buffer.byteLength(String(file.content || ""), "utf8")} bytes)`,
+      );
   }
   console.log("Use --json for the full record.");
 }
@@ -3677,22 +3834,42 @@ function printRewardReviewResult({ operation, data }) {
 function printRewardActivity(data) {
   const apps = Array.isArray(data.apps) ? data.apps : [];
   const suspects = Array.isArray(data.suspects) ? data.suspects : [];
-  console.log(`Reward activity ${data.from} → ${data.to} (${data.days} day(s)): ${apps.length} app(s) paid, ${suspects.length} flagged player-day(s).`);
+  console.log(
+    `Reward activity ${data.from} → ${data.to} (${data.days} day(s)): ${apps.length} app(s) paid, ${suspects.length} flagged player-day(s).`,
+  );
   for (const app of apps) {
-    console.log(`  app ${app.buildId} ${app.title}: ${app.claims} claim(s) · ${app.earners} earner(s) · ${app.xp} XP · ${app.coins} Coins · ${app.flagged} flagged`);
+    console.log(
+      `  app ${app.buildId} ${app.title}: ${app.claims} claim(s) · ${app.earners} earner(s) · ${app.xp} XP · ${app.coins} Coins · ${app.flagged} flagged`,
+    );
   }
   if (!suspects.length) {
-    console.log("Nothing unusual: no claim on the minimum time, no bursts, no sweeps, no repeated cap days, no guessing.");
+    console.log(
+      "Nothing unusual: no claim on the minimum time, no bursts, no sweeps, no repeated cap days, no guessing.",
+    );
     return;
   }
   console.log("Flagged (worst first):");
   for (const s of suspects) {
-    const parts = [`${s.flags.join("+")}`, `user ${s.userId}${s.username ? ` ${s.username}` : ""}`, `app ${s.buildId} ${s.title}`, s.dayKey, `${s.claims} claim(s) · ${s.xp} XP`];
-    if (s.fastClaims) parts.push(`${s.fastClaims} on the minimum (fastest ${s.minElapsedSeconds}s)`);
-    if (s.guessing) parts.push(`${s.guessing} challenge(s) with ${data.limits?.guessingAttempts ?? 15}+ wrong answers`);
+    const parts = [
+      `${s.flags.join("+")}`,
+      `user ${s.userId}${s.username ? ` ${s.username}` : ""}`,
+      `app ${s.buildId} ${s.title}`,
+      s.dayKey,
+      `${s.claims} claim(s) · ${s.xp} XP`,
+    ];
+    if (s.fastClaims)
+      parts.push(
+        `${s.fastClaims} on the minimum (fastest ${s.minElapsedSeconds}s)`,
+      );
+    if (s.guessing)
+      parts.push(
+        `${s.guessing} challenge(s) with ${data.limits?.guessingAttempts ?? 15}+ wrong answers`,
+      );
     console.log(`  ${parts.join(" · ")}`);
   }
-  console.log("Flags: fast = claimed within 5 s of the rule's minimum; burst = 3+ claims in 10 min; sweep = 75%+ of an app's completion rules within 30 min; cap = at the per-learner day cap; daily-max = at the cap on 3+ days; guessing = 15+ wrong answers on one quiz challenge. None is proof: read the player before acting.");
+  console.log(
+    "Flags: fast = claimed within 5 s of the rule's minimum; burst = 3+ claims in 10 min; sweep = 75%+ of an app's completion rules within 30 min; cap = at the per-learner day cap; daily-max = at the cap on 3+ days; guessing = 15+ wrong answers on one quiz challenge. None is proof: read the player before acting.",
+  );
 }
 
 function printAdminResult({ operation, result }) {
@@ -3707,20 +3884,34 @@ function printAdminResult({ operation, result }) {
   }
   if (operation.name === "runtime.evidence") {
     const evidence = data.evidence || {};
-    console.log(`Runtime evidence (${data.host?.requested || "unknown"}): ${evidence.status || "unknown"}.`);
-    console.log(`Samples: ${evidence.coverage?.samples ?? "unknown"}; latest: ${evidence.coverage?.lastAtMs ?? "unknown"}; age ms: ${evidence.coverage?.ageMs ?? "unknown"}.`);
+    console.log(
+      `Runtime evidence (${data.host?.requested || "unknown"}): ${evidence.status || "unknown"}.`,
+    );
+    console.log(
+      `Samples: ${evidence.coverage?.samples ?? "unknown"}; latest: ${evidence.coverage?.lastAtMs ?? "unknown"}; age ms: ${evidence.coverage?.ageMs ?? "unknown"}.`,
+    );
     for (const recycle of evidence.recycles || []) {
-      console.log(`  ${recycle.id}: ${recycle.outcome}; under load: ${recycle.observedUnderLoad ?? "unknown"}.`);
+      console.log(
+        `  ${recycle.id}: ${recycle.outcome}; under load: ${recycle.observedUnderLoad ?? "unknown"}.`,
+      );
     }
-    console.log("Missing evidence is unknown, not healthy. A recovered topology does not verify interrupted user work. Use --json for full evidence.");
+    console.log(
+      "Missing evidence is unknown, not healthy. A recovered topology does not verify interrupted user work. Use --json for full evidence.",
+    );
     return;
   }
   if (operation.name === "featured.plan") {
     for (const pair of data.plan?.replacements || []) {
-      console.log(`${pair.remove.id} ${pair.remove.title} -> ${pair.add.id} ${pair.add.title}`);
+      console.log(
+        `${pair.remove.id} ${pair.remove.title} -> ${pair.add.id} ${pair.add.title}`,
+      );
     }
-    console.log(`Proposed final order: ${(data.plan?.finalIds || []).join(",")}`);
-    console.log(`Plan hash: ${data.planHash}. Obtain Mikey's approval before using featured apply --file <plan.json> --approve ${data.planHash}.`);
+    console.log(
+      `Proposed final order: ${(data.plan?.finalIds || []).join(",")}`,
+    );
+    console.log(
+      `Plan hash: ${data.planHash}. Obtain Mikey's approval before using featured apply --file <plan.json> --approve ${data.planHash}.`,
+    );
     return;
   }
   if (operation.featuredWorkflow) {

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,7 +2900,7 @@ 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 reject|revoke <review-id> --reason <text> [--json]
@@ -2936,6 +2954,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:

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.75",
+  "version": "0.2.78",
   "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.41.0
-Updated: 2026-09-08
-Generated: 2026-09-12T06:19:33.743Z
+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-12T06:19:33.743Z
 - 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,20 +1014,29 @@ 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 (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.
 
 ## Examples
 

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
@@ -1092,7 +1102,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 +1132,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 +1140,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
@@ -1159,11 +1169,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 +3253,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