@stage5/lumine 0.3.88 → 0.3.90

package/README.md

@@ -486,6 +486,19 @@ after validation passes and still uses the workspace's server-issued
 overwritten. Provider login and model usage stay inside the selected local CLI;
 Twinkle never receives a provider credential and does not reserve AI Energy.
 
+The project tools are Lumine's own (list, read, search, edit). Like grep,
+`search_project_files` can match plain text (the default), a JavaScript regular
+expression (`mode: "regex"`, up to 200 characters, with a time limit, one
+regex search at a time and a per-minute text budget per member), or a whole
+class with `kind: "emoji"` or `kind: "symbol"`. `kind: "emoji"` counts only
+characters that show as emoji: a text-style symbol such as an arrow or bullet
+counts only when followed by U+FE0F, otherwise it is listed under
+`kind: "symbol"`. A kind finds each one written directly and written as an
+escape: `\u25B6`, `\u{1F512}`, surrogate
+pairs, CSS `content: "\25B6"`, `🔒`, or `String.fromCodePoint(...)`. When
+results are capped, a regex runs out of time, or a long line is only partly
+checked, the result sets `truncated` and says in `note` what was left out.
+
 Every run writes a sanitized observable tool trace under
 `.twinkle/agent-runs/`. By default, the selected subscription agent reviews
 that trace after the pass and records evidence-based loop feedback without

package/lib/admin-coins.js

