@stage5/lumine 0.3.87 → 0.3.89

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

@@ -2481,6 +2481,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",
@@ -2904,6 +2906,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) : "",
@@ -3379,6 +3390,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/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.87",
+  "version": "0.3.89",
   "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.0
+Version: 1.82.0
 Updated: 2026-11-07
-Generated: 2026-11-07T02:35:09.137Z
+Generated: 2026-11-07T15:13:41.763Z
 
 ## 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.
@@ -71,6 +71,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 +82,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 +125,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
@@ -241,7 +243,7 @@ files:read, media:read, media:write, live:read, live:write, user:read, users:rea
   - Report live player or avatar bounds so the preview host can detect floor, wall, or out-of-bounds issues.
   - Always available in the build iframe.
   - Reports live gameplay bounds in the same coordinate space as setPlayfield.
-  - Use this for moving players or avatars so preview review and auto-fix can detect floor or wall escapes.
+  - Use this for moving players or avatars so the preview check can detect floor or wall escapes.
   - Do not report viewport-relative or screen-pixel rectangles; keep telemetry in stable game/world coordinates.
   - Example: Twinkle.preview.reportGameplayState({ playerBounds: { x: player.x, y: player.y, width: player.width, height: player.height } });
 - getGameplayTelemetry() | scopes: none
@@ -1892,6 +1894,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? }