@stage5/lumine 0.2.71 → 0.2.76

package/lib/admin.js

@@ -1,6 +1,15 @@
 import { createHash, randomUUID } from "node:crypto";
 import { once } from "node:events";
-import { readFileSync } from "node:fs";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
 import { assertAuthScope, resolveAuth } from "./auth.js";
 import { requestJson } from "./http.js";
 import {
@@ -121,6 +130,105 @@ function readBuildReviewContextFile(filePath) {
   return understanding;
 }
 
+const MAX_REWARD_CONFIG_FILE_BYTES = 256 * 1024;
+const REWARD_REVIEW_STATUSES = ["pending", "approved", "all"];
+const REWARD_REVIEW_DECISIONS = ["approve", "reject", "revoke"];
+
+// The reviewer's earning rules for one Build reward approval: budgets plus
+// server-verified numeric-quiz rules keyed by the rule IDs the app source
+// starts challenges with. Validation is the server's; this only reads JSON.
+export function readRewardConfigFile(filePath) {
+  const normalizedPath = String(filePath || "").trim();
+  if (!normalizedPath) {
+    throw cliValidationError(
+      "Pass the earning rules with --config <rules.json> (dailyXP, dailyCoins, userDailyXP, userDailyCoins, lifetimeXP, lifetimeCoins, rules[]).",
+    );
+  }
+  let contents;
+  try {
+    contents = readFileSync(normalizedPath, "utf8");
+  } catch {
+    throw cliValidationError(`Could not read ${normalizedPath}.`);
+  }
+  if (Buffer.byteLength(contents, "utf8") > MAX_REWARD_CONFIG_FILE_BYTES) {
+    throw cliValidationError("The earning rules file must be under 256KB.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(contents);
+  } catch {
+    throw cliValidationError(`${normalizedPath} is not valid JSON.`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw cliValidationError(
+      "The earning rules file must be a JSON object with budgets and a rules array.",
+    );
+  }
+  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}).",
+    );
+  }
+  return parsed;
+}
+
+// Writes the frozen source snapshot of a reward review into a local directory
+// so the reviewing agent can read the exact code under review with ordinary
+// tools. Paths are confined to the target directory; files are private.
+export function writeRewardReviewSnapshot({ directory, files }) {
+  const requested = String(directory || "").trim();
+  if (!requested) {
+    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>.");
+  }
+  // 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) {
+      throw cliValidationError(
+        `--dir ${root} must be a new or empty directory (not a symlink, file, or populated folder).`,
+      );
+    }
+  } else {
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+  }
+  const realRoot = realpathSync(root);
+  const written = [];
+  for (const file of Array.isArray(files) ? files : []) {
+    const relative = String(file?.path || "").replace(/^\/+/, "");
+    const target = path.resolve(realRoot, relative);
+    if (
+      !relative ||
+      relative.includes("\\") ||
+      !target.startsWith(`${realRoot}${path.sep}`)
+    ) {
+      throw cliValidationError(
+        `Refusing to write snapshot path outside ${realRoot}: ${file?.path}`,
+      );
+    }
+    mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    if (!realpathSync(path.dirname(target)).startsWith(realRoot)) {
+      throw cliValidationError(
+        `Refusing to write snapshot path outside ${realRoot}: ${file?.path}`,
+      );
+    }
+    const content = String(file?.content ?? "");
+    // 'wx' creates a fresh file only; an existing entry (or symlink) fails.
+    writeFileSync(target, content, { mode: 0o600, flag: "wx" });
+    written.push({
+      path: `/${relative}`,
+      bytes: Buffer.byteLength(content, "utf8"),
+      savedTo: target,
+    });
+  }
+  return { directory: realRoot, files: written };
+}
+
 function readEditorialFile(filePath) {
   const normalizedPath = String(filePath || "").trim();
   if (!normalizedPath) {
@@ -410,6 +518,23 @@ export async function adminCommand(options) {
   if (operation.name === "daily-run.start") {
     assertAdminTodoHandoffResult(result, operation.body.scope);
   }
+  if (operation.name === "reward-review.show" && operation.snapshotDir) {
+    // The snapshot leaves the JSON result and lands on disk, where the agent
+    // reads it like any pulled workspace; the result keeps sizes and paths.
+    const review = result?.data?.review || {};
+    const snapshot = writeRewardReviewSnapshot({
+      directory: operation.snapshotDir,
+      files: review.files,
+    });
+    result = {
+      ...result,
+      data: {
+        ...(result.data || {}),
+        review: { ...review, files: snapshot.files },
+        snapshotDirectory: snapshot.directory,
+      },
+    };
+  }
   if (operation.name === "news.claim") {
     const artifacts = writeNewsClaimArtifacts({
       result,
@@ -1241,6 +1366,93 @@ export function parseAdminOperation(options) {
     }
   }
 
+  if (
+    namespace === "reward-review" ||
+    namespace === "reward-reviews" ||
+    namespace === "rewards"
+  ) {
+    // Build XP/Coin reward approvals are the administrator's own decision and
+    // never part of a delegated Zero/Ciel daily run: they can happen any time.
+    const snapshotDir = String(options.dir || "").trim();
+    if (!action || action === "list") {
+      return readOperation(
+        "reward-review.list",
+        withQuery("/cli/admin/reward-reviews", {
+          status: parseChoice(
+            options.adminStatus || "pending",
+            "--status",
+            REWARD_REVIEW_STATUSES,
+          ),
+          beforeId: options.adminCursor
+            ? parseRequiredInteger(options.adminCursor, "--cursor", 1)
+            : "",
+        }),
+        { requiresRun: false },
+      );
+    }
+    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>.");
+      }
+      return readOperation(
+        "reward-review.show",
+        withQuery(`/cli/admin/reward-reviews/${reviewId}`, {
+          // Without --dir the source is listed with sizes only; with --dir the
+          // full snapshot is fetched and written locally for reading.
+          files: snapshotDir ? "1" : "0",
+        }),
+        { requiresRun: false, reviewId, snapshotDir },
+      );
+    }
+    if (REWARD_REVIEW_DECISIONS.includes(action)) {
+      const reviewId = parseRequiredInteger(target, "Reward review ID", 1);
+      const reason = String(options.adminReason || "").trim();
+      if (action !== "approve" && !reason) {
+        throw cliValidationError(
+          `lumine admin reward-review ${action} <id> needs --reason <text> the creator will read.`,
+        );
+      }
+      if (reason.length > 1000) {
+        throw cliValidationError("--reason must be at most 1000 characters.");
+      }
+      const body = { decision: action, reason };
+      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);
+      } else if (options.adminConfigFile) {
+        throw cliValidationError(
+          "--config is only used with approve; rejections and revocations take --reason.",
+        );
+      }
+      return writeOperation(
+        "reward-review.decide",
+        "POST",
+        `/cli/admin/reward-reviews/${reviewId}`,
+        body,
+        { requiresRun: false, reviewId, decision: action },
+      );
+    }
+    throw cliValidationError(
+      "Usage: lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] | show <id> [--dir <path>] | approve <id> [--config <rules.json>] [--reason <text>] | reject <id> --reason <text> | revoke <id> --reason <text>.",
+    );
+  }
+
+  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;
+    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)) : "",
+      }),
+      { requiresRun: false },
+    );
+  }
+
   if (namespace === "todo" || namespace === "todos") {
     if (!action || action === "list") {
       return readOperation(
@@ -3395,8 +3607,104 @@ async function printSpooledAdminResult({ operation, result, storage }) {
   printPagination(data.pagination);
 }
 
+function formatRewardReviewLine(review) {
+  const owner = review.ownerUsername ? ` by ${review.ownerUsername}` : "";
+  const rules = Array.isArray(review.config?.rules)
+    ? review.config.rules.length
+    : Number(review.ruleCount || 0);
+  return `#${review.id} ${String(review.status || "").toUpperCase()} · ${review.title || `App ${review.buildId}`}${owner} · app ${review.buildId} · saved version ${review.sourceVersionId} · ${rules} rule${rules === 1 ? "" : "s"}`;
+}
+
+// One reviewer-facing line per earning rule: amounts, what a later try pays,
+// how many tries, and which Korean days the dated sets cover.
+export function formatRewardRuleLine(rule) {
+  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`);
+    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(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)` : ""}`);
+  } 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"}`);
+  } else {
+    parts.push(`${standing} question(s)`);
+  }
+  return parts.join(" · ");
+}
+
+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)}`);
+    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());
+  }
+  if (Array.isArray(review.detectedRuleIds)) {
+    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.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)`);
+  }
+  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)}`);
+  }
+  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("Use --json for the full record.");
+}
+
+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).`);
+  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`);
+  }
+  if (!suspects.length) {
+    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`);
+    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.");
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (operation.name === "reward-activity.report") {
+    printRewardActivity(data);
+    return;
+  }
+  if (operation.name.startsWith("reward-review.")) {
+    printRewardReviewResult({ operation, data });
+    return;
+  }
   if (operation.name === "runtime.evidence") {
     const evidence = data.evidence || {};
     console.log(`Runtime evidence (${data.host?.requested || "unknown"}): ${evidence.status || "unknown"}.`);

package/lib/assets.js

@@ -141,6 +141,7 @@ export async function assetsGenerate(options) {
     model,
     ...(quality ? { quality } : {}),
     ...(fileName ? { fileName } : {}),
+    ...(options.transparent ? { transparentBackground: true } : {}),
   };
 
   if (!options.assumeYes) {

package/lib/commands.js

@@ -55,6 +55,7 @@ import {
   writeAssetsManifest,
 } from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
+import { rewardsCommand, reportRewardDeclaration } from "./rewards.js";
 import {
   assertAuthScope,
   ensureAuth,
@@ -272,6 +273,10 @@ export async function main() {
     await assetsCommand(options);
     return;
   }
+  if (options.command === "rewards") {
+    await rewardsCommand(options);
+    return;
+  }
   if (options.command === "thumbnail") {
     await thumbnailCommand(options);
     return;
@@ -1166,6 +1171,7 @@ export async function check(options) {
   const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
   const canonicalBuild = await loadBuildMetadata({ options, auth, buildId });
   await reportLocalProjectFindings(options, canonicalBuild?.projectLimits);
+  await reportRewardDeclaration({ options, auth, buildId });
   const result = await requestJson({
     url: `${options.apiUrl}/cli/build/${buildId}/launch-check`,
     authToken: auth.token,
@@ -2262,6 +2268,7 @@ export function parseArgs(args) {
     "noUpdateCheck",
     "allowWrite",
     "main",
+    "transparent",
     "yes",
     "json",
     "keepAssets",
@@ -2279,6 +2286,7 @@ export function parseArgs(args) {
     "reviewed",
     "noReviewLoop",
     "acceptAgreement",
+    "show",
   ]);
 
   for (let i = 0; i < rest.length; i += 1) {
@@ -2495,9 +2503,11 @@ export function parseArgs(args) {
     adminActions: raw.actions ? String(raw.actions) : "",
     adminDate: raw.date ? String(raw.date) : "",
     adminDays: raw.days ? String(raw.days) : "",
+    adminBuild: raw.build ? String(raw.build) : "",
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
     adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
     adminFile: raw.file ? String(raw.file) : "",
+    adminConfigFile: raw.config ? String(raw.config) : "",
     adminReviewedBuildVersion: raw.reviewedVersion
       ? String(raw.reviewedVersion)
       : "",
@@ -2518,6 +2528,7 @@ export function parseArgs(args) {
     model: raw.model ? String(raw.model) : "",
     quality: raw.quality ? String(raw.quality) : "",
     assetName: raw.name ? String(raw.name) : "",
+    transparent: parseBoolean(raw.transparent, false),
     out: raw.out ? String(raw.out) : "",
     target:
       raw.url ||
@@ -2838,6 +2849,9 @@ export function printHelp() {
   lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>
   lumine assets delete <assetId>
   lumine assets prune [--yes]
+  lumine rewards check
+  lumine rewards sheet <file.json>
+  lumine rewards sheet --show
   lumine thumbnail set <file>
   lumine thumbnail capture [--out <file>]
   lumine thumbnail generate ["<prompt>"] --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>
@@ -2867,6 +2881,11 @@ export function printHelp() {
   lumine admin sponsor integrity cases [--status open|pending|held|flagged|cleared|disqualified] [--json]
   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-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]
   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]
   lumine admin builds review <build-url-or-id> [--output-dir <dir>] [--wait-ms <ms>] [--interact <steps.json>] [--browser-path <path>] [--json]
@@ -2977,7 +2996,8 @@ 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
+  --dir <path>          Directory for pulled project files or a reward-review source snapshot
+  --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
   --effort <level>      Optional provider reasoning effort
@@ -3058,6 +3078,7 @@ Options:
   --quality <q>         GPT Image quality: low, medium, high, xhigh, max (default high; xhigh/max require 2.5)
   --name <fileName>     File name hint for a generated asset
   --out <path>          With thumbnail capture: also save the capture locally
+  --transparent         Ask GPT Image for a transparent background (assets generate)
   --yes                 Skip confirmation prompts (assets prune/generate, thumbnail)
 `);
 }

package/lib/constants.js

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

package/lib/rewards.js

@@ -0,0 +1,188 @@
+import fs from "fs/promises";
+import path from "path";
+
+import { requestJson } from "./http.js";
+import { findLocalProjectMetadata } from "./workspace.js";
+import { ensureAuth, assertAuthScope } from "./auth.js";
+import { resolveRequiredBuildIdOrSelected } from "./commands.js";
+
+// Creator-side reward tooling.
+//
+// An app that pays XP or Coins declares its economy in `rewards.json` at the
+// project root: rule ids, titles, amounts, tries, retry share, budgets. The
+// reviewer reads that file next to the code. Quiz rules also need questions
+// with answer keys, and those must never be project files (published source
+// is readable by every player), so they travel separately as the private
+// question sheet: `lumine rewards sheet <file.json>` uploads it to Twinkle,
+// where it is merged with rewards.json when the version is sent for review.
+
+const REWARDS_FILE = "rewards.json";
+
+async function readWorkspaceRewardsJson(options) {
+  const localProject = await findLocalProjectMetadata(
+    path.resolve(options.dir || process.cwd()),
+  );
+  if (!localProject?.rootDir) return { present: false, value: undefined };
+  const filePath = path.join(localProject.rootDir, REWARDS_FILE);
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return { present: false, value: undefined };
+    throw error;
+  }
+  try {
+    return { present: true, value: JSON.parse(raw), filePath };
+  } catch (error) {
+    throw new Error(`${REWARDS_FILE} is not valid JSON: ${error?.message || error}`);
+  }
+}
+
+async function checkDeclaration({ options, auth, buildId, rewardsJson, sheet }) {
+  return await requestJson({
+    url: `${options.apiUrl}/cli/build/${buildId}/rewards/check`,
+    method: "POST",
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+    body: {
+      ...(rewardsJson === undefined ? {} : { rewardsJson }),
+      ...(sheet === undefined ? {} : { sheet }),
+    },
+  });
+}
+
+function printDeclaration(result, { prefix = "" } = {}) {
+  const rules = Array.isArray(result?.rules) ? result.rules : [];
+  if (result?.ok) {
+    console.log(
+      `${prefix}Rewards declaration: ok (${rules.length} rule${rules.length === 1 ? "" : "s"}${result.sheetPresent ? ", question sheet on file" : ""}).`,
+    );
+    for (const rule of rules) {
+      const what =
+        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}`);
+    }
+    return;
+  }
+  console.log(`${prefix}Rewards declaration: NOT ready.`);
+  for (const error of result?.errors || []) console.log(`${prefix}  - ${error}`);
+}
+
+// Part of `lumine check`: only speaks up when the workspace declares rewards
+// or the server says the code uses the rewards SDK.
+export async function reportRewardDeclaration({ options, auth, buildId }) {
+  let local;
+  try {
+    local = await readWorkspaceRewardsJson(options);
+  } catch (error) {
+    console.error(`Local check error: ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!local.present) return;
+  try {
+    const result = await checkDeclaration({
+      options,
+      auth,
+      buildId,
+      rewardsJson: local.value,
+    });
+    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}).`);
+  }
+}
+
+export async function rewardsCommand(options) {
+  const action = String(options.positional?.[0] || "check");
+  if (options.help) {
+    printRewardsHelp();
+    return;
+  }
+  const auth = await ensureAuth(options);
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
+  if (action === "check") {
+    const local = await readWorkspaceRewardsJson(options);
+    const result = await checkDeclaration({
+      options,
+      auth,
+      buildId,
+      rewardsJson: local.present ? local.value : undefined,
+    });
+    if (options.json) {
+      console.log(JSON.stringify({ ...result, source: local.present ? "workspace" : "saved" }, null, 2));
+    } else {
+      console.log(
+        local.present
+          ? `Checked ${REWARDS_FILE} from this workspace against the question sheet on file.`
+          : `No ${REWARDS_FILE} in this workspace; checked the saved version instead.`,
+      );
+      printDeclaration(result);
+    }
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === "sheet") {
+    if (options.show) {
+      const result = await requestJson({
+        url: `${options.apiUrl}/cli/build/${buildId}/rewards/sheet`,
+        authToken: auth.token,
+        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 {
+        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)`);
+        }
+      }
+      return;
+    }
+    const file = options.positional?.[1];
+    if (!file) throw new Error("Usage: lumine rewards sheet <file.json> | --show");
+    await assertAuthScope({ options, auth, scope: "build:write" });
+    let sheet;
+    try {
+      sheet = JSON.parse(await fs.readFile(path.resolve(file), "utf8"));
+    } catch (error) {
+      throw new Error(`Could not read ${file}: ${error?.message || error}`);
+    }
+    const result = await requestJson({
+      url: `${options.apiUrl}/cli/build/${buildId}/rewards/sheet`,
+      method: "PUT",
+      authToken: auth.token,
+      timeoutMs: options.timeoutMs,
+      body: { sheet },
+    });
+    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.`);
+      printDeclaration(result);
+    }
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  printRewardsHelp();
+  throw new Error(`Unknown rewards action: ${action}`);
+}
+
+function printRewardsHelp() {
+  console.log(`Usage:
+  lumine rewards check              Validate rewards.json (workspace or saved) against the question sheet on file
+  lumine rewards sheet <file.json>  Upload the private question sheet ({ rules: { <ruleId>: { questions?, sets? } } })
+  lumine rewards sheet --show       Summarize the sheet on file (never prints answer keys)
+
+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) }] }
+Questions and answer keys never go in project files; they belong in the sheet.`);
+}

package/lib/sdk.js

@@ -27,6 +27,11 @@ export const SDK_CLI_METHODS = {
   "subjects.getSubject": { path: "api/content/subject", scopes: ["content:read"] },
   "subjects.getSubjectComments": { path: "api/content/subject-comments", scopes: ["content:read"] },
   "subjectComments.list": { path: "api/content/subject-comment-list", scopes: ["content:read"] },
+  "subjects.create": { path: "api/content/subject/create", scopes: ["content:write"], write: true },
+  "subjects.edit": { path: "api/content/subject/edit", scopes: ["content:write"], write: true },
+  "subjects.getWriteStatus": { path: "api/content/write-status", scopes: ["content:read"] },
+  "subjectComments.create": { path: "api/content/comment/create", scopes: ["content:write"], write: true },
+  "subjectComments.edit": { path: "api/content/comment/edit", scopes: ["content:write"], write: true },
   "profileComments.getProfileComments": { path: "api/content/profile-comments", scopes: ["content:read"] },
   "profileComments.getProfileCommentIds": { path: "api/content/profile-comment-ids", scopes: ["content:read"] },
   "profileComments.getCommentsByIds": { path: "api/content/profile-comments-by-ids", scopes: ["content:read"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.71",
+  "version": "0.2.76",
   "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-09T02:13:12.499Z
+Version: 1.42.0
+Updated: 2026-09-12
+Generated: 2026-09-12T07:41:17.555Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -31,7 +31,8 @@ Generated: 2026-09-09T02:13:12.499Z
 - 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.
-- Lumine agents prepare private numeric quiz rules and budgets with prepare_reward_rules (CLI: POST /build/:buildId/rewards/prepare with { config }). Creators are kids and teens: show a simple earning summary, approval status and Send for review; do not ask them to fill in technical forms. Every code or rule update that retains rewards needs a new approval before publishing. Removing the SDK automatically clears its gate and publishes without reward permission; adding it back requires a fresh approval. Other protected SDKs keep their own gates. Keep protected SDK calls explicit in project source. Existing approved live rewards continue while a draft waits; approvals never publish automatically.
+- 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.
 
 ## Token Scopes
@@ -580,13 +581,15 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Each operation slice is { cooldownSeconds, availableAt, retryAfterSeconds }.
   - serverNow is unix seconds so progress bars ignore client clock skew.
   - Pass subjectId/commentId to include per-target edit cooldowns.
-- async create({ title, description }) | scopes: content:write
-  - Returns: { subject, writeStatus }
-  - Creates a normal site subject (title + description only in v1).
+- async create({ title, description, attachment }) | scopes: content:write
+  - Returns: { subject: { id, title, description, filePath, fileName, fileSize, thumbUrl, userId, username, ... }, writeStatus }
+  - Creates a normal site subject. title up to 200 characters, description up to 20,000.
+  - attachment: { runtimeFileId } names a file the viewer uploaded through Twinkle.files.uploadGenerated (its asset id); the server verifies it is this viewer’s upload for this app, copies it into the site’s attachment storage and stores it as the subject’s real attachment (cover). Images get a thumbUrl from the site optimizer shortly after.
   - Site-wide durable cooldown: 600s between creates. 429 includes writeStatus.
-- async edit({ subjectId, title, description }) | scopes: content:write
+- async edit({ subjectId, title, description, attachment }) | scopes: content:write
   - Returns: { subject, writeStatus }
   - Own subjects only (userId === uploader). Never uses moderator edit rights.
+  - attachment: { runtimeFileId } replaces the subject attachment with one of the viewer’s uploads; attachment: null removes it; omit to leave it unchanged.
   - Per-subject edit cooldown: 10s.
 
 ### Twinkle.aiCards
@@ -674,13 +677,14 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - For subject-poster books that include poster replies, use author: subjectPoster, includeReplies: true, and replyScope: ownThread so the poster's replies to other people do not become pages.
   - Supports cursor-based pagination. Pass cursor from the previous response to load more.
   - Example: const { subjects } = await Twinkle.subjects.search({ query: searchText, limit: 12 }); const subjectId = pickedSubject.id; const page = await Twinkle.subjectComments.list(subjectId, { sortBy: 'oldest', author: 'subjectPoster', includeReplies: true, replyScope: 'ownThread', limit: 50 });
-- async create({ subjectId, content }) | scopes: content:write
+- async create({ subjectId, content, attachment }) | scopes: content:write
   - Returns: { comment, writeStatus }
-  - Adds a top-level subject comment (book page). Own subject only.
+  - Adds a top-level subject comment (book page). Own subject only. content up to 10,000 characters (longer text is cut at 10,000, so split chapters yourself).
+  - attachment: { runtimeFileId } attaches one of the viewer’s Twinkle.files.uploadGenerated uploads to the comment as a real attachment.
   - Site-wide durable cooldown: 20s between comment creates. 429 includes writeStatus.
 - async edit({ commentId, content }) | scopes: content:write
   - Returns: { comment, writeStatus }
-  - Own comments only. Per-comment edit cooldown: 10s.
+  - Own comments only. content up to 10,000 characters. Per-comment edit cooldown: 10s.
 
 ### Twinkle.profileComments
 - async getProfileComments({ profileUserId, limit, offset, sortBy, includeReplies, range, since, until } = {}) | scopes: content:read
@@ -1006,14 +1010,27 @@ world.updatePresence({ x, y, z, facing });
 
 ### Twinkle.rewards
 - await Twinkle.rewards.getStatus() | scopes: rewards:claim
-  - Returns: { mode: "live", dayKey, rules, history, balances: { xp, coins } } | { mode: "preview", rules: [], history: [], message }
-  - Read canonical earning rules (without answer keys), today’s receipts and balances. Drafts return preview mode. Unapproved or revoked published releases return an error.
+  - 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.
+  - 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.start({ ruleId }) | scopes: rewards:claim
-  - Returns: { mode: "live", challengeId, questions: [{ prompt }], reward: { xp, coins }, attemptsRemaining, expiresAt }
-  - Creates or resumes a server-issued challenge for the signed-in viewer. Render its questions and collect numeric answers in the same order. One daily challenge per rule/review; repeat starts cannot reset attempts.
-- await Twinkle.rewards.claim({ challengeId, answers: [number] }) | scopes: rewards:claim
-  - Returns: { awarded: false, attemptsRemaining } | { awarded: true, duplicate, receipt, balances: { xp, coins } }
-  - Twinkle verifies every answer, approval, current published artifact and budget before atomically recording XP and Coins. Retry the same challengeId after a lost response; a confirmed claim returns its original receipt without another award. Never update balance UI optimistically.
+  - 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.
+  - 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.
+  - 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.
+  - 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

@@ -1045,6 +1045,141 @@ mutation when a caller needs the same retry identity across processes. The CLI
 generates a fresh key for every mutation invocation; if a mutation fails, its
 JSON error includes `details.retryIdempotencyKey` for a safe exact retry.
 
+### Build XP/Coin reward approvals (any time; also a full-daily-review duty)
+
+The creator's Lumine designs the rewards and writes them into the app. The
+app declares its economy in `rewards.json` at the project root (rule ids,
+titles, XP, Coins, tries, retry share, budgets); quiz rules get their questions
+and answer keys from a private question sheet the creator's Lumine uploads with
+`lumine rewards sheet <file.json>` (never a project file: published source is
+readable by every player). **Send for review** freezes the code and proposes
+`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).
+
+```bash
+lumine admin reward-review list --json                       # pending (default)
+lumine admin reward-review list --status approved --json
+lumine admin reward-review list --status all --cursor 40 --json
+lumine admin reward-review show 2 --json                     # summary + file sizes + proposed rules
+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
+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
+```
+
+`show --dir` writes the exact reviewed snapshot (private files, including the
+app's own `rewards.json`) so the agent can read it like a pulled workspace. The
+result's `config` is the proposal: the declared economy with the sheet's
+questions merged in. It also carries `detectedRuleIds` (a heuristic scan of
+`start({ ruleId })` calls), `isLatest`/`isLive`, the published version,
+lifetime totals and what this review has already paid out.
+
+Review questions to settle with Mikey before approving:
+
+- Is the reward tied to real play or learning, or does it fire on trivial or
+  losing moments (a timer, a game over, the first minute of play)?
+- Completion rules (`verifier: "completion"`) prove nothing but elapsed time:
+  the app calls `start` when an activity begins and `claim` when it ends, and
+  the server only checks `minSeconds`, once per learner per day, and the
+  budgets. Read the code for where those calls sit, and keep the amounts and
+  `userDailyXP` small enough that a player scripting the calls would not
+  matter. Arcade Typing's stage clears are the reference: up to 10,000 XP a
+  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.
+- 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
+  for what the app actually asks of people?
+
+`rules.json` (what `--config` takes, and what the app's `rewards.json` plus
+sheet compose into):
+
+```json
+{
+  "dailyXP": 2000000, "dailyCoins": 0,
+  "userDailyXP": 10000, "userDailyCoins": 0,
+  "lifetimeXP": 200000000, "lifetimeCoins": 0,
+  "rules": [
+    { "id": "stage-1", "title": "Clear Stage 1", "xp": 300, "coins": 0,
+      "verifier": "completion", "minSeconds": 20 },
+    { "id": "e1-daily", "title": "Elementary 1 · Daily bounty", "xp": 50000, "coins": 1000,
+      "verifier": "numeric-quiz", "maxAttempts": null, "retry": { "xpPercent": 50, "coinsPercent": 0 },
+      "progression": "until-earned",
+      "sets": [{ "key": "e1-01", "questions": [{ "prompt": "...", "answer": 4, "hint": "...", "guide": { "explanation": "..." } }] }] }
+  ]
+}
+```
+
+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
+  (`"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.
+- `retry`: `{ "xpPercent": 50, "coinsPercent": 0 }` — what a correct answer pays
+  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.
+- 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
+  across all rules. `1` is "one bounty a day".
+
+Math Lab's economy (Mikey, 2026-09-12): twelve level rules, one per grade per
+day, elementary 50,000 XP + 1,000 Coins, middle 70,000 + 5,000, high
+100,000 + 10,000; `retry` 50 % XP / 0 % Coins; `maxAttempts` null;
+`userDailyClaims` 1; until-earned sets authored from the Korean curriculum.
+Arcade Typing (Mikey, 2026-09-12): XP for clearing campaign stages, up to
+10,000 XP per learner per day, no Coins. Platform ceilings: 100,000 XP /
+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.
+
+### Reward activity report (standing duty, every full daily review; added 2026-09-12)
+
+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 --days 14 --build 333 --json
+```
+
+Read-only, no run lease. 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
+  who types the stage lands well above the minimum; a script lands on it;
+- `burst`: 3+ claims within 10 minutes;
+- `sweep`: 75 %+ of an app's completion rules earned within 30 minutes (3+ claims);
+- `cap` / `daily-max`: at the per-learner day cap; at it on 3+ days of the window;
+- `guessing`: a quiz challenge with 15+ wrong answers (unlimited-tries rules).
+
+Put the app totals and every flagged row in the daily report verbatim. A
+single `cap` day is a good player having a good day; `fast` + `sweep` +
+`burst` together on one player is the script signature. None of it is proof:
+open the player with `admin identity inspect` before proposing anything, and
+propose to Mikey (revoke the app's rule, or a bucket ban) rather than acting.
+Never revoke an approval from a daily run.
+
 ## Private carry-over todos
 
 ```bash
@@ -2374,6 +2509,43 @@ not that all channel history was reviewed. Deleted messages and hidden
 attachments remain hidden. Group-channel browsing, `--all`, and `--days` are
 not supported. Never start an entire daily run just to investigate one reply.
 
+### API worker memory report (same phase, every full daily review; added 2026-09-12)
+
+On 2026-09-12 both primary API workers hit their 256 MiB V8 old-space cap at
+the same moment after ~14.6 h and aborted; core dumps then pinned both vCPUs
+and the site was down about five minutes. Since then the cluster primary
+recycles one worker politely when its heap stays above 85 % of its limit
+(immediately above 95 %), never both at once, and the unit sets `LimitCORE=0`.
+The daily run reports on that behaviour so Mikey can decide the next step
+(heap cap, retention fix, host budget).
+
+Run on the primary over management SSH (standing permission covers it):
+
+```bash
+ssh api-primary.twinkle.network 'cd /home/ec2-user/server && bash scripts/twinkle-api-service.sh memory-daily'
+```
+
+Read every line, and put these in the daily report verbatim:
+
+- each `worker slot=… uptime=… core_limit=… heap_pct=… heap_high_water_pct=…`
+  line: worker age, current heap as a share of its cap, and the highest share
+  it reached; `core_limit` must read `0` on a post-2026-09-12 generation;
+- the `worker events (24h) heap_recycles=… heap_high_warnings=… pressure_recycles=…
+  operator_recycles=… service_restarts=… oom_aborts=… unexpected_worker_exits=…`
+  line;
+- the `day-over-day … worker_heap=…` delta.
+
+Escalate in the report (a todo, and a note for Mikey) when any of these hold:
+`oom_aborts` > 0, `service_restarts` > 0, `unexpected_worker_exits` > 0, any
+worker `heap_high_water_pct` ≥ 95, or `heap_recycles` ≥ 4 in a day (the
+recycler is masking growth faster than expected). A worker at 85–90 % with a
+few recycles a day is the designed steady state, not an incident; report the
+numbers and move on. Do not raise the cap, change guard thresholds, or take a
+heap snapshot as part of the run: a snapshot inflates the worker to ~6× its
+heap and the cgroup guard kills it (observed 2026-09-12); the facility now
+refuses without that headroom. The retention investigation uses the
+`[runtime-memory] allocation-profile` lines in `twinkle-api.out.log` instead.
+
 ### API runtime-log review (same phase, every full daily review)
 
 The bot-conduct review also owns a bounded production API log review. Bot
@@ -3099,8 +3271,17 @@ farm-signal sections added that day; AI Card summon watch added 2026-08-24):
   comments, recommendations, wordle, reflections, dailyTasks, aiChat,
   lumineBuildChat, buildsEdited, buildsPlayed) for the current window vs the
   equal-length previous window, each as `{ current, previous, delta }`.
-  Presence, build edits, and build plays come from durable action/version/view
-  events, not mutable `lastActive`/`updatedAt` snapshots. Zero/Ciel are excluded
+  `activeUsers` is the union of every timestamp-windowed surface: a member who
+  logged an action (search, logout, entering Chat), wrote or recommended a
+  Subject or comment, sent a chat message, shared a reflection, talked to
+  Lumine, or saved a Build in the window, counted once however many surfaces
+  they touched. It is therefore never smaller than subjects, comments,
+  recommendations, reflections, lumineBuildChat or buildsEdited, and a member
+  active in both windows counts in both. The calendar-bucket surfaces (wordle,
+  dailyTasks, aiChat) and buildsPlayed are NOT part of that union, so
+  `activeUsers` can be smaller than those. Presence, build edits, and build
+  plays come from durable action/version/view events, not mutable
+  `lastActive`/`updatedAt` snapshots. Zero/Ciel are excluded
   from authored surfaces. Wordle, daily tasks, and AI chat use the equal
   calendar-bucket ranges in `dayWindow`; those can begin before the exact
   timestamp window but always compare the same number of days. This is the