@stage5/lumine 0.2.91 → 0.2.94

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/lib/util.js

@@ -47,7 +47,34 @@ export function formatBytes(bytes) {
   const value = Math.max(0, Number(bytes) || 0);
   if (value < 1024) return `${value} B`;
   if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KB`;
-  return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+  if (value < 1024 * 1024 * 1024) {
+    return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+  }
+  return `${(value / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+// Storage sizes for the Lumine file storage unlock: "500MB", "1GB", "1.5gb",
+// or a bare number of MB ("750"). Binary units, matching the server quota.
+export function parseStorageSizeBytes(value) {
+  const raw = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "");
+  const match = raw.match(/^(\d+(?:\.\d+)?)(mb|m|gb|g)?$/);
+  if (!match) {
+    throw new Error(
+      `Pass a storage size like 500MB, 1GB or 2GB (got "${String(value ?? "")}").`,
+    );
+  }
+  const amount = Number(match[1]);
+  const unit = match[2] && match[2].startsWith("g") ? "gb" : "mb";
+  const bytes = Math.round(
+    amount * (unit === "gb" ? 1024 * 1024 * 1024 : 1024 * 1024),
+  );
+  if (!Number.isSafeInteger(bytes) || bytes <= 0) {
+    throw new Error("The storage size must be positive.");
+  }
+  return bytes;
 }
 
 export function isNewerVersion(latestVersion, currentVersion) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.91",
+  "version": "0.2.94",
   "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.60.0
-Updated: 2026-09-27
-Generated: 2026-09-27T07:17:40.033Z
+Version: 1.61.0
+Updated: 2026-09-28
+Generated: 2026-09-27T17:21:08.257Z
 
 ## 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.
@@ -137,7 +137,9 @@ files:read, media:read, media:write, live:read, live:write, user:read, users:rea
   - Returns: { success, session } when opened by lumine app-mcp
   - Register the live iframe handlers for the published app's static MCP tool manifest.
   - Tool discovery comes only from /app-tools.json in the pinned published artifact; runtime code cannot add or rename tools.
-  - Every declared tool needs a same-named handler. Outside an app-mcp session, registration stores the handlers and resolves with active:false without starting a relay.
+  - Every declared tool needs a same-named handler. Outside an app-mcp session, registration stores the handlers, tells Twinkle the app offers tools (so the signed-in viewer can click Connect AI helper and pair this open tab with lumine app-mcp <buildId> --code <code>), and resolves with active:false.
+  - Mark each tool that only reads with "readOnly": true in /app-tools.json; for a tool whose action argument decides, declare "readOnlyWhen": { "action": ["list", "export"] }. A helper paired through Connect AI helper can use only read-only calls until the viewer switches on Allow edits; undeclared tools count as edits.
+  - Include what the viewer has selected or is looking at in the state-reading tool (for example the selected range and active item), so a paired helper can see what the viewer is pointing at.
   - Handlers run serially inside the visible app iframe and should return the confirmed post-action state.
   - Do not synthesize server-owned state; await Twinkle SDK mutations before returning.
   - Example: await Twinkle.appTools.register({ handlers: { get_state: () => ({ view, data }), open_view: ({ view }) => navigateTo(view) } });
@@ -1335,13 +1337,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 +1389,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

package/sdk/LUMINE_ADMIN.md

@@ -1083,6 +1083,34 @@ mutation when a caller needs the same retry identity across processes. The CLI
 generates a fresh key for every mutation invocation; if a mutation fails, its
 JSON error includes `details.retryIdempotencyKey` for a safe exact retry.
 
+### Build review requests: one queue for every unlock (any time; added 2026-09-28)
+
+Everything a creator asks Mikey to unlock is one review request with a type:
+`rewards` (XP & Coin rewards, below), `project-limit` (more project room),
+`storage-limit` (more Lumine file storage, per creator) and `cardcraft` (an AI
+Card crafting recipe). Mikey sees them in one list (Management → **Build
+approvals**, or the CLI below), gets the same DM card for each, and decides
+them the same way. Each type keeps its own rules: reward approvals carry the
+earning rules and publish the frozen version; storage approvals take a size
+(500 MB / 1 GB / 2 GB tiers, any size up to the 2 GB cap, never lowering an
+existing approval); project room approvals raise Main to the fixed bounds;
+card crafting approvals make the recipe live in the published app without a
+new release. Only rewards and card crafting approvals can be revoked. The
+older per-type commands (`reward-review`, `cardcraft-review`, `storage
+approve|reject|list`) are aliases of these routes and keep working.
+
+```bash
+lumine admin review list --json                       # waiting on a decision (default)
+lumine admin review list --status queue --type storage,project --json
+lumine admin review show storage:12 --json             # <type>:<id>, or <id> --type storage
+lumine admin review approve storage:12 --size 1GB --json
+lumine admin review reject project:4 --reason "Split the big file first" --json
+lumine admin review approve cardcraft:3 --json
+lumine admin review revoke cardcraft:3 --reason "Too strong for level 1 cards" --json
+lumine admin review approve rewards:70 --config rules.json --json
+lumine admin review propose rewards:70 --dir /private/tmp/reward-review-70 --config rules.json --json
+```
+
 ### Build XP/Coin reward approvals (any time; also a full-daily-review duty)
 
 The creator's Lumine designs the rewards and writes them into the app. The