@stage5/lumine 0.2.91 → 0.2.92

package/lib/admin.js

@@ -1699,6 +1699,61 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (
+    namespace === "cardcraft-review" ||
+    namespace === "cardcraft-reviews" ||
+    namespace === "cardcraft"
+  ) {
+    // AI Card crafting recipes (cardcraft.json). Same reviewer as rewards and,
+    // like rewards, never part of a delegated daily run.
+    if (!action || action === "list") {
+      return readOperation(
+        "cardcraft-review.list",
+        withQuery("/cli/admin/cardcraft-reviews", {
+          status: parseChoice(
+            options.adminStatus || "pending",
+            "--status",
+            REWARD_REVIEW_STATUSES,
+          ),
+          beforeId: options.adminCursor
+            ? parseRequiredInteger(options.adminCursor, "--cursor", 1)
+            : "",
+        }),
+        { requiresRun: false },
+      );
+    }
+    if (action === "show" || action === "get") {
+      const reviewId = parseRequiredInteger(target, "Card crafting review ID", 1);
+      return readOperation(
+        "cardcraft-review.show",
+        `/cli/admin/cardcraft-reviews/${reviewId}`,
+        { requiresRun: false, reviewId },
+      );
+    }
+    if (REWARD_REVIEW_DECISIONS.includes(action)) {
+      const reviewId = parseRequiredInteger(target, "Card crafting review ID", 1);
+      const reason = String(options.adminReason || "").trim();
+      if (action !== "approve" && !reason) {
+        throw cliValidationError(
+          `lumine admin cardcraft-review ${action} <id> needs --reason <text> the creator will read.`,
+        );
+      }
+      if (reason.length > 1000) {
+        throw cliValidationError("--reason must be at most 1000 characters.");
+      }
+      return writeOperation(
+        "cardcraft-review.decide",
+        "POST",
+        `/cli/admin/cardcraft-reviews/${reviewId}`,
+        { decision: action, reason },
+        { requiresRun: false, reviewId, decision: action },
+      );
+    }
+    throw cliValidationError(
+      "Usage: lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve <id> [--reason <text>] | reject <id> --reason <text> | revoke <id> --reason <text>.",
+    );
+  }
+
   if (namespace === "chat-reports" || namespace === "chat-report") {
     // Members' in-chat message reports. Like reward reviews they are handled
     // any time, never inside a daily-run lease; recording an outcome only
@@ -4339,6 +4394,70 @@ function printChatSafetyResult({ operation, data }) {
   return false;
 }
 
+function formatCardCraftReviewLine(review) {
+  return `#${review.id} · ${review.status}${review.isLive ? " (live)" : ""} · Build ${review.buildId}${review.appTitle ? ` "${review.appTitle}"` : ""}${review.ownerUsername ? ` by ${review.ownerUsername}` : ""}${review.reason ? ` · ${review.reason}` : ""}`;
+}
+
+function printCardCraftReviewResult({ operation, data }) {
+  if (operation.name === "cardcraft-review.list") {
+    const reviews = Array.isArray(data.reviews) ? data.reviews : [];
+    console.log(
+      `${reviews.length} card crafting review(s) (${data.filter || "pending"}):`,
+    );
+    for (const review of reviews)
+      console.log(`  ${formatCardCraftReviewLine(review)}`);
+    if (data.nextCursor) console.log(`More: --cursor ${data.nextCursor}`);
+    return;
+  }
+  const review = data.review || {};
+  if (operation.name === "cardcraft-review.decide") {
+    console.log(
+      `Decision recorded: ${operation.decision} → #${review.id} is ${review.status}.`,
+    );
+    if (review.status === "approved")
+      console.log(
+        "Crafting in the published app now uses this recipe (no republish needed).",
+      );
+    if (review.status === "revoked")
+      console.log(
+        "New crafts stopped. Existing assets stay with their cards.",
+      );
+    return;
+  }
+  console.log(formatCardCraftReviewLine(review));
+  if (review.craftedCount !== undefined)
+    console.log(`Assets crafted under this recipe: ${review.craftedCount}`);
+  for (const problem of review.problems || [])
+    console.log(`  problem: ${problem}`);
+  const declaration = review.declaration || {};
+  if (declaration.guidance) console.log(`Guidance: ${declaration.guidance}`);
+  for (const kind of declaration.kinds || []) {
+    console.log(`Kind ${kind.id} "${kind.label}"${kind.description ? ` — ${kind.description}` : ""}`);
+    for (const [name, param] of Object.entries(kind.params || {})) {
+      const shape =
+        param.type === "enum"
+          ? `one of ${param.values.join(", ")}`
+          : param.type === "integer" || param.type === "number"
+            ? `${param.type} ${param.min}-${param.max}${param.scaleWithTier ? " (scales with colour)" : ""}`
+            : param.type === "string"
+              ? `text up to ${param.maxLength}`
+              : param.type;
+      console.log(`    ${name}: ${shape}`);
+    }
+  }
+  const colours = ["", "blue", "pink", "orange", "magenta", "gold", "black"];
+  for (const level of ["1", "2", "3", "4", "5", "6"]) {
+    const kinds = (declaration.tiers || {})[level];
+    console.log(
+      `  ${level} ${colours[Number(level)]}: ${kinds?.length ? kinds.join(", ") : "not craftable"}`,
+    );
+  }
+  for (const event of review.events || [])
+    console.log(
+      `  ${new Date(event.createdAt * 1000).toISOString()} ${event.action} by ${event.actorId}${event.reason ? `: ${event.reason}` : ""}`,
+    );
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
   if (printChatSafetyResult({ operation, data })) return;
@@ -4350,6 +4469,10 @@ function printAdminResult({ operation, result }) {
     printRewardReviewResult({ operation, data });
     return;
   }
+  if (operation.name.startsWith("cardcraft-review.")) {
+    printCardCraftReviewResult({ operation, data });
+    return;
+  }
   if (operation.name === "runtime.evidence") {
     const evidence = data.evidence || {};
     console.log(

package/lib/cardcraft.js

@@ -0,0 +1,141 @@
+import fs from "fs/promises";
+import path from "path";
+
+import { requestJson } from "./http.js";
+import { findLocalProjectMetadata } from "./workspace.js";
+import { ensureAuth, assertAuthScope } from "./auth.js";
+import { resolveRequiredBuildIdOrSelected } from "./commands.js";
+
+// Creator-side AI Card crafting tooling (Twinkle.cardCraft).
+//
+// An app declares what AI Cards can become in it in `cardcraft.json` at the
+// project root: kinds (pet, snack, furniture …) with their parameters, and
+// which kinds each card colour (1 blue … 6 black) can become. A reviewer
+// approves the recipe; the approved copy is what crafting uses, so editing
+// the file changes nothing live until the next approval.
+
+const CARDCRAFT_FILE = "cardcraft.json";
+
+async function readWorkspaceCardCraftJson(options) {
+  const localProject = await findLocalProjectMetadata(
+    path.resolve(options.dir || process.cwd()),
+  );
+  if (!localProject?.rootDir) return { present: false, value: undefined };
+  let raw;
+  try {
+    raw = await fs.readFile(path.join(localProject.rootDir, CARDCRAFT_FILE), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return { present: false, value: undefined };
+    throw error;
+  }
+  try {
+    return { present: true, value: JSON.parse(raw) };
+  } catch (error) {
+    throw new Error(`${CARDCRAFT_FILE} is not valid JSON: ${error?.message || error}`);
+  }
+}
+
+function printCheck(result) {
+  if (!result?.ok) {
+    console.log("Card crafting recipe: NOT ready.");
+    for (const error of result?.errors || []) console.log(`  - ${error}`);
+    return;
+  }
+  const summary = result.summary || {};
+  console.log(
+    `Card crafting recipe: ok (${(summary.kinds || []).length} kind(s); card colours ${(summary.acceptedLevels || []).join(", ") || "none"}).`,
+  );
+  for (const kind of summary.kinds || [])
+    console.log(`  ${kind.id}: ${kind.label} · params ${kind.params.join(", ") || "none"}`);
+  if (result.nextStep) console.log(result.nextStep);
+}
+
+export async function cardcraftCommand(options) {
+  const action = String(options.positional?.[0] || "check");
+  if (options.help) {
+    printCardCraftHelp();
+    return;
+  }
+  const auth = await ensureAuth(options);
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
+  if (action === "check") {
+    const local = await readWorkspaceCardCraftJson(options);
+    const result = await requestJson({
+      url: `${options.apiUrl}/build/${buildId}/cardcraft/check`,
+      method: "POST",
+      authToken: auth.token,
+      timeoutMs: options.timeoutMs,
+      body: local.present ? { cardcraftJson: local.value } : {},
+    });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(
+        local.present
+          ? `Checked ${CARDCRAFT_FILE} from this workspace.`
+          : `No ${CARDCRAFT_FILE} in this workspace; checked the saved version instead.`,
+      );
+      printCheck(result);
+    }
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === "status") {
+    const result = await requestJson({
+      url: `${options.apiUrl}/build/${buildId}/cardcraft`,
+      authToken: auth.token,
+      timeoutMs: options.timeoutMs,
+    });
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log(`Card crafting: ${result.state}. ${result.message || ""}`.trim());
+      if (result.latestReview)
+        console.log(
+          `Latest review #${result.latestReview.id}: ${result.latestReview.status}${result.latestReview.reason ? ` · ${result.latestReview.reason}` : ""}`,
+        );
+      for (const problem of result.problems || []) console.log(`  - ${problem}`);
+    }
+    return;
+  }
+  if (action === "review") {
+    await assertAuthScope({ options, auth, scope: "build:write" });
+    const result = await requestJson({
+      url: `${options.apiUrl}/build/${buildId}/cardcraft/reviews`,
+      method: "POST",
+      authToken: auth.token,
+      timeoutMs: options.timeoutMs,
+      body: {},
+    });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    if (result.state === "approved")
+      console.log(`The saved ${CARDCRAFT_FILE} is already the approved recipe (#${result.reviewId}).`);
+    else
+      console.log(
+        `Sent the saved ${CARDCRAFT_FILE} of Build ${buildId} for review (request #${result.reviewId}${result.duplicate ? ", already waiting" : ""}). Any approved recipe keeps working until this one is approved.`,
+      );
+    return;
+  }
+  printCardCraftHelp();
+  throw new Error(`Unknown cardcraft action: ${action}`);
+}
+
+function printCardCraftHelp() {
+  console.log(`Usage:
+  lumine cardcraft check    Validate cardcraft.json (workspace, else the saved version)
+  lumine cardcraft status   Approved / waiting for review / needs review
+  lumine cardcraft review   Send the saved cardcraft.json for review
+
+cardcraft.json (project root) says what AI Cards can become in this app:
+  { "guidance"?: "short creative brief",
+    "kinds": [{ "id", "label", "description"?,
+                "params": { "<name>": { "type": "enum", "values": [...] }
+                                     | { "type": "integer" | "number", "min", "max", "scaleWithTier"? }
+                                     | { "type": "boolean" } | { "type": "string", "maxLength" } } }],
+    "tiers": { "1": ["<kind>"], … "6": ["<kind>"] } }
+Card colours: 1 blue, 2 pink, 3 orange, 4 magenta, 5 gold, 6 black (grander as they go up);
+quality (common … legendary) sets the finish effects. A card can be crafted once, ever;
+the asset stays with the card when it is sold. Use Twinkle.cardCraft in the app.`);
+}

package/lib/commands.js

@@ -58,6 +58,7 @@ import {
 } from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
 import { rewardsCommand, reportRewardDeclaration } from "./rewards.js";
+import { cardcraftCommand } from "./cardcraft.js";
 import { chatlogCommand } from "./chatlog.js";
 import {
   assertAuthScope,
@@ -284,6 +285,10 @@ export async function main() {
     await rewardsCommand(options);
     return;
   }
+  if (options.command === "cardcraft") {
+    await cardcraftCommand(options);
+    return;
+  }
   if (options.command === "thumbnail") {
     await thumbnailCommand(options);
     return;
@@ -2956,6 +2961,7 @@ export function printHelp() {
   lumine rewards sheet <file.json>
   lumine rewards sheet --show
   lumine rewards review
+  lumine cardcraft check|status|review
   lumine thumbnail set <file>
   lumine thumbnail capture [--out <file>]
   lumine thumbnail generate ["<prompt>"] --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>
@@ -2986,6 +2992,7 @@ export function printHelp() {
   lumine admin sponsor integrity get <case-id> [--json]
   lumine admin sponsor integrity review <case-id> --decision clear|hold|flag|disqualify [--note <evidence>] [--json]
   lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] [--json]
+  lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
   lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
   lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] [--json]
   lumine admin chat-reports show <report-id> [--json]   (reported message snapshot + surrounding context)

package/lib/constants.js

@@ -447,6 +447,7 @@ export const COMMANDS = new Set([
   "sdk",
   "assets",
   "rewards",
+  "cardcraft",
   "chatlog",
   "thumbnail",
   "doctor",

package/lib/rewards.js

@@ -238,7 +238,9 @@ function printRewardsHelp() {
 
 rewards.json (project root) declares the economy the reviewer approves:
   { "userDailyXP", "userDailyCoins", "userDailyClaims"?,
-    "rules": [{ "id", "title", "howTo"? (how to earn it, in the player's words), "xp", "coins", "verifier": "numeric-quiz" | "completion",
+    "rules": [{ "id", "title", "howTo"? (how to earn it, in the player's words), "category"? (section header, up to 40 characters, e.g. "Bring friends"),
+                "series"? (lowercase key for repeat rules like friend-1/2/3; they must share category, verifier and amounts), "xp", "coins", "verifier": "numeric-quiz" | "completion",
                 "maxAttempts"?, "retry"?: { "xpPercent", "coinsPercent", "paidAttempts"? }, "minSeconds"? (completion), "progression"?: "dated" | "until-earned" (quiz) }] }
+The Earn page shows rules under their category headers and each series as one row ("up to 3 a day").
 Questions and answer keys never go in project files; they belong in the sheet.`);
 }

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -2,7 +2,7 @@
 
 Version: 1.60.0
 Updated: 2026-09-27
-Generated: 2026-09-27T07:17:40.033Z
+Generated: 2026-09-27T13:54:27.792Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -33,7 +33,7 @@ Generated: 2026-09-27T07:17:40.033Z
 - Use Twinkle.live for one-way app livestreams and Twinkle.chat for the accompanying thread. Free livestreams require a verified host, end after at most 15 minutes, and issue at most 10 private viewer grants. Twinkle keeps platform-owned live-status/end controls above active hosts, so app code cannot hide or replace the broadcaster's Stop path.
 - Media Energy is separate from AI Energy. Replace Media Energy UI only from canonical mediaEnergy/getUsage responses; never decrement, reserve, or synthesize it in app code.
 - Twinkle.rewards awards real XP and Coins only in the current approved published release. Drafts, local previews, private apps and superseded releases cannot earn. The server supplies a published-runtime grant; app code cannot choose a recipient or award amount.
-- The creator's agent designs the rewards. Declare the economy in a project file `rewards.json` at the root: budgets (userDailyXP, userDailyCoins, optional userDailyClaims; there is no app-wide daily or lifetime budget, only what one learner can earn per day) and rules [{ id, title, xp, coins, verifier: 'numeric-quiz' | 'completion', maxAttempts?, retry?: { xpPercent, coinsPercent, paidAttempts? }, minSeconds? (completion), progression?: 'dated' | 'until-earned' (quiz) }]. Wire the matching Twinkle.rewards calls with those literal rule ids. Questions and answer keys NEVER go in project files (published source is readable by every player): quiz rules get them from the private question sheet uploaded with `lumine rewards sheet <file.json>` ({ rules: { <ruleId>: { questions?, sets? } } }); `lumine rewards check` validates both together. A review request freezes the code and proposes rewards.json merged with the sheet; the administrator reads the code, checks the amounts and whether the app is exploitable, may change any amount, and approves. Creators are kids and teens: show approval status and one Send for review action; do not ask them to fill in technical forms. Every code update that retains rewards needs a new approval before publishing. Removing the SDK automatically clears its gate. Apps read amounts, tries and sets from getStatus, never from their own file.
+- The creator's agent designs the rewards. Declare the economy in a project file `rewards.json` at the root: budgets (userDailyXP, userDailyCoins, optional userDailyClaims; there is no app-wide daily or lifetime budget, only what one learner can earn per day) and rules [{ id, title, howTo?, category? (section header, up to 40 characters), series? (key for repeat rules that share category and amounts), xp, coins, verifier: 'numeric-quiz' | 'completion', maxAttempts?, retry?: { xpPercent, coinsPercent, paidAttempts? }, minSeconds? (completion), progression?: 'dated' | 'until-earned' (quiz) }]. Wire the matching Twinkle.rewards calls with those literal rule ids. Questions and answer keys NEVER go in project files (published source is readable by every player): quiz rules get them from the private question sheet uploaded with `lumine rewards sheet <file.json>` ({ rules: { <ruleId>: { questions?, sets? } } }); `lumine rewards check` validates both together. A review request freezes the code and proposes rewards.json merged with the sheet; the administrator reads the code, checks the amounts and whether the app is exploitable, may change any amount, and approves. Creators are kids and teens: show approval status and one Send for review action; do not ask them to fill in technical forms. Every code update that retains rewards needs a new approval before publishing. Removing the SDK automatically clears its gate. Apps read amounts, tries and sets from getStatus, never from their own file.
 - Verifiers: 'numeric-quiz' pays for server-checked numeric answers (retry share, attempt limits, dated sets or until-earned sets that stay up until somebody earns them, after-answer guides). 'completion' pays when the app reports an activity finished — a cleared stage, a finished round — at least minSeconds after start({ ruleId }); the server checks only the elapsed time, once per learner per site day (UTC midnight), and the budgets. Call start when the activity begins and claim({ challengeId }) with no answers when it ends; keep completion amounts and userDailyXP small enough that a player scripting the calls would not matter, because nothing else is verified.
 - Numeric quiz answers are verified on the server; client scores, privateDb state, timers and completion booleans are not verified reward evidence. Limits reset at UTC midnight. Rules are earned once per viewer per UTC day; attempt limits and retry payouts come from the approved rule. Challenges expire at the UTC day boundary. Budgets apply across release changes.
 - Optional reward rule controls: maxLifetimeClaims caps one learner’s receipts for that rule across every day and release; completionProof: classic-tower-v1 requires a server-simulated Classic Tower finish in addition to minSeconds. These are server-enforced controls. Existing completion rules without completionProof still verify elapsed time only. Registered proof profiles also include breadface-v1, breadface-v2 and breadface-v3 (server-simulated Breadface inputs; each is one reviewed release's exact physics, chosen by the reviewer) study-record-v1 (a private study record reviewed by JEV, billed to the learner’s AI Energy), and Groove Lab's groove-lab-song-v1 (a song the learner published today, checked on the server for length, notes and originality) and groove-lab-heard-v1 (three established accounts finished the learner's songs today), Ashen Vigil's vigil-guest-coplay-v1 (a new guest spent 10 minutes with the learner in a private world room, measured by the world relay; each guest pays once) and minecraft-first-link-v1 (the learner is the first Twinkle account ever linked to that Minecraft player; each player pays once). Profiles are platform-owned; an app cannot invent a verifier or authorize its own reward.
@@ -1335,13 +1335,14 @@ world.updatePresence({ x, y, z, facing });
 
 ### Twinkle.rewards
 - await Twinkle.rewards.getStatus() | scopes: rewards:claim
-  - Returns: { mode: "live", dayKey, userDailyClaims, claimsToday, budgets: { userDailyXP, userDailyCoins }, rules: [{ id, title, howTo?, xp, coins, verifier: "numeric-quiz" | "completion", minSeconds?, progression?, retryReward: { xp, coins }, maxAttempts, available, setKey, questionCount }], challenges: [{ challengeId, ruleId, attempts, attemptsRemaining, state: "open" | "finished" | "earned", setKey, questions: [{ prompt, hint?, guide? }] }], history: [{ ruleId, xp, coins, attempt, createdAt }], balances: { xp, coins } } | { mode: "preview", dayKey?, rules, challenges: [], history: [], balances?, problems?: string[], message }
+  - Returns: { mode: "live", dayKey, userDailyClaims, claimsToday, budgets: { userDailyXP, userDailyCoins }, rules: [{ id, title, howTo?, category?, series?, xp, coins, verifier: "numeric-quiz" | "completion", minSeconds?, progression?, retryReward: { xp, coins }, maxAttempts, available, setKey, questionCount }], challenges: [{ challengeId, ruleId, attempts, attemptsRemaining, state: "open" | "finished" | "earned", setKey, questions: [{ prompt, hint?, guide? }] }], history: [{ ruleId, xp, coins, attempt, createdAt }], balances: { xp, coins } } | { mode: "preview", dayKey?, rules, challenges: [], history: [], balances?, problems?: string[], message }
   - Read canonical earning rules (without answer keys), today’s started challenges, today’s receipts and balances. Drafts return preview mode: for the app's owner the rules come from the draft's own rewards.json and question sheet (problems lists what is still wrong with them); anyone else sees no rules. Unapproved or revoked published releases return an error.
   - rules[].available is false on a site day (UTC) the reviewer scheduled no questions for; show the rule as not available instead of starting it. xp/coins are the first-try amounts; retryReward is what a correct answer pays after a wrong one (equal to xp/coins unless the reviewer set a retry share). maxAttempts null means unlimited wrong answers until the site's daily reset (UTC midnight, 9:00 AM in Korea). retry.paidAttempts, when set, is the last attempt number a correct answer is still paid on: a later correct answer is recorded as solved (receipt xp 0, coins 0) and pays nothing — tell the learner before they pass it.
   - challenges lists challenges this viewer already started today with their questions, so an app can resume after a reload without calling start. A question's guide (reviewer-approved JSON teaching content: explanation, interactive-model configuration) is present only once the viewer has answered at least once, right or wrong; render it as the after-attempt lesson. claimsToday against userDailyClaims (null = uncapped) tells whether another bounty can still pay today.
   - Under progression 'until-earned' the same set stays up day after day until somebody earns it; setKey names the set currently up. Completion rules are always available and have questionCount 0.
   - Rules may set maxLifetimeClaims, a per-learner limit for that rule across days and releases. rules[].lifetime contains the server-confirmed limit and remaining claims. App storage never enforces this limit.
   - howTo is the rule's optional plain-words steps from rewards.json (up to 300 characters, e.g. "Save a new design of at least 64 blocks in Designs"). The Earn page shows it under the title; show it in the app's own rewards list too so players always know exactly what earns each reward.
+  - category and series are optional rewards.json labels for a long list. category is a short section header (up to 40 characters, e.g. "Bring friends"); series is a short lowercase key (e.g. "new-friend") tying repeat rules like vigil-friend-1/2/3 together, and rules in one series must share category, verifier, XP and Coins. The Earn page groups rules by category and shows each series as one row ("up to 3 a day", "1 of 3 today"); group the app's own rewards list the same way.
 - await Twinkle.rewards.getReceipt({ challengeId }) | scopes: rewards:claim
   - Returns: { mode: "live", status: "awarded" | "pending" | "expired" | "not_found", receipt: { id, challengeId, ruleId, reviewId, artifactVersionId, dayKey, xp, coins, attempt, createdAt } | null, balances: { xp, coins } } | { mode: "preview", status: "not_found", receipt: null, message }
   - Read an existing receipt for this app and signed-in viewer by server-issued challengeId, including previous UTC days and previous approved versions. Requires the current approved published release and runtime grant; a stale frame must reload first. Never awards, retries a claim, returns answer keys, or restores removed rewards permission.
@@ -1386,6 +1387,32 @@ world.updatePresence({ x, y, z, facing });
   - Use a receiptId returned by getTimeline. Both reads independently check retirement and app ownership; guessing an active or other app’s receipt cannot reveal its questions or guides. Returns build_reward_archive_unavailable (404) if unavailable.
   - Uses that receipt’s frozen approved sheet, never today’s edited question or the mutable draft. Answer keys and tolerances are never returned. Render the question first and offer Reveal guide for learning, without a reward-claim button.
 
+### 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? }
+  - Live mode (the published app) returns the reviewer-approved recipe, which may differ from the cardcraft.json in the app files until the next approval. In a draft the owner sees their own draft recipe and its problems; anyone else sees no recipe.
+  - cardcraft.json (project root): { guidance?, kinds: [{ id, label, description?, params: { <name>: { type: "enum", values } | { type: "integer" | "number", min, max, scaleWithTier? } | { type: "boolean" } | { type: "string", maxLength } } }], tiers: { "1"…"6": [kindId] } }. Levels are card colours (1 blue, 2 pink, 3 orange, 4 magenta, 5 gold, 6 black); a missing level means cards of that colour cannot be crafted here. scaleWithTier narrows a numeric range to the level's sixth of it (blue = bottom band, black = top band). Validate with `lumine cardcraft check`, send for review with `lumine cardcraft review`.
+- await Twinkle.cardCraft.craft({ cardId, requestId? }) | scopes: cardCraft:craft
+  - Returns: { asset: { assetId, cardId, kind, name, description, params, palette: ["#rrggbb"], tier: { level, colour, quality, effects, rank }, state, stateRevision, craftedAt, stateUpdatedAt, card: { id, word, level, colour, quality, style, imageUrl, creator: { id, username }, crafterId }, app: { buildId } }, duplicate: boolean } | { mode: "preview", asset: { assetId: null, preview: true, … }, duplicate: false }
+  - Twinkle asks the player to confirm first (a card can only ever be crafted once). Omit cardId to let Twinkle show the player a picker of their own cards that can be crafted here, or pick cards yourself with Twinkle.aiCards.list({ userId: viewer.id }); the card must be revealed (have its picture) and its colour must be accepted by the recipe. A player who cancels gets an error with code card_craft_cancelled.
+  - The AI writes the name and description; Twinkle checks that text is fine to show publicly for all ages. Text that is not clearly fine is rewritten once, and if it is still not clearly fine the asset gets a plain name from its colour and species or kind (for example "Gold Fox") and a stock description, with free-text params left empty. The craft itself never fails because of this check.
+  - The card page shows "Crafted into <name> in <app>" for a public app, and only "Crafted into <name>" (no app name or link) while the app is private. Deleting the app frees the card so it can be crafted again; unpublishing does not.
+  - Only the published app crafts for real. In a draft the owner gets a preview asset: the AI runs on the draft recipe, nothing is stored and the card keeps its craft.
+  - Pass the same requestId when retrying after a lost reply to get the same asset back (duplicate: true). Errors carry code: card_already_crafted (details.name, details.appTitle), card_craft_in_progress, card_changed_hands, card_craft_level_not_accepted, card_craft_card_unrevealed, card_craft_generation_failed (the card is unchanged; try again), card_craft_not_approved.
+  - Example: const { asset } = await Twinkle.cardCraft.craft({ cardId });
+spawnPet(asset.kind, asset.params, asset.palette, asset.tier.effects);
+- await Twinkle.cardCraft.list({ cursor?, limit? }) | scopes: cardCraft:read
+  - Returns: { assets: [{ assetId, cardId, kind, name, description, params, palette: ["#rrggbb"], tier: { level, colour, quality, effects, rank }, state, stateRevision, craftedAt, stateUpdatedAt, card: { id, word, level, colour, quality, style, imageUrl, creator: { id, username }, crafterId }, app: { buildId } }], cursor: { assetId } | null }
+  - The viewer's assets in this app: assets whose card they own right now. After a sale the old owner's list no longer has it and the buyer's does. limit 1-50 (default 20).
+- await Twinkle.cardCraft.get({ assetId } | { cardId }) | scopes: cardCraft:read
+  - Returns: { asset: { assetId, cardId, kind, name, description, params, palette: ["#rrggbb"], tier: { level, colour, quality, effects, rank }, state, stateRevision, craftedAt, stateUpdatedAt, card: { id, word, level, colour, quality, style, imageUrl, creator: { id, username }, crafterId }, app: { buildId } } | null }
+  - null when the viewer does not own the card (any more), the card was burned, or it was crafted in another app.
+- await Twinkle.cardCraft.setState({ assetId, state, expectedRevision }) | scopes: cardCraft:write
+  - Returns: { asset }
+  - Saves the asset's own progress (JSON object/array up to 16,000 bytes, or null to clear): level, hunger, nickname, outfit. It travels with the card when it is sold, so keep asset progress here and player progress (coins, room layout) in privateDb.
+  - The asset's name is fixed: it is shown on the card page and cannot be renamed. To let owners name their pet, keep an in-game nickname in state (for example state.nickname, trimmed and length-limited by your app) and show it in the game. After a sale the new owner can set their own nickname the same way.
+  - expectedRevision is the stateRevision you last read; a mismatch fails with code card_craft_state_conflict (details.stateRevision), and a card the viewer no longer owns fails with card_craft_not_owner.
+
 ## Examples
 
 ### Daily reflection feed