@@ -0,0 +1,239 @@
+// lumine admin coins: Twinkle.coins purchases and the builder tally's one-time
+// fill (the server is controllers/cli/admin/coinCharges.ts). Writes are dry
+// runs unless --confirm.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { requestJson } from "./http.js";
+
+const USAGE =
+  "Usage: lumine admin coins list --build <id> [--user <id>] [--price <priceId>] [--key <itemKey>] | refund <receiptId> --reason <text> [--keep-recipient (purchases only, not sales/takeovers)] [--confirm] | release --build <id> --price <priceId> --key <itemKey> --reason <text> [--confirm] | tally-import <buildId> --file <cells.json> --reason <text> [--replace-region <region>] [--confirm] | tally-clear <buildId> --user <id> [--region <region>] [--area <x0:z0:x1:z1>] --reason <text> [--confirm] [--json]";
+// Cells per tally-import request (COIN_TALLY_LIMITS.importBatchCells on the API).
+export const TALLY_IMPORT_BATCH_CELLS = 5000;
+// One spelling per world (review-r2 M3): COIN_TALLY_REGION_PATTERN on the API.
+const TALLY_REGION = /^[a-z0-9-]{1,64}$/;
+const TALLY_NUMBER = /^(0|-?[1-9][0-9]{0,6})$/;
+function invalid(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  throw error;
+}
+function positiveInteger(value, flag) {
+  const number = Number(String(value || "").trim());
+  if (!Number.isSafeInteger(number) || number <= 0) invalid(`${flag} must be a positive whole number. ${USAGE}`);
+  return number;
+}
+export function buildCoinsOperation({ action, target, options }) {
+  if (options.adminConfirm !== "" && options.adminConfirm !== "true")
+    invalid("Pass --confirm on its own, without a value.");
+  const confirm = options.adminConfirm === "true";
+  if (!action || action === "list") {
+    const query = new URLSearchParams({ buildId: String(positiveInteger(options.adminBuild, "--build")) });
+    if (options.adminUser) query.set("userId", String(positiveInteger(options.adminUser, "--user")));
+    if (options.adminCoinPrice) query.set("priceId", options.adminCoinPrice);
+    if (options.adminCoinKey) query.set("key", options.adminCoinKey);
+    return {
+      name: "coins.list", method: "GET", path: `/cli/admin/coins/purchases?${query}`,
+      mutates: false, requiresRun: false
+    };
+  }
+  const reason = String(options.adminReason || "").trim();
+  if (!reason) invalid(`--reason is required. ${USAGE}`);
+  if (action === "tally-import") {
+    const buildId = positiveInteger(target, "<buildId>");
+    if (!options.adminFile) invalid(`--file is required. ${USAGE}`);
+    const file = readTallyFile(options.adminFile);
+    if (file.buildId !== undefined && Number(file.buildId) !== buildId)
+      invalid(`${options.adminFile} was made for app ${file.buildId}, not ${buildId}.`);
+    const replaceRegion = String(options.adminCoinReplaceRegion || "").trim();
+    // Clearing a region is spelled out: the flag must name the file's region.
+    if (replaceRegion && replaceRegion !== file.region)
+      invalid(`--replace-region must name the file's region (${file.region}).`);
+    return {
+      name: confirm ? "coins.tally-import" : "coins.tally-import.preview",
+      method: "POST", path: "/cli/admin/coins/tally-import",
+      coinsWorkflow: "tally-import", buildId, reason, replace: Boolean(replaceRegion), file,
+      batches: tallyImportBatches(file, { buildId, replace: Boolean(replaceRegion), reason, dryRun: !confirm }),
+      mutates: confirm, requiresRun: false
+    };
+  }
+  // The admin's fix for fake builder records (review-r2 M2): one player's
+  // recorded blocks in one app, optionally one region and one area.
+  if (action === "tally-clear") {
+    const buildId = positiveInteger(target, "<buildId>");
+    const userId = positiveInteger(options.adminUser, "--user");
+    const region = String(options.adminCoinRegion || "").trim();
+    const area = String(options.adminCoinArea || "").trim();
+    if (region && !TALLY_REGION.test(region)) invalid("--region is the world name: 1 to 64 lowercase letters, digits or dashes.");
+    if (area) {
+      if (!region) invalid("--area needs --region.");
+      const parts = area.split(":");
+      if (parts.length !== 4 || !parts.every((part) => TALLY_NUMBER.test(part)))
+        invalid("--area is x0:z0:x1:z1 (whole numbers, both corners included).");
+      const [x0, z0, x1, z1] = parts.map(Number);
+      if (x1 < x0 || z1 < z0) invalid("--area is x0:z0:x1:z1 with x0 <= x1 and z0 <= z1.");
+    }
+    return {
+      name: confirm ? "coins.tally-clear" : "coins.tally-clear.preview",
+      method: "POST", path: "/cli/admin/coins/tally-clear",
+      body: { buildId, userId, ...(region ? { region } : {}), ...(area ? { area } : {}), reason, dryRun: !confirm },
+      mutates: confirm, requiresRun: false
+    };
+  }
+  if (action === "refund")
+    return {
+      name: confirm ? "coins.refund" : "coins.refund.preview", method: "POST", path: "/cli/admin/coins/refund",
+      body: {
+        receiptId: positiveInteger(target, "<receiptId>"), reason,
+        fromRecipient: !options.adminCoinKeepRecipient, dryRun: !confirm
+      },
+      mutates: confirm, requiresRun: false
+    };
+  if (action === "release") {
+    if (!options.adminCoinPrice || !options.adminCoinKey) invalid(`--price and --key are required. ${USAGE}`);
+    return {
+      name: confirm ? "coins.release" : "coins.release.preview", method: "POST", path: "/cli/admin/coins/release",
+      body: {
+        buildId: positiveInteger(options.adminBuild, "--build"), priceId: options.adminCoinPrice,
+        key: options.adminCoinKey, reason, dryRun: !confirm
+      },
+      mutates: confirm, requiresRun: false
+    };
+  }
+  invalid(USAGE);
+}
+// cells.json from firestar-land/probes/build-tally-import.mjs:
+// { format: "twinkle-coin-tally-v1", buildId?, region, at, placed: [[x, y, z, userId]], removed?: [[x, y, z]] }
+export function readTallyFile(filePath) {
+  let buffer;
+  try {
+    buffer = readFileSync(path.resolve(filePath));
+  } catch (error) {
+    invalid(`Could not read ${filePath}: ${error.message}`);
+  }
+  let file;
+  try {
+    file = JSON.parse(buffer.toString("utf8"));
+  } catch {
+    invalid(`${filePath} is not JSON.`);
+  }
+  if (file?.format !== "twinkle-coin-tally-v1") invalid(`${filePath} is not a tally file (format twinkle-coin-tally-v1).`);
+  if (!TALLY_REGION.test(String(file.region || ""))) invalid(`${filePath}: region must be 1 to 64 lowercase letters, digits or dashes (a-z 0-9 -).`);
+  if (!Number.isSafeInteger(file.at) || file.at <= 0) invalid(`${filePath}: at must be the server time (seconds) of the newest history row.`);
+  const placed = Array.isArray(file.placed) ? file.placed : invalid(`${filePath}: placed must be a list.`);
+  const removed = file.removed === undefined ? [] : Array.isArray(file.removed) ? file.removed : invalid(`${filePath}: removed must be a list.`);
+  return {
+    buildId: file.buildId, region: file.region, at: file.at, placed, removed,
+    sha256: createHash("sha256").update(buffer).digest("hex")
+  };
+}
+// The requests one file becomes: placed cells, then removed cells, at most
+// TALLY_IMPORT_BATCH_CELLS a request. Only the first may clear the region.
+export function tallyImportBatches(file, { buildId, replace, reason, dryRun }) {
+  const cells = [...file.placed.map((cell) => ["placed", cell]), ...file.removed.map((cell) => ["removed", cell])];
+  const count = Math.max(1, Math.ceil(cells.length / TALLY_IMPORT_BATCH_CELLS));
+  return Array.from({ length: count }, (_, index) => {
+    const slice = cells.slice(index * TALLY_IMPORT_BATCH_CELLS, (index + 1) * TALLY_IMPORT_BATCH_CELLS);
+    return {
+      buildId, region: file.region, at: file.at,
+      placed: slice.filter(([kind]) => kind === "placed").map(([, cell]) => cell),
+      removed: slice.filter(([kind]) => kind === "removed").map(([, cell]) => cell),
+      replace: Boolean(replace) && index === 0,
+      ...(replace && index === 0 ? { replaceRegion: file.region } : {}),
+      fileSha256: file.sha256, batchIndex: index, batchCount: count, reason, dryRun
+    };
+  });
+}
+// The same file, region, mode and batch always use the same idempotency key:
+// a re-run after a crash replays finished batches from their audit records
+// and applies only the rest.
+export function tallyImportRequestKey(batch) {
+  return `cli:tally:${batch.buildId}:${batch.fileSha256.slice(0, 16)}:${batch.replace ? "r" : "m"}:${batch.batchIndex}`;
+}
+export async function runCoinsTallyImport({ options, operation, authToken, request = requestJson, log = () => {} }) {
+  const results = [];
+  for (const batch of operation.batches) {
+    const receipt = await request({
+      method: "POST",
+      url: `${options.apiUrl}${operation.path}`,
+      authToken,
+      body: batch,
+      headers: batch.dryRun ? {} : { "x-lumine-idempotency-key": tallyImportRequestKey(batch) },
+      timeoutMs: Math.max(120000, Number(options.timeoutMs) || 0),
+    });
+    if (!receipt || receipt.ok !== true) {
+      const error = new Error(receipt?.error?.message || `Tally import batch ${batch.batchIndex + 1} failed; earlier batches stay applied. Re-run the same command to finish.`);
+      error.code = receipt?.error?.code || "CLI_ADMIN_COINS_TALLY_FAILED";
+      throw error;
+    }
+    results.push(receipt.data || {});
+    log(`batch ${batch.batchIndex + 1}/${batch.batchCount}: ${batch.placed.length} placed, ${batch.removed.length} removed`);
+  }
+  const sum = (key) => results.reduce((total, row) => total + (Number(row?.[key]) || 0), 0);
+  const last = results[results.length - 1] || {};
+  return {
+    ok: true,
+    status: "success",
+    data: {
+      dryRun: operation.batches[0]?.dryRun !== false,
+      buildId: operation.buildId,
+      region: operation.file.region,
+      at: operation.file.at,
+      fileSha256: operation.file.sha256,
+      batches: results.length,
+      regionCellsBefore: Number(results[0]?.regionCellsBefore || 0),
+      cleared: sum("cleared") || sum("wouldClear"),
+      // What --replace-region keeps (review-r2 M4): live, newer and used-up blocks.
+      replaceKeeps: results[0]?.replaceKeeps || null,
+      placed: sum("placed"),
+      removed: sum("removed"),
+      keptNewer: sum("keptNewer"),
+      keptNewerPlaced: sum("keptNewerPlaced"),
+      keptNewerRemoved: sum("keptNewerRemoved"),
+      regionCellsAfter: last.regionCellsAfter ?? null,
+      importIds: results.map((row) => row?.importId).filter(Boolean)
+    }
+  };
+}
+
+export function formatCoinsResult({ operation, data }) {
+  if (operation.name.startsWith("coins.tally-clear")) {
+    const regions = (data?.regions || []).map((row) => `${row.region} ${row.cells} (x ${row.bounds?.x0}..${row.bounds?.x1}, z ${row.bounds?.z0}..${row.bounds?.z1})`);
+    return [
+      `${data?.dryRun ? "Dry run: would clear" : "Cleared"} ${data?.dryRun ? data?.cells : data?.cleared} recorded blocks of ${data?.username || "player"} (${data?.userId}) in app ${data?.buildId}${data?.region ? `, region ${data.region}` : ", every region"}${data?.area ? `, area ${data.area.x0}:${data.area.z0}:${data.area.x1}:${data.area.z1}` : ""}.`,
+      ...(regions.length ? [`  by region: ${regions.join("; ")}`] : []),
+      `  ${data?.consumed || 0} were already used up by a sale (that sale paid them; only a refund moves Coins) · ${data?.touchedByOthers || 0} were broken or built over by another player since (a hint the block was real) · ${data?.imported || 0} came from the one-time fill.`,
+      ...(data?.dryRun ? ["Nothing was written. Add --confirm to apply."] : [`  receipt ${data?.receiptId}`]),
+    ];
+  }
+  if (operation.name.startsWith("coins.tally-import")) {
+    const keeps = data?.replaceKeeps;
+    return [
+      `${data?.dryRun ? "Dry run: would import" : "Imported"} the builder tally of app ${data?.buildId}, region ${data?.region} (history up to ${data?.at ? new Date(data.at * 1000).toISOString() : "?"}), in ${data?.batches} batch${data?.batches === 1 ? "" : "es"}:`,
+      `  region had ${data?.regionCellsBefore} recorded blocks${data?.cleared || keeps ? `; ${data?.dryRun ? "would clear" : "cleared"} ${data?.cleared || 0} older imported blocks (--replace-region)` : ""}`,
+      ...(keeps ? [`  --replace-region keeps ${keeps.total} blocks: ${keeps.live} recorded live (never touched by an import), ${keeps.newer} imported from newer history, ${keeps.consumed} used up by a sale`] : []),
+      `  ${data?.placed} placed blocks, ${data?.removed} removals${data?.keptNewer ? `; ${data.keptNewer} file cells left alone because a live, newer or used-up block holds them (${data.keptNewerPlaced || 0} placements, ${data.keptNewerRemoved || 0} removals)` : ""}`,
+      ...(data?.dryRun ? ["Nothing was written. Add --confirm to apply."] : [`  region now has ${data?.regionCellsAfter} recorded blocks · receipts ${(data?.importIds || []).join(", ")}`]),
+    ];
+  }
+  if (operation.name === "coins.list") {
+    const receipts = data?.receipts || [];
+    if (!receipts.length) return ["No purchases."];
+    return [
+      ...receipts.map((r) =>
+        `#${r.id} ${new Date(r.createdAt * 1000).toISOString()} ${r.buyer?.username || r.buyer?.id} ${r.kind} ${r.priceId}${r.key ? ` [${r.key}]` : ""} ${r.coins} Coins → ${r.destination}${r.recipient ? ` ${r.recipient.username || r.recipient.id}` : ""}${r.builders ? ` + builders ${r.builders.map((b) => `${b.userId}:${b.coins}`).join(",")}` : ""} · ${r.status}${r.holds ? " (holds)" : ""}`),
+      ...(data?.nextBefore ? [`More: re-run with the oldest id as a cursor (before ${data.nextBefore}).`] : [])
+    ];
+  }
+  if (operation.name.startsWith("coins.refund")) {
+    const takeBack = (data?.takeBackFrom || []).map((entry) => `${entry.username || entry.id} ${entry.coins}`).join(", ");
+    return [
+      `${data?.dryRun ? "Dry run: would refund" : "Refunded"} receipt #${data?.receiptId}: ${data?.refundCoins} Coins back to ${data?.buyer?.username || data?.buyer?.id}${takeBack ? `, taking back ${takeBack}` : ", taking nothing back"}${data?.platformCovers ? ` (the platform covers ${data.platformCovers} Coins)` : ""}${data?.restoresReceiptId ? `; the item returns to receipt #${data.restoresReceiptId}` : ""}.`,
+      ...(data?.dryRun ? ["Nothing was written. Add --confirm to apply."] : [])
+    ];
+  }
+  return [
+    `${data?.dryRun ? "Dry run: would release" : "Released"} receipt #${data?.receiptId} (holder ${data?.holderId}). No Coins move.`,
+    ...(data?.dryRun ? ["Nothing was written. Add --confirm to apply."] : [])
+  ];
+}

package/lib/admin.js

@@ -52,6 +52,8 @@ import { buildRolesOperation, printRoles } from "./admin-roles.js";
 import { buildSpendingOperation, completeSpendingReport, formatSpending } from "./admin-spending.js";
 import { buildCraftOperation, formatCraftResult } from "./admin-craft.js";
 import { buildNonogramOperation, formatNonogramResult } from './admin-nonogram.js';
+import { buildCoinsOperation, formatCoinsResult, runCoinsTallyImport } from './admin-coins.js';
+import { formatCoinPrices } from './rewards.js';
 import { buildArenaOperation, formatArenaResult } from "./admin-arena.js";
 import { buildJevRoutingReviewOperation, formatJevRoutingReview } from "./admin-jev-review.js";
 import { buildJevImagesOperation, formatJevImagesResult } from "./admin-jev-images.js";
@@ -1698,6 +1700,14 @@ export async function adminCommand(options) {
         runId,
         parseTarget: parseRecommendationTarget,
       });
+    } else if (operation.coinsWorkflow === "tally-import") {
+      // The builder tally's one-time fill: one request per batch of cells.
+      result = await runCoinsTallyImport({
+        options,
+        operation,
+        authToken: auth.token,
+        log: options.json ? () => {} : (line) => console.error(line),
+      });
     } else if (operation.teacherWorkflow) {
       result = await runTeacherWorkflow({
         options,
@@ -2826,6 +2836,8 @@ export function parseAdminOperation(options) {
     return buildSlidingBlockOperation({ action, options });
   }
   if (namespace === 'nonogram') return buildNonogramOperation({ action, target, options });
+  // Twinkle.coins purchases: list, refund, release (admin-coins.js); no run.
+  if (namespace === "coins") return buildCoinsOperation({ action, target, options });
   // Arena's mock-exam item bank (admin-arena.js); no run.
   if (namespace === "arena") return buildArenaOperation({ action, options });
   // Stuck Lumine Build plans and their free recheck (admin-build-plans.js).
@@ -6474,6 +6486,11 @@ export function printRewardReviewResult({ operation, data }) {
     for (const rule of config.rules)
       console.log(`  ${formatRewardRuleLine(rule)}`);
   }
+  // Coin prices, with what builder payments add (review L6, 11-07), and the
+  // same Coin warnings the website reviewer sees (residual builder risk).
+  for (const line of formatCoinPrices(config)) console.log(line);
+  for (const warning of Array.isArray(review.coinPriceWarnings) ? review.coinPriceWarnings : [])
+    console.log(`WARNING: ${warning}`);
   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)"}`,
@@ -7816,6 +7833,10 @@ function printAdminResult({ operation, result }) {
     for (const line of formatNonogramResult({ operation, data })) console.log(line);
     return;
   }
+  if (operation.name.startsWith("coins.")) {
+    for (const line of formatCoinsResult({ operation, data })) console.log(line);
+    return;
+  }
   if (operation.name.startsWith("build-plans.")) {
     for (const line of formatBuildPlansResult({ operation, data }))
       console.log(line);

package/lib/commands.js

@@ -1036,10 +1036,27 @@ export async function updateBranchFromMain(options) {
       method: "POST",
       url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/update-from-main`,
       authToken: auth.token,
-      body: projectFiles ? { projectFiles, baseFilesHash } : {},
-      timeoutMs: options.timeoutMs,
+      body: {
+        ...(projectFiles ? { projectFiles, baseFilesHash } : {}),
+        // Only an explicit --stop-lumine stops a Lumine run working on the
+        // branch (like its Stop button) before the update.
+        ...(options.stopLumine ? { stopActiveRun: true } : {}),
+      },
+      // The server waits (up to 20 s) for the stopped run to finish first.
+      timeoutMs: options.stopLumine
+        ? Math.max(Number(options.timeoutMs) || 0, 90_000)
+        : options.timeoutMs,
     });
   } catch (error) {
+    // Without --stop-lumine the server refuses, before writing anything,
+    // while a Lumine run is working on this branch.
+    if (error?.data?.code === "build_lumine_run_active") {
+      throw new Error(
+        options.stopLumine
+          ? `${error.message} Nothing was changed.`
+          : "Wait for Lumine to finish first. Lumine is working on this branch; run `lumine update-from-main` again when it is done, or rerun with --stop-lumine to stop it now (its unfinished changes are dropped). Nothing was changed.",
+      );
+    }
     if (error?.data?.code === "build_project_files_stale") {
       throw new Error(
         [
@@ -2481,6 +2498,8 @@ export function parseArgs(args) {
   const raw = {};
   const positional = [];
   const booleanFlags = new Set([
+    // lumine admin coins refund <receiptId> --keep-recipient
+    "keepRecipient",
     // lumine admin jev-images thumbnails --featured [--saved-only]
     "featured",
     "savedOnly",
@@ -2498,6 +2517,8 @@ export function parseArgs(args) {
     "published",
     "save",
     "force",
+    // lumine update-from-main --stop-lumine
+    "stopLumine",
     "noUpdateCheck",
     "allowWrite",
     "main",
@@ -2904,6 +2925,15 @@ export function parseArgs(args) {
     adminAwsProfile: raw.awsProfile,
     adminMaxStep: raw.maxStep ? String(raw.maxStep) : "",
     adminBuild: raw.build ? String(raw.build) : "",
+    // lumine admin coins (admin-coins.js)
+    adminCoinPrice: raw.price ? String(raw.price) : "",
+    adminCoinKey: raw.key ? String(raw.key) : "",
+    adminCoinKeepRecipient: Boolean(raw.keepRecipient),
+    // lumine admin coins tally-import --replace-region <region>
+    adminCoinReplaceRegion: raw.replaceRegion ? String(raw.replaceRegion) : "",
+    // lumine admin coins tally-clear --region <region> --area <x0:z0:x1:z1>
+    adminCoinRegion: raw.region ? String(raw.region) : "",
+    adminCoinArea: raw.area ? String(raw.area) : "",
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
     adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
     adminFile: raw.file ? String(raw.file) : "",
@@ -3037,6 +3067,7 @@ export function parseArgs(args) {
     summary: raw.summary ? String(raw.summary) : "",
     publish: parseBoolean(raw.publish, false),
     force: parseBoolean(raw.force, false),
+    stopLumine: parseBoolean(raw.stopLumine, false),
     saveFirst: parseBoolean(raw.save, false),
     limit: Math.min(
       Math.max(
@@ -3302,7 +3333,7 @@ export function printHelp() {
   lumine diff <twinkle-branch-url>
   lumine merge <twinkle-branch-url>
   lumine replace-main <twinkle-branch-url>
-  lumine update-from-main [twinkle-branch-url]
+  lumine update-from-main [twinkle-branch-url] [--stop-lumine]
   lumine save [--summary <text>] [--publish] [--json]
   lumine check [twinkle-build-url]
   lumine preview [--viewport phone|desktop] [--actions <json|file>] [--focus <text>] [--out <file>] [--saved] [--build <id>] [--json]
@@ -3379,6 +3410,7 @@ export function printHelp() {
   lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | import --dir <paper folder> [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked --confirm | revise --file <revisions.json> [--confirm] | picture-audit [--items <id,id,...> | --cursor <id>] [--limit 1-20] [--renders <dir of <itemId>.png>] [--output <review-list.json>]   (Arena's mock-exam bank; picture-audit is an advisory JEV image review list that never retires or edits items; import and revise are validation-only dry runs without --confirm; revise fixes a live item in place as a new content version; upload audio first with twinkle-api scripts/arena-upload-media.ts)
   lumine admin arena today-queue [--cursor <id>] | today-member --user <id> | today-import --file <reviewed-questions.json> [--confirm] | today-withdraw --user <id> (--keys <key,...> | --file <withdraw.json>) --reason <text> [--confirm]   (Today's Challenge personal queues; import and withdraw are dry runs without --confirm; withdraw removes only unserved queued questions and is audited)
   lumine admin nonogram status | add --file <pictures.json> | retire <key> | restore <key> [--confirm]   (private reviewed pictures; changes are dry runs without --confirm)
+  lumine admin coins list --build <id> [--user <id>] [--price <id>] [--key <k>] | refund <receiptId> --reason <text> [--keep-recipient] [--confirm] | release --build <id> --price <id> --key <k> --reason <text> [--confirm] | tally-import <buildId> --file <cells.json> --reason <text> [--replace-region <region>] [--confirm] | tally-clear <buildId> --user <id> [--region <region>] [--area <x0:z0:x1:z1>] --reason <text> [--confirm]   (Twinkle.coins purchases; refund writes the reverse ledger rows and gives a tally purchase's used-up builder credits back; --keep-recipient lets the platform cover a purchase recipient's share, keeps those builders' credits used up, and is refused for sales/takeovers; tally-import is the builder tally's one-time fill from server-attributed history, batched and idempotent, never changing or deleting a block recorded live; --replace-region clears only that region's older imported blocks and says what it keeps; tally-clear removes one player's recorded blocks, the admin's fix for fake records, since players cannot clear each other's; dry runs without --confirm)
   lumine admin build-plans stuck [--days <1-90>] [--all] | recheck <buildId> [<buildId> ...] [--confirm]   (Lumine Build plans stuck on one milestone: runs, Energy vs estimate, gradings, loop-guard state; recheck re-grades the current milestone with today's evaluator, free for the creator, dry run without --confirm)
   lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]
   lumine admin meetup list [--status review|active|completed|all] | show <crewId> | info <crewId> <userId> --decision ask|accept|ask-again|withdraw [--note <text>] | set-branch <crewId> <userId> --branch "<name>" [--note <text>] | branches [list [--status pending|official|rejected|all] | show <id> | approve <id> | reject <id> [--note <text>] | merge <id> --into <officialId>] | emails [list|send <id> [--fingerprint <revision>]|discard <id>|review on|off] | friends [status|on|off] | funnel [--days <1-90>] | announce-checkins [--send] [--as zero|ciel]   (Bridge Builder crews and check-ins)

package/lib/platformRules.generated.js

@@ -1,4 +1,4 @@
 // Generated by twinkle-api/scripts/generate-build-sdk-index.mjs from
 // constants/buildSdkManifest.json (platformRules, essentialSdk). Do not edit by hand.
-export const LUMINE_PLATFORM_RULES = "Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.\n\n1. Every page that draws on a <canvas> (2D, WebGL or Three.js) says what kind of page it is on <html>: data-twinkle-game for a game that fills the screen, data-twinkle-document for a normal scrolling page with a drawing pad, chart, visualizer or background effect. Without it, unless the page lays itself out with Twinkle.preview, Twinkle guesses from the canvas, and any canvas larger than 160 px, even one hidden in a tab, locks the page to one screen so it no longer scrolls. Add the attribute together with the first canvas.\n2. Games (data-twinkle-game) size themselves from Twinkle.preview: subscribe with Twinkle.preview.subscribe(listener, { immediate: true }), size canvases and renderers from layout.stage or layout.viewport, and report the play area with Twinkle.preview.setPlayfield(). Never size a game from 100vh/100vw, window.innerWidth/innerHeight or visualViewport, and never draw a fake phone or browser frame unless the creator asks for a device mockup: those fight the host and leave the game blank, cropped or scrolling on phones. Pages marked data-twinkle-document use ordinary CSS layout instead.\n3. alert(), confirm() and prompt() are silently blocked: alert shows nothing, confirm() always returns false (so the action it guards never happens) and prompt() returns null. Use in-page UI instead: a message element, an in-page confirm step, an <input>.\n4. Apps cannot open new windows or tabs: window.open() and target=\"_blank\" links do nothing, and neither does a download link to an uploaded file. Open Twinkle pages with Twinkle.app.openContent(url) from a tap, save files with Twinkle.files.saveAs({ url, fileName }) (or { blob, fileName } for a file the app made), and show other web addresses as plain text.\n5. Do not use <form> elements: native form submission is blocked, so a submit button inside a form does nothing. Handle inputs and buttons in JavaScript.\n6. Code loads only from project files and Twinkle's vendor paths (/build/vendor/...). Package imports, CDN scripts, external network calls and app-local /api/* routes fail at runtime; use the Twinkle SDK for data, AI and storage.\n7. Call only Twinkle.* methods documented in the SDK reference. An invented or guessed method name throws and breaks the feature.\n8. Twinkle.privateDb and Twinkle.sharedDb save on a user action or as an occasional snapshot, never per frame, tick or keystroke: fast repeated writes are refused with 429 and the data is lost. A privateDb value is at most 16 KB. Keep live state in memory, and use Twinkle.world for realtime multiplayer.\n9. Before changing an existing view, read its relevant event handlers, animations and state flow, and identify the behavior the edit must keep. A new appearance, reference image, renderer or performance improvement does not authorize removing an interaction, animation or capability; preserve it unless the creator explicitly asks for that change. After editing, compare the affected behavior before and after, including its active and inactive states (for example, playing and paused). Exercise those states when tools allow; a still screenshot or a clean console cannot prove motion or interaction. If a state cannot be exercised, report that limit rather than claiming it is preserved.\n10. When changing stored data or a renderer, inspect both the old save/resume shape and every reader, including fallback views. Keep existing saves readable with an explicit, non-destructive conversion and retain fields needed by another supported renderer. Verify an old save in the new version, new state after reload, and switching to the fallback (for example, 2D x/y toppings becoming 3D positions and returning to a flat view). Never silently drop saved objects or reset progress to make the new view work; an incomplete migration is part of this change to finish, not unrelated future polish.\n11. Keep local gameplay and unsaved edits separate from confirmed server state. Await storage writes and replace saved counters, scores and other durable state from the documented canonical response; Twinkle.privateDb.get/set return { item }, and the stored data is item.value (get may return item: null). Never read a guessed response shape, present a local increment as saved, or swallow a save/load error. Keep unfinished work recoverable, show a clear pending or failed-save state, and let the viewer retry deliberately without counting the same action twice. Verify canonical response restoration, rejected saves and delayed replies, not only a successful local animation.\n12. Start sound and image generation inside the viewer's tap or click handler. A Web Audio AudioContext stays silent until it is created or resumed in a tap (iPhones always enforce this), and Twinkle.ai.generateImage called from load or a timer fails with USER_ACTIVATION_REQUIRED.\n13. Call setPointerCapture only inside a pointerdown handler with that event's pointerId, wrapped in try/catch, and release only when hasPointerCapture says the element holds it. From click, mouse, timer or synthetic handlers it throws and the control stops working.\n14. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.\n15. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.";
+export const LUMINE_PLATFORM_RULES = "Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.\n\n1. Every page that draws on a <canvas> (2D, WebGL or Three.js) says what kind of page it is on <html>: data-twinkle-game for a game that fills the screen, data-twinkle-document for a normal scrolling page with a drawing pad, chart, visualizer or background effect. Without it, unless the page lays itself out with Twinkle.preview, Twinkle guesses from the canvas, and any canvas larger than 160 px, even one hidden in a tab, locks the page to one screen so it no longer scrolls. Add the attribute together with the first canvas.\n2. Games (data-twinkle-game) size themselves from Twinkle.preview: subscribe with Twinkle.preview.subscribe(listener, { immediate: true }), size canvases and renderers from layout.stage or layout.viewport, and report the play area with Twinkle.preview.setPlayfield(). Never size a game from 100vh/100vw, window.innerWidth/innerHeight or visualViewport, and never draw a fake phone or browser frame unless the creator asks for a device mockup: those fight the host and leave the game blank, cropped or scrolling on phones. Pages marked data-twinkle-document use ordinary CSS layout instead.\n3. alert(), confirm() and prompt() are silently blocked: alert shows nothing, confirm() always returns false (so the action it guards never happens) and prompt() returns null. Use in-page UI instead: a message element, an in-page confirm step, an <input>.\n4. Apps cannot open new windows or tabs: window.open() and target=\"_blank\" links do nothing, and neither does a download link to an uploaded file. Open Twinkle pages with Twinkle.app.openContent(url) from a tap, save files with Twinkle.files.saveAs({ url, fileName }) (or { blob, fileName } for a file the app made), and show other web addresses as plain text.\n5. Do not use <form> elements: native form submission is blocked, so a submit button inside a form does nothing. Handle inputs and buttons in JavaScript.\n6. Code loads only from project files and Twinkle's vendor paths (/build/vendor/...). Package imports, CDN scripts, external network calls and app-local /api/* routes fail at runtime; use the Twinkle SDK for data, AI and storage.\n7. Call only Twinkle.* methods documented in the SDK reference. An invented or guessed method name throws and breaks the feature.\n8. Twinkle.privateDb and Twinkle.sharedDb save on a user action or as an occasional snapshot, never per frame, tick or keystroke: fast repeated writes are refused with 429 and the data is lost. A privateDb value is at most 16 KB. Keep live state in memory, and use Twinkle.world for realtime multiplayer.\n9. Before changing an existing view, read its relevant event handlers, animations and state flow, and identify the behavior the edit must keep. A new appearance, reference image, renderer or performance improvement does not authorize removing an interaction, animation or capability; preserve it unless the creator explicitly asks for that change. After editing, compare the affected behavior before and after, including its active and inactive states (for example, playing and paused). Exercise those states when tools allow; a still screenshot or a clean console cannot prove motion or interaction. If a state cannot be exercised, report that limit rather than claiming it is preserved.\n10. Change how something looks by editing the code that actually renders it. First find it (search for its visible text, id or class) and read that markup, CSS rule or canvas drawing code; text and shapes drawn on a canvas change in the drawing code, not in CSS. Then style that element through its own selector or code. Do not cover a guess with broad selectors that match class-name fragments or tags across the app (for example [class*=\"panel\"] or every h1) or with !important overrides of rules you have not read: on someone else's app or a contribution branch they restyle screens nobody asked to change. If you cannot find the element, say so and name what you searched for instead of guessing broadly.\n11. When changing stored data or a renderer, inspect both the old save/resume shape and every reader, including fallback views. Keep existing saves readable with an explicit, non-destructive conversion and retain fields needed by another supported renderer. Verify an old save in the new version, new state after reload, and switching to the fallback (for example, 2D x/y toppings becoming 3D positions and returning to a flat view). Never silently drop saved objects or reset progress to make the new view work; an incomplete migration is part of this change to finish, not unrelated future polish.\n12. Keep local gameplay and unsaved edits separate from confirmed server state. Await storage writes and replace saved counters, scores and other durable state from the documented canonical response; Twinkle.privateDb.get/set return { item }, and the stored data is item.value (get may return item: null). Never read a guessed response shape, present a local increment as saved, or swallow a save/load error. Keep unfinished work recoverable, show a clear pending or failed-save state, and let the viewer retry deliberately without counting the same action twice. Verify canonical response restoration, rejected saves and delayed replies, not only a successful local animation.\n13. Start sound and image generation inside the viewer's tap or click handler. A Web Audio AudioContext stays silent until it is created or resumed in a tap (iPhones always enforce this), and Twinkle.ai.generateImage called from load or a timer fails with USER_ACTIVATION_REQUIRED.\n14. Call setPointerCapture only inside a pointerdown handler with that event's pointerId, wrapped in try/catch, and release only when hasPointerCapture says the element holds it. From click, mouse, timer or synthetic handlers it throws and the control stops working.\n15. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.\n16. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.";
 export const LUMINE_ESSENTIAL_SDK = "Features every app needs whenever they apply. When you build a new app or make a substantial change, add every one that applies as part of that change, without being asked. On a small, targeted request, add a missing one only when the request touches what it covers (a change to levels, scoring or saving: keep-place; a new screen: back-button); otherwise name it in one line so the creator can ask. Say in one line what you added. Never add one that does not apply.\n\n1. When: The app has a place worth keeping: a game, a level or score in play, an open document, drawing or editor, a quiz in progress, a chosen view or tab, a long page the viewer scrolls. Use: Register Twinkle.app.lifecycle.onSuspend(() => smallState, { work: [...] }) and, at startup, restore from await Twinkle.app.lifecycle.getResumeState(). The snapshot holds where the viewer is looking (scroll, open tab or view, selected item) and unfinished work (a game or level in play, a half-written answer, an unsaved drawing, a quiz in progress); list the work keys in { work }. A return (the phone unloaded the app, a reload, a quick switch away) gets everything back; a new visit (the next day, a new tab) starts at the app's start and gets only the work keys. Phones unload apps that are not on screen (3D apps right away) and browsers kill tabs; without this the player starts over every time.\n2. When: The app has more than one view: a list and its details, menus, chapters, pages, settings. Use: Twinkle.app.history.push on each confirmed view change and Twinkle.app.history.subscribe to restore views, so Back and Forward move inside the app instead of leaving it.\n3. When: Progress, collections, unlocks, high scores or settings the viewer expects to still have tomorrow. Use: Twinkle.privateDb (Twinkle.sharedDb for what everyone sees), written on a user action or as an occasional snapshot, never per frame.\n4. When: The app shares or links to something inside itself (a level, a post, a result). Use: Twinkle.app.getShareUrl(pathSegment) for the link, and read the segment back at startup, instead of building twin-kle.com URLs by hand.";

package/lib/rewards.js

@@ -68,6 +68,46 @@ async function checkDeclaration({
   });
 }
 
+export function formatCoinPrices(result) {
+  const prices = Array.isArray(result?.prices) ? result.prices : [];
+  if (!prices.length) return [];
+  const lines = [`Coin prices: ${prices.length}${result.spendBudget ? ` · at most ${result.spendBudget.userDailyCoins} Coins a player a day` : " · no daily spend budget"}`];
+  for (const price of prices) {
+    const limits = [
+      price.userDailyLimit ? `${price.userDailyLimit} a day` : "",
+      price.maxLifetime ? `${price.maxLifetime} ever` : "",
+      price.uniqueKey ? `one holder per key${price.keyGroup ? ` (key group ${price.keyGroup})` : ""}` : "",
+      price.offers
+        ? `resale: offers from ${price.offers.minCoins} to ${price.offers.maxCoins ?? "?"} Coins, each Sell or takeover pays the previous holder (a person: extra review); ${price.offers.maxOpenPerPlayer || 1} open per player`
+        : price.uniqueKey && price.keyGroup ? "no offers on items bought with this price" : "",
+    ].filter(Boolean).join(" · ");
+    lines.push(
+      `  ${price.id}: ${price.title} · ${coinPriceDestination(price)}${limits ? ` · ${limits}` : ""}`,
+    );
+  }
+  return lines;
+}
+// Where a price's Coins go, including builder payments (they are not removed).
+export function coinPriceDestination(price) {
+  // A 0-Coin price that pays builders is not free (round-2 review N7).
+  const base = price.coins > 0
+    ? `${price.coins} Coins ${price.destination === "owner" ? "to the app owner (extra review)" : "removed"}`
+    : price.builders ? "0 Coins of its own" : "free";
+  const b = price.builders;
+  if (!b) return base;
+  const most = Math.min(
+    b.maxCoinsPerPurchase || 100000,
+    b.coinsPerUnit * b.maxUnitsPerRecipient * (b.maxRecipients || 64),
+  );
+  const unit = b.unitName || "block";
+  const plot = b.tally
+    ? `the ${b.tally.plotSize}x${b.tally.plotSize} plot its key names ("${b.tally.keyFormat}")`
+    : "no tally declared, so nobody can be paid";
+  // r2: builders are paid from Twinkle's own block record, never the app's
+  // counts; review-r2 M2/M5: each builder paid for at most the limit.
+  return `${base} + ${b.coinsPerUnit} Coins per ${unit} to other players for the ${unit}s credited to them in Twinkle's record inside ${plot} (never the buyer or the owner; each paid for at most ${b.maxUnitsPerRecipient}; land with more than ${b.maxRecipients || 64} builders or over ${most} Coins for builders cannot be bought; extra review)`;
+}
+
 export function printDeclaration(result, { prefix = "" } = {}) {
   const rules = Array.isArray(result?.rules) ? result.rules : [];
   if (result?.ok) {
@@ -87,6 +127,8 @@ export function printDeclaration(result, { prefix = "" } = {}) {
         `${prefix}  ${rule.id}: ${rule.title} · ${rule.xp} XP + ${rule.coins} Coins · ${what}`,
       );
     }
+    // Coin prices and where each price's Coins go (approved in the same review)
+    for (const line of formatCoinPrices(result)) console.log(`${prefix}${line}`);
     // rules only a timer checks (the server's warning; never blocks)
     for (const warning of result.warnings || [])
       console.log(`${prefix}WARNING: ${warning}`);
@@ -289,6 +331,25 @@ rewards.json (project root) declares the economy the reviewer approves:
                 "maxAttempts"?, "retry"?: { "xpPercent", "coinsPercent", "paidAttempts"? }, "minSeconds"? (completion), "progression"?: "dated" | "until-earned" (quiz),
                 "bank"? (generated-quiz): { "steps": [percent, ...] rising to 100, "startStep"?, "instructions", "topics": [{ "key", "title", "description" }] } }] }
 The Earn page shows rules under their category headers and each series as one row ("up to 3 a day").
+Coin prices (Twinkle.coins) go in the same file and the same review:
+  "prices": [{ "id", "title", "howTo"?, "coins", "destination": "removed" | "owner", "userDailyLimit"?, "maxLifetime"?,
+               "uniqueKey"? (one holder per item key), "keyGroup"? (prices sharing keys; offers stay per price; fixed once players hold items),
+               "offers"?: { "minCoins", "maxCoins" (highest offer price, required), "maxOpenPerPlayer"? (default 1) } (unique items only),
+               "builders"?: { "coinsPerUnit", "maxUnitsPerRecipient" (<= 4096), "maxRecipients"? (<= 64),
+                              "maxCoinsPerPurchase"? (<= 100000), "unitName"?,
+                              "tally": { "plotSize" (<= 64), "keyFormat": "region:x:z" | "region:cx:cz" } (required; uniqueKey too) } }],
+  "spendBudget"?: { "userDailyCoins" }
+An app that only charges may leave out rules and the XP/Coin budgets. "owner" pays the app owner, "builders" pays
+other players for the blocks credited to them in Twinkle's record inside the plot the purchase key names (on top of the
+price). Each player's copy of the app records only that player's own blocks (Twinkle.coins.recordBlocks); Twinkle does
+not see the world, so it cannot tell whether a recorded block is really there. A block stays credited to its builder when
+someone else breaks or builds over it, until that builder removes it or a plot containing it is sold; only the admin can
+clear a player's fake records (lumine admin coins tally-clear). Every price in a builders price's keyGroup reads its key
+as the same plot: all builders prices there declare the same tally, a price that pays no builders cannot buy land with
+other players' recorded blocks, and plots may not overlap. Regions are lowercase a-z 0-9 -, keys are written plainly
+("main:112:-48"). "offers" lets players resell items to each other (each Sell or takeover pays the previous holder);
+all three pay a person and get extra review.
+Offers, Sells and takeovers are not limited by spendBudget; purchases (builder payments included) are.
 Questions and answer keys never go in project files; they belong in the sheet.
 archive-rematch (at most one) needs no sheet either: each day the server picks one retired
 until-earned puzzle for players who never met it and checks the answer against its frozen sheet.

package/lib/sdk.js

@@ -249,6 +249,28 @@ export const SDK_CLI_METHODS = {
   // holds no award logic; the server checks approval, version and budget.
   // Status and receipt reads use the endpoint's rewards:claim scope, but
   // only their fixed read operation is sent.
+  // Twinkle.coins reads use the same published-runtime grant as rewards.
+  // Spending (charge, offers, takeover) happens only in the website after the
+  // member confirms; the server refuses it from CLI sessions, so it is not
+  // mapped here.
+  "coins.getBalance": {
+    path: "api/coins/balance", special: "rewards", routeBase: "coins", operation: "balance",
+    scopes: ["coins:charge"], readOnly: true,
+    mapArgs: () => ({}),
+  },
+  "coins.getReceipts": {
+    path: "api/coins/receipts", special: "rewards", routeBase: "coins", operation: "receipts",
+    scopes: ["coins:charge"], readOnly: true,
+    mapArgs: (args) => ({
+      priceId: args.priceId, key: args.key, mine: args.mine === true ? true : undefined,
+      held: args.held === true ? true : undefined, cursor: args.cursor, limit: args.limit,
+    }),
+  },
+  "coins.getOffers": {
+    path: "api/coins/offers", special: "rewards", routeBase: "coins", operation: "offers",
+    scopes: ["coins:charge"], readOnly: true,
+    mapArgs: (args) => ({ priceId: args.priceId, key: args.key, mine: args.mine, cursor: args.cursor }),
+  },
   "rewards.getStatus": {
     path: "api/rewards/status",
     special: "rewards",
@@ -679,7 +701,7 @@ export async function sdkCall(options) {
       lastResult = await executeSdkHttpCall({
         options,
         method: "POST",
-        url: `${options.apiUrl}/build/${buildId}/api/rewards/${endpoint.operation}`,
+        url: `${options.apiUrl}/build/${buildId}/api/${endpoint.routeBase || "rewards"}/${endpoint.operation}`,
         authToken: auth.token,
         body,
         buildApiToken: tokenResult.token,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.88",
+  "version": "0.3.90",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.81.1
-Updated: 2026-11-07
-Generated: 2026-11-07T12:02:59.156Z
+Version: 1.82.1
+Updated: 2026-11-08
+Generated: 2026-11-08T00:36:53.981Z
 
 ## Platform rules
 Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.
@@ -16,12 +16,13 @@ Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed f
 7. Call only Twinkle.* methods documented in the SDK reference. An invented or guessed method name throws and breaks the feature.
 8. Twinkle.privateDb and Twinkle.sharedDb save on a user action or as an occasional snapshot, never per frame, tick or keystroke: fast repeated writes are refused with 429 and the data is lost. A privateDb value is at most 16 KB. Keep live state in memory, and use Twinkle.world for realtime multiplayer.
 9. Before changing an existing view, read its relevant event handlers, animations and state flow, and identify the behavior the edit must keep. A new appearance, reference image, renderer or performance improvement does not authorize removing an interaction, animation or capability; preserve it unless the creator explicitly asks for that change. After editing, compare the affected behavior before and after, including its active and inactive states (for example, playing and paused). Exercise those states when tools allow; a still screenshot or a clean console cannot prove motion or interaction. If a state cannot be exercised, report that limit rather than claiming it is preserved.
-10. When changing stored data or a renderer, inspect both the old save/resume shape and every reader, including fallback views. Keep existing saves readable with an explicit, non-destructive conversion and retain fields needed by another supported renderer. Verify an old save in the new version, new state after reload, and switching to the fallback (for example, 2D x/y toppings becoming 3D positions and returning to a flat view). Never silently drop saved objects or reset progress to make the new view work; an incomplete migration is part of this change to finish, not unrelated future polish.
-11. Keep local gameplay and unsaved edits separate from confirmed server state. Await storage writes and replace saved counters, scores and other durable state from the documented canonical response; Twinkle.privateDb.get/set return { item }, and the stored data is item.value (get may return item: null). Never read a guessed response shape, present a local increment as saved, or swallow a save/load error. Keep unfinished work recoverable, show a clear pending or failed-save state, and let the viewer retry deliberately without counting the same action twice. Verify canonical response restoration, rejected saves and delayed replies, not only a successful local animation.
-12. Start sound and image generation inside the viewer's tap or click handler. A Web Audio AudioContext stays silent until it is created or resumed in a tap (iPhones always enforce this), and Twinkle.ai.generateImage called from load or a timer fails with USER_ACTIVATION_REQUIRED.
-13. Call setPointerCapture only inside a pointerdown handler with that event's pointerId, wrapped in try/catch, and release only when hasPointerCapture says the element holds it. From click, mouse, timer or synthetic handlers it throws and the control stops working.
-14. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.
-15. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.
+10. Change how something looks by editing the code that actually renders it. First find it (search for its visible text, id or class) and read that markup, CSS rule or canvas drawing code; text and shapes drawn on a canvas change in the drawing code, not in CSS. Then style that element through its own selector or code. Do not cover a guess with broad selectors that match class-name fragments or tags across the app (for example [class*="panel"] or every h1) or with !important overrides of rules you have not read: on someone else's app or a contribution branch they restyle screens nobody asked to change. If you cannot find the element, say so and name what you searched for instead of guessing broadly.
+11. When changing stored data or a renderer, inspect both the old save/resume shape and every reader, including fallback views. Keep existing saves readable with an explicit, non-destructive conversion and retain fields needed by another supported renderer. Verify an old save in the new version, new state after reload, and switching to the fallback (for example, 2D x/y toppings becoming 3D positions and returning to a flat view). Never silently drop saved objects or reset progress to make the new view work; an incomplete migration is part of this change to finish, not unrelated future polish.
+12. Keep local gameplay and unsaved edits separate from confirmed server state. Await storage writes and replace saved counters, scores and other durable state from the documented canonical response; Twinkle.privateDb.get/set return { item }, and the stored data is item.value (get may return item: null). Never read a guessed response shape, present a local increment as saved, or swallow a save/load error. Keep unfinished work recoverable, show a clear pending or failed-save state, and let the viewer retry deliberately without counting the same action twice. Verify canonical response restoration, rejected saves and delayed replies, not only a successful local animation.
+13. Start sound and image generation inside the viewer's tap or click handler. A Web Audio AudioContext stays silent until it is created or resumed in a tap (iPhones always enforce this), and Twinkle.ai.generateImage called from load or a timer fails with USER_ACTIVATION_REQUIRED.
+14. Call setPointerCapture only inside a pointerdown handler with that event's pointerId, wrapped in try/catch, and release only when hasPointerCapture says the element holds it. From click, mouse, timer or synthetic handlers it throws and the control stops working.
+15. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.
+16. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.
 
 ## Essential SDK features
 Features every app needs whenever they apply. When you build a new app or make a substantial change, add every one that applies as part of that change, without being asked. On a small, targeted request, add a missing one only when the request touches what it covers (a change to levels, scoring or saving: keep-place; a new screen: back-button); otherwise name it in one line so the creator can ask. Say in one line what you added. Never add one that does not apply.
@@ -71,6 +72,7 @@ Features every app needs whenever they apply. When you build a new app or make a
 - word-game-entry-v1 verifies a Battery-settled missing-definition/example contribution made today in this app/runtime mode, paying each contribution once. Its platform cap is three claims per viewer/app/day. word-game-quiz-v1 is capped at five. Declare matching completion rules and normal reward review; these proofs do not approve the app themselves.
 - word-game-puzzle-v1 preserves Word Search streak bonuses using canonical puzzle reward history: daily-easy/medium/hard with optional -s10 and -s20 tiers. A learner earns each difficulty once per UTC day across every tier and release. rewards.getStatus returns wordGamePuzzle { streakDays, ruleIds, earnedLevels }; choose its ruleIds and display canonical rule amounts. Streaks count consecutive days with a puzzle reward, capped at 30. This profile checks streak eligibility and duplicate difficulty claims in addition to the approved timer; it does not simulate or prove the puzzle solve.
 - word-game-puzzle-v2 is the same daily rule and also requires a server-verified finished solve of that difficulty today (Twinkle.wordMaster.startPuzzle and sendPuzzleEvents). word-search-champion-v1 pays only the rank-1 viewer of a completed UTC month on the server-written verified:month:YYYY-MM board (score, then earliest), once per month and only after the month is final (07:00 UTC on the 2nd, when its last boards can no longer take scores); once anyone collected a month, nobody else can; a removed or fully banned #1 passes the prize to the next eligible player; The daily Twinkle review confirms each month’s winner from the server’s record of their solves before the prize opens (a disqualified winner passes it to the next eligible player). rewards.getStatus returns wordSearchChampion: { month, months, claimable, checking } — months are ready to collect; checking lists wins still being confirmed (show a checking message, no collect button). Show the champion banner from that status, never from app storage.
+- Twinkle.coins prices are part of the app's rewards review (rewards.json prices + spendBudget). Using Twinkle.coins requires the same approval as Twinkle.rewards; the website, never the app, confirms every purchase. Use getReceipts as the only proof of who owns a bought item.
 
 ## AI decision design
 - Twinkle.ai.decide runs JEV, a model for narrow decisions over supplied text or structured state, and it is free for viewers: decisions are covered by Twinkle and never use their AI Energy. Whenever an app makes a judgment that ordinary code can only approximate, consider JEV first. Proven patterns: an opponent or boss coach that reads the player's habits (favourite lane, repeated trick, cheese move) and picks a counter-plan from a fixed list, as in Red Square's boss and Open Football's opponent coach; NPCs that understand what a player types and choose an action; classifying or scoring user submissions; ranking supplied candidates; and picking the next exercise or difficulty from evidence about the learner. Any app with an AI opponent, NPC, or adaptive difficulty should decide explicitly whether JEV improves it. These are examples to reason from, not a keyword checklist or a requirement to add AI to every app.
@@ -81,7 +83,7 @@ Features every app needs whenever they apply. When you build a new app or make a
 - Call at meaningful user actions or discrete app decision points, not every render, animation frame, keystroke, or background poll. Batch work, debounce changing input, keep one request active per decision flow, and discard results whose app state changed while waiting. Keep rendering, movement, and controls local and responsive. JEV decisions are covered by Twinkle and never use the viewer's AI Energy; the runtime AI rate limits still apply. Handle unavailable, timeout, and rate-limit errors with a clear retry or an explicitly local fallback; never fabricate an AI answer or run an automatic retry loop. Consider the guest and offline experience before making AI essential.
 
 ## 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
+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, coins:charge
 
 ## Namespaces
 
@@ -124,7 +126,8 @@ files:read, media:read, media:write, live:read, live:write, user:read, users:rea
 
 ### Twinkle.app
 - async getInfo() | scopes: none
-  - Returns: App info object from the parent ({ buildId, appUrl, source, artifactVersionId }) or null
+  - Returns: App info object from the parent ({ buildId, ownerId, ownerUsername, appUrl, source, artifactVersionId }) or null
+  - ownerId/ownerUsername name the app's owner and are the same for every viewer (null on older hosts). Use ownerId to honour owner-only records (e.g. admin actions) by comparing it with the server-set userId on sharedDb entries, instead of hard-coding an id. It is not a permission check: the server still decides what a viewer may do.
   - Cached after the first call for the iframe session.
   - source is 'published' on the app page and 'workspace' in the editor preview; artifactVersionId is the published release this frame runs (null in the workspace). Stamp it on your own telemetry rows instead of a hand-written release label, so data can be tied to an exact version. Hosts older than website 2.3.113 omit source and artifactVersionId; treat a missing value as unknown.
 - async getShareUrl(pathSegment) | scopes: none
@@ -1892,6 +1895,57 @@ world.updatePresence({ x, y, z, facing });
   - Report a wrong or unclear bank question the learner has seen.
   - One report per learner per question; three reports hide it from everyone. Show a small 'report this problem' action next to the question.
 
+### Twinkle.coins
+- await Twinkle.coins.getBalance() | scopes: coins:charge
+  - Returns: { mode: "live" | "preview", coins, prices: [{ id, title, howTo?, coins, destination, uniqueKey, userDailyLimit?, maxLifetime?, offers?: { minCoins, maxCoins } }], spendBudget: { userDailyCoins } | null, spentToday }
+  - Read the viewer's Coin balance and this app's approved prices.
+  - Show prices from this response, never hard-coded numbers: the reviewer may change them. In a draft preview the prices come from the draft's rewards.json and mode is "preview".
+- await Twinkle.coins.charge({ priceId, key?, payload?, requestId? }) | scopes: coins:charge
+  - Returns: { mode: "live", receipt: { id, priceId, key, kind: "purchase" | "sale" | "takeover", coins, destination: "removed" | "owner" | "holder", buyer: { id, username }, recipient: { id, username } | null, payload, builders?: [{ userId, units, coins }], status: "active" | "transferred" | "released" | "refunded", holds, previousReceiptId, offerId, createdAt, preview? }, balances: { coins }, replayed } | { mode: "preview", receipt: { id: "preview-…", preview: true, … }, balances, message }
+  - Buy one approved price. Twinkle asks the player to confirm in its own box first.
+  - Declare every price in rewards.json: "prices": [{ "id", "title", "howTo"?, "coins", "destination": "removed" | "owner", "userDailyLimit"?, "maxLifetime"?, "uniqueKey"?, "keyGroup"?, "offers"?: { "minCoins", "maxCoins", "maxOpenPerPlayer"? } }] and optionally "spendBudget": { "userDailyCoins" }. offers.maxCoins (required with offers) is the highest price an offer may be. spendBudget limits purchases (builder payments included), not offers, Sells or takeovers. Prices are approved with the app's rewards review; an app that only charges may leave out rules and the XP/Coin budgets.
+  - A price may also pay builders (Firestar's World pays 50 Coins a block): declare "builders": { "coinsPerUnit", "maxUnitsPerRecipient" (up to 4,096), "maxRecipients"? (up to 64), "maxCoinsPerPurchase"? (all builders together, up to 100,000), "unitName"?, "tally": { "plotSize" (1 to 64), "keyFormat": "region:x:z" | "region:cx:cz" } } with uniqueKey: true. The purchase key names the plot: "region:x:z" is its lowest corner in blocks (e.g. "main:112:-48" covers x 112..127, z -48..-33 with plotSize 16), "region:cx:cz" a grid square (x from cx × plotSize); full height. Write keys plainly: the region in lowercase letters, digits and dashes, numbers without leading zeros, "+" or "-0" (anything else is build_coin_tally_key_invalid). Twinkle itself works out who is paid, from its record of who placed each block (Twinkle.coins.recordBlocks): every player credited with blocks inside that plot, except the buyer and the app owner, gets their blocks × coinsPerUnit on top of the price, at most maxUnitsPerRecipient blocks each (a builder with more is paid that many). The app never names builders or counts (a builders field is ignored). The confirmation box shows every builder and share; a plot with no other players' credited blocks costs just the price. The tally belongs to the key group: every price sharing that keyGroup (plain and free prices too) reads its key as the same plot, all builders prices in it must declare the same tally, a price that pays no builders is refused on land with other players' credited blocks (build_coin_builders_price_required, details { priceIds, builders }: buy with a price in priceIds), and a plot that overlaps a plot someone holds in the key group is refused (build_coin_plot_overlap, details { key, holderId }). A purchase uses up the credits inside its plot, so the same builders are never paid twice (an admin refund gives them back). Refused too: land whose builders would get more than maxCoinsPerPurchase, or with more builders than maxRecipients (build_coin_builders_over_limit, details { builders, units, recorded, coins, limits }; the admin can clear fake records). A price without tally cannot pay builders (refused at check, review and charge).
+  - Twinkle shows the player a confirmation box outside the app naming the item, the price and where the Coins go ("The Coins are removed" or "go to <owner>"). A player who says no gets an error with code build_coin_cancelled. Nothing is charged until they say yes.
+  - uniqueKey prices need key (up to 128 of A-Z a-z 0-9 . _ : -, e.g. "main:12:-4"): one player holds a key at a time. A held key is refused with build_coin_key_taken (use makeOffer when the price takes offers) or build_coin_key_owned. Prices with the same keyGroup share keys (e.g. a plain land purchase and a claim that pays builders both use keyGroup "plots", so one plot has one holder). Once players hold items, a later release must keep each held item's price in the same key group and keep every held key group declared (build_coin_key_group_held at check, review and publish); a key held under an older group is never sold again.
+  - payload is optional JSON up to 1,024 characters stored on the receipt (e.g. plot bounds).
+  - Refusals are errors with a code and a sentence to show: build_coin_insufficient, build_coin_daily_limit, build_coin_lifetime_limit, build_coin_spend_budget, build_coin_self_payment (the owner cannot buy an owner-paid price from their own app), build_coin_quote_changed (the price went up since the box was shown, or its destination changed; a builder split that changed without raising the total goes ahead with Twinkle's split), build_coin_not_live (draft or unapproved version).
+  - Pass the same requestId (8 to 64 of A-Z a-z 0-9 _ -) again after a lost reply to get the first receipt back without paying twice. Sales and takeovers get server requestIds ("offer:<offerId>") an app cannot choose.
+  - Drafts and previews never charge: the owner's preview returns a receipt with preview: true and id "preview-…" and the balance unchanged. Never treat a preview receipt as ownership.
+- await Twinkle.coins.getReceipts({ priceId?, key?, mine?, held?, cursor?, limit? }) | scopes: coins:charge
+  - Returns: { mode: "live", receipts: [{ id, priceId, key, kind: "purchase" | "sale" | "takeover", coins, destination: "removed" | "owner" | "holder", buyer: { id, username }, recipient: { id, username } | null, payload, builders?: [{ userId, units, coins }], status: "active" | "transferred" | "released" | "refunded", holds, previousReceiptId, offerId, createdAt, preview? }], nextCursor } | { mode: "preview", receipts: [] }
+  - Read server-written purchase receipts for this app: who holds which item.
+  - Receipts are written only by Twinkle's server inside the charge, so they are the proof of ownership no client can forge. Decide who owns an item from getReceipts({ priceId, held: true }) (holds: true is the current holder of a unique key), not from sharedDb, privateDb or app state. Page with nextCursor (newest first, up to 50).
+  - The viewer reads all of their own receipts (as buyer or recipient). Other players' receipts appear only while they hold an item, with only id, priceId, key, kind, coins (the last price), buyer, payload, status, holds and createdAt (no destination, recipient or builder split). A refunded or released receipt no longer holds its item; a sold or taken-over one shows status "transferred" and the new holder has a newer receipt for the same key.
+- await Twinkle.coins.recordBlocks({ region, placed?: [[x, y, z], ...], removed?: [[x, y, z], ...] }) | scopes: coins:charge
+  - Returns: { mode: "live", recorded: { placed, removed, keptForOthers }, today: { cells, limit } } | { mode: "preview", recorded: { placed: 0, removed: 0, keptForOthers: 0 }, message }
+  - Record the blocks this player placed or broke, so builders are paid from Twinkle's own record when land is bought.
+  - Only for apps whose approved prices pay builders with a tally (build_coin_tally_off otherwise). Twinkle records the blocks as the signed-in player's own (from their website session; the app cannot name anyone else). A block placed on an empty cell is credited to that player. Once credited, a block stays that player's credit when anyone else breaks or builds over it (the record notes who did, for the admin); the credit ends only when that player sends its removal, or when a plot containing it is sold. So a removal or placement of another player's block changes nothing (counted in recorded.keptForOthers). Twinkle cannot see the world: it trusts each player's own reports of their own blocks, and only the admin can clear a player's records (lumine admin coins tally-clear).
+  - region is the world's name (1 to 64 lowercase letters, digits or dashes: a-z 0-9 -), the same name the purchase keys use. Cells are [x, y, z] whole numbers (real numbers, not strings): x and z within ±1,000,000, y from -512 to 512.
+  - Send batches: 1 to 64 blocks a call, each block once per call with its latest change. Record only blocks the player placed or broke by hand, never blocks the game made (water, lava results, revealed ores, falling sand, grown trees), and send a removal only for a block a player had placed (breaking natural ground needs no call). Calls run one at a time in the order you make them (the SDK waits for each answer before sending the next), so a newer change is never undone by an older one.
+  - Limits per player per app: 5 blocks a second with bursts of 160 (each call counts at least 4), 20,000 blocks a day. Over the pace: build_coin_tally_throttled with details { retryAfterSeconds }: keep the blocks and send them again after that wait. Over the day: build_coin_tally_daily_limit. Never call it on every frame; flush about once a second.
+  - Only the approved published release records. In a draft preview the call is checked and answered with mode "preview", and nothing is written.
+- await Twinkle.coins.makeOffer({ priceId, key, coins }) | scopes: coins:charge
+  - Returns: { mode: "live", offer: { id, priceId, key, coins, status: "open" | "kept" | "sold" | "taken" | "withdrawn" | "closed" | "failed" | "lapsed", offerer: { id, username }, holder: { id, username }, createdAt, respondedAt, takeoverAt, lapsesAt, canTakeOver, saleReceiptId }, replayed }
+  - Offer to buy a unique item another player holds. Twinkle asks the player to confirm first.
+  - Only items bought under a price with offers take offers (a keyGroup shares keys, not offers); a builders price may declare offers too, and then its last price is the full total paid (price plus builder Coins). A sale or takeover pays only the previous holder, never the builders again. coins must be at least offers.minCoins and more than the price last paid for that key, but never more than offers.maxCoins: once the last price reaches offers.maxCoins an offer of exactly offers.maxCoins is enough (getReceipts shows the last price; build_coin_offer_too_low returns details.minimumOffer, build_coin_offer_too_high details.maximumOffer). Offers are not limited by spendBudget. No Coins move or are held now, but a player's open offers in the app together cannot exceed their balance (build_coin_insufficient). If the item changed hands after the box opened: build_coin_quote_changed.
+  - One open offer per item (build_coin_offer_exists) and one open offer per player in the app unless the price declares offers.maxOpenPerPlayer (build_coin_offer_limit); at most 3 offers per player per app per day (build_coin_offer_rate_limited). The holder always gets a site notification, even if they muted the app, and answers Keep or Sell. After a Keep, a withdraw or a lapse the same player cannot offer on that item for 7 days (build_coin_offer_cooldown, details.retryAt). If the holder does not answer in 30 days, the offerer may buy it with takeover at the offered price between day 30 and day 44 (offer.lapsesAt); the Coins go to the previous holder. If the app's approval is revoked or the app is unpublished (or a release goes live after a time the app was not live), open offers end with status "closed" and a closeReason, no Coins move, and both players are notified.
+- await Twinkle.coins.respondOffer({ offerId, decision: "keep" | "sell" }) | scopes: coins:charge
+  - Returns: { mode: "live", status: "kept" | "sold" | "failed" | "closed" | "lapsed", receipt?, balances?, offer? }
+  - The holder answers an offer. Twinkle asks the holder to confirm either answer.
+  - Sell moves the item to the offerer and pays the holder the offered Coins at once. If the offerer can no longer pay, the status is "failed" and the holder keeps the item. If a newer release stopped this price taking offers (or lowered offers.maxCoins below the offer), the status is "closed" and nothing moves. Keep stops this offer and its 30-day takeover, and the offerer cannot offer on the item again for 7 days. The holder may still Keep after day 30, until the offerer buys; the offerer is then notified that the holder came back and kept it, and when they may offer again.
+- await Twinkle.coins.takeover({ offerId }) | scopes: coins:charge
+  - Returns: { mode: "live", status: "taken" | "closed" | "lapsed", receipt?, balances?, replayed }
+  - After 30 days without an answer, the offerer buys the item at the offered price.
+  - Allowed only when offer.canTakeOver is true (server clock: 30 days after the offer, with no answer). Twinkle asks the player to confirm. The Coins go to the previous holder and the price becomes the item's new last price. Too early: build_coin_takeover_early with details.takeoverAt. An offer nobody acts on for 14 more days lapses (day 44, offer.lapsesAt).
+- await Twinkle.coins.withdrawOffer({ offerId }) | scopes: coins:charge
+  - Returns: { mode: "live", offer: { id, priceId, key, coins, status: "open" | "kept" | "sold" | "taken" | "withdrawn" | "closed" | "failed" | "lapsed", offerer: { id, username }, holder: { id, username }, createdAt, respondedAt, takeoverAt, lapsesAt, canTakeOver, saleReceiptId } }
+  - Take back your own open offer. Twinkle asks the player to confirm first.
+  - A player who says no gets build_coin_cancelled and the offer stays open. After a withdraw the same player cannot offer on that item for 7 days. Withdraw works even after a release stopped the price taking offers; such offers also end when that release goes live and no longer count as the player's open offer.
+- await Twinkle.coins.getOffers({ priceId?, key?, mine?: "received" | "made", cursor? }) | scopes: coins:charge
+  - Returns: { mode: "live", offers: [{ id, priceId, key, coins, status: "open" | "kept" | "sold" | "taken" | "withdrawn" | "closed" | "failed" | "lapsed", offerer: { id, username }, holder: { id, username }, createdAt, respondedAt, takeoverAt, lapsesAt, canTakeOver, saleReceiptId }], nextCursor }
+  - List offers on one item (key) or the viewer's own offers.
+  - Pass key for one item's offers (any status), mine: "received" for open offers waiting for the viewer's answer, or mine: "made" for the viewer's own. On offers the viewer is not part of, offerer, coins, respondedAt, canTakeOver and saleReceiptId are left out. The notification target is { coinOfferId }.
+
 ### Twinkle.cardCraft
 - await Twinkle.cardCraft.getStatus() | scopes: cardCraft:read
   - Returns: { mode: "live" | "preview", available, reason?: "not_approved" | "not_declared" | "invalid" | "published_app_required", recipe: { kinds: [{ id, label, description, params }], tiers: { "1": [kindId] … "6": [kindId] }, acceptedLevels: number[] } | null, problems?: string[], message? }