@stage5/lumine 0.3.31 → 0.3.33

package/lib/commands.js

@@ -2478,7 +2478,14 @@ export function parseArgs(args) {
     "show",
     "foreground",
     "open",
+    "dryRun",
+    "confirmEmailRule",
+    "includePrefix",
+    "allowSharedNetwork",
   ]);
+  // A flag that may stand alone (true) or carry a value: `--confirm` confirms
+  // an AI bucket change; `meetup slot <crewId> --confirm <slotIndex>` picks a slot.
+  const optionalValueFlags = new Set(["confirm"]);
 
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
@@ -2499,6 +2506,12 @@ export function parseArgs(args) {
           : inlineValue;
     } else if (booleanFlags.has(camelKey)) {
       raw[camelKey] = true;
+    } else if (
+      optionalValueFlags.has(camelKey) &&
+      // a following flag (`--json`, `-h`) is never taken as the value
+      (rest[i + 1] === undefined || rest[i + 1].startsWith("-"))
+    ) {
+      raw[camelKey] = true;
     } else {
       const nextValue = rest[i + 1];
       if (
@@ -2732,6 +2745,13 @@ export function parseArgs(args) {
         : "",
     adminBucketId: raw.bucketId ? String(raw.bucketId) : "",
     adminDeviceKey: raw.deviceKey ? String(raw.deviceKey) : "",
+    adminRuleId: raw.ruleId ? String(raw.ruleId) : "",
+    adminIp: raw.ip ? String(raw.ip) : "",
+    adminMessage: raw.message === undefined ? undefined : String(raw.message),
+    adminDryRun: Boolean(raw.dryRun),
+    adminConfirmEmailRule: Boolean(raw.confirmEmailRule),
+    adminIncludePrefix: Boolean(raw.includePrefix),
+    adminAllowSharedNetwork: Boolean(raw.allowSharedNetwork),
     adminLabel: raw.label ? String(raw.label) : "",
     adminUserIds: raw.userIds ? String(raw.userIds) : "",
     adminUser: raw.user ? String(raw.user) : "",
@@ -2782,10 +2802,20 @@ export function parseArgs(args) {
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
     adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
     adminFile: raw.file ? String(raw.file) : "",
+    // admin craft revise --item <id|name> [--why] [--emoji] [--category]
+    // (kept raw: a flag given without a text value is refused in
+    // admin-craft.js rather than sent as the string "true")
+    adminCraftItem: raw.item,
+    adminCraftWhy: raw.why,
+    adminCraftEmoji: raw.emoji,
+    adminCraftCategory: raw.category,
+    adminCraftPair: raw.pair,
     adminPort: raw.port ? String(raw.port) : "",
     adminForeground: Boolean(raw.foreground),
     adminOpen: Boolean(raw.open),
     adminConfigFile: raw.config ? String(raw.config) : "",
+    // admin review propose --thumbnail <image|workspace>
+    adminThumbnail: raw.thumbnail ? String(raw.thumbnail) : "",
     adminReviewedBuildVersion: raw.reviewedVersion
       ? String(raw.reviewedVersion)
       : "",
@@ -3177,6 +3207,15 @@ export function printHelp() {
   lumine admin ai-bucket accounts add --bucket-id <id> --user-ids <id,id,...> [--note <text>] [--json]
   lumine admin ai-bucket device block-signup --bucket-id <id> --user <source-user-id> --device-key <inspection-key> --user-ids <reviewed-device-users> --note <reason> [--json]
   lumine admin ai-bucket note set --bucket-id <id> --note <text> [--json]
+  lumine admin ai-bucket inspect --bucket-id <id> --reason <management reason> [--include-private-evidence] [--json]
+  lumine admin ai-bucket restrict --bucket-id <id> --mode none|signup|full [--message <text>] [--allow-shared-network] (--dry-run | --confirm) [--json]
+  lumine admin ai-bucket rule add --bucket-id <id> --type user --user <id> [--note <text>] (--dry-run | --confirm) [--json]
+  lumine admin ai-bucket rule add --bucket-id <id> --type email --email <address> [--note <text>] (--dry-run | --confirm-email-rule --confirm) [--json]
+  lumine admin ai-bucket rule add --bucket-id <id> --type ip --ip <address> --scope signup|full [--include-prefix] [--allow-shared-network] [--note <text>] (--dry-run | --confirm) [--json]
+  lumine admin ai-bucket rule add --bucket-id <id> --type device --user <source-user-id> --device-key <inspect-key> --scope signup|full --user-ids <reviewed-device-users> --note <reason> (--dry-run | --confirm) [--json]
+  lumine admin ai-bucket rule disable --bucket-id <id> --rule-id <id> [--note <text>] (--dry-run | --confirm) [--json]
+      (every real change needs --confirm; --dry-run shows exactly what would change and writes nothing;
+       a shared network (academy, school) or an unmeasured prefix is refused unless --allow-shared-network, only on Mikey's explicit word)
   lumine admin ai-email-policy get --email <address> [--json]
   lumine admin ai-email-policy set --email <address> --mode <automatic|separate_accounts> --note <text> [--json]
   lumine admin daily-run start [--scope full|featured|newspaper] [--identity zero|ciel|auto] [--comment-mode off|draft|post] [--run-key <key>] [--json]
@@ -3202,6 +3241,7 @@ export function printHelp() {
   lumine admin english import <verdicts.json> --pass a|b | adjudicate <file> | add-questions <file> | relevel <file> | mastery <userId> --reason <why> | backfill-distractors | summary | review [--limit <n>] | accept|retire <questionId> | retag <questionId> --skill <code>   (English skill tags and bank upkeep for Grammarbles; content written by Claude Code agents)
   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 craft seed --build <id> --file <pairs.json> [--confirm] | stats --build <id> [--limit <1-100>] | revise --build <id> --item <id|name> [--why <text>] [--emoji <emoji>] [--category <field>] [--confirm] | retire --build <id> --item <id|name> --reason <text> [--confirm] | unfizzle --build <id> [--since <iso>] [--pair <a+b>] [--confirm]   (Twinkle.craft curation: 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] | approve-crew <crewId> | approve-grownup <crewId> | request-changes <crewId> --note <text> | emails [list|send <id>|discard <id>|review on|off] | friends [status|on|off] | parent-reply <crewId> <memberUserId> --note <text> | funnel [--days <1-90>] | branches [list [--status pending|official|rejected|all] | show <id> | approve <id> | reject <id> [--note <text>] | merge <id> --into <officialId>] | show <crewId> | approve-plan <crewId> [--note <text>] | send-back <crewId> --note <text> | approve <crewId> --attended <userId,userId,...> [--note <text>] | info <crewId> <userId> --decision ask|accept|ask-again|withdraw [--note <text>] | set-branch <crewId> <userId> --branch "<name>" [--note <text>] | slot <crewId> --confirm <slotIndex> | resend-email <crewId>   (Bridge Builder meetup quest)
   lumine admin meetup story list | show <crewId> | approve <crewId> [--note <text>] [--no-announce] | send-back <crewId> --note <text> | unpublish <crewId> --note <text>   (Bridge Builder story pages: publishes only what every tagged member's parent allowed)
@@ -3216,7 +3256,7 @@ export function printHelp() {
   lumine admin chat-reports suspend --user <id> --note <why> [--json]   (full ban: signs them out)
   lumine admin reward-review show <review-id> [--dir <path>] [--json]
   lumine admin reward-review approve <review-id> [--config <rules.json>] [--reason <text>] [--json]   (approval publishes the approved version)
-  lumine admin reward-review propose <review-id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--json]
+  lumine admin reward-review propose <review-id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--title <new app name>] [--thumbnail <image|workspace>] [--json]
   lumine admin reward-review reject|revoke <review-id> --reason <text> [--json]
   lumine admin recommendations list [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin builds candidates [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--limit <number>] [--json]

package/lib/thumbnail.js

@@ -134,6 +134,27 @@ export async function thumbnailSet(options) {
   if (!filePath) {
     throw new Error("Usage: lumine thumbnail set <file> (jpg, png, or webp)");
   }
+  const { buffer, contentType } = await readThumbnailFile(filePath);
+
+  const { buildId, auth, build } = await resolveThumbnailContext(options);
+  const proceed = await confirmThumbnailOverwrite({ options, build, buildId });
+  if (!proceed) return;
+
+  const { thumbnailUrl } = await commitThumbnailImage({
+    options,
+    auth,
+    buildId,
+    buffer,
+    contentType,
+  });
+  console.log(`Thumbnail set for Build #${buildId}:`);
+  console.log(`  ${thumbnailUrl}`);
+  console.log("Tip: thumbnails display ~16:9; the image was uploaded uncropped.");
+}
+
+// A local jpg/png/webp checked against the thumbnail limits, ready for
+// commitThumbnailImage (also used by `lumine admin review propose --thumbnail`).
+export async function readThumbnailFile(filePath) {
   const absolutePath = path.resolve(filePath);
   const extension = path.extname(absolutePath).toLowerCase();
   const contentType = THUMBNAIL_CONTENT_TYPE_BY_EXTENSION[extension];
@@ -159,21 +180,7 @@ export async function thumbnailSet(options) {
       `Thumbnail file is too big (${formatBytes(buffer.length)}; max ${formatBytes(THUMBNAIL_MAX_FILE_SIZE_BYTES)}).`,
     );
   }
-
-  const { buildId, auth, build } = await resolveThumbnailContext(options);
-  const proceed = await confirmThumbnailOverwrite({ options, build, buildId });
-  if (!proceed) return;
-
-  const { thumbnailUrl } = await commitThumbnailImage({
-    options,
-    auth,
-    buildId,
-    buffer,
-    contentType,
-  });
-  console.log(`Thumbnail set for Build #${buildId}:`);
-  console.log(`  ${thumbnailUrl}`);
-  console.log("Tip: thumbnails display ~16:9; the image was uploaded uncropped.");
+  return { buffer, contentType };
 }
 
 function decodeImageDataUrl(dataUrl) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.31",
+  "version": "0.3.33",
   "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.64.3
-Updated: 2026-10-10
-Generated: 2026-10-10T06:47:00.045Z
+Version: 1.65.1
+Updated: 2026-10-13
+Generated: 2026-10-12T17:14:00.482Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -36,7 +36,7 @@ Generated: 2026-10-10T06:47:00.045Z
 - 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; an award larger than the learner's remaining room today pays what fits, XP and Coins clamped separately; a capped award still counts as claimed, including a one-time maxLifetimeClaims reward, and its receipt carries cappedFrom) 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' | 'generated-quiz', 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 }] } }]. generated-quiz rules need no question sheet. 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. 'generated-quiz' pays from a question bank the server fills itself: for one declared topic at the learner's step of the ladder, the server writes a question with GPT-6.1 Sol (billed to that learner's AI Energy), solves it again independently and keeps it only when both answers agree; every learner who has not seen a question gets it before anything new is written. `xp`/`coins` are the top step's amounts and each step pays its `steps` percent of them (then the usual retry share). Two first-try answers in a row climb a step; two misses in a row step down. Learners may earn many bank questions a day, bounded by userDailyXP/userDailyCoins. The reviewer approves the ladder, amounts, topics and instructions, not each question; learner reports and solve rates hide bad questions. Use the rewards bank methods (getBankStatus, startBankQuestion, generateBankQuestion, claimBankQuestion, reportBankQuestion); start and claim refuse bank rules. 'archive-rematch' is the daily rematch: one retired until-earned puzzle of the app a day, chosen by the server (celebrated, high-rated solves first; never repeated within 60 days) and answered from its frozen approved sheet. Declare at most one, with no questions, sets, progression, series, minSeconds or completionProof, e.g. { "id": "rematch-daily", "title": "Daily rematch", "xp": 20000, "coins": 1000, "verifier": "archive-rematch", "retry": { "xpPercent": 50, "coinsPercent": 0, "paidAttempts": 3 }, "maxAttempts": null }. Only players who never met that puzzle (no official receipt, wrong answer or challenge while it was live, no Vault practice) may answer it; its receipt does not use userDailyClaims but counts toward userDailyXP/userDailyCoins. Use getRematch and claimRematch; start and claim refuse it.
 - 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 (a receipt capped by the daily budget still counts, so a one-time reward claimed near the cap pays only what fits); 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), groove-lab-listen-v1 (the learner listened to most of someone else's published song: start binds the song, the server clock covers three quarters of it up to two minutes, and the listener's own groove-lab-listens row for it was written today; each song pays a listener once a day across listening rules) and groove-lab-own-listen-v1 (the same for the learner's own song; own listens never count toward groove-lab-heard-v1), 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), and writing-words-v1 with minWords (counted words the learner wrote today as chapters in their own books registered in the app's shared books topic; each chapter is read once by a small model for genuine writing and language, English words count fully and other languages half, and the same text counts once), reading-quiz-v1 (the learner passed a server-graded three-question quiz on a chapter of someone else's registered book after its reading time; each chapter pays a reader once, one attempt per chapter per day) and reading-readers-v1 with minReaders (that many established accounts passed a quiz on the learner's chapters today). Profiles are platform-owned; an app cannot invent a verifier or authorize its own reward.
+- Optional reward rule controls: maxLifetimeClaims caps one learner’s receipts for that rule across every day and release (a receipt capped by the daily budget still counts, so a one-time reward claimed near the cap pays only what fits); 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), groove-lab-listen-v1 (the learner listened to most of someone else's published song: start binds the song, the server clock covers three quarters of it up to two minutes, and the listener's own groove-lab-listens row for it was written today; each song pays a listener once a day across listening rules) and groove-lab-own-listen-v1 (the same for the learner's own song; own listens never count toward groove-lab-heard-v1), 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), and writing-words-v1 with minWords (counted words the learner wrote today as chapters in their own books registered in the app's shared books topic; each chapter is read once by a small model for genuine writing and language, English words count fully and other languages half, and the same text counts once), reading-quiz-v1 (the learner passed a server-graded three-question quiz on a chapter of someone else's registered book after its reading time; each chapter pays a reader once, one attempt per chapter per day) and reading-readers-v1 with minReaders (that many established accounts passed a quiz on the learner's chapters today). Twinkle.craft apps also have craft-target-v1 (the learner's run of merges reaches today's target in this app's universe; every merge is a known pair and every result is one the learner made through Twinkle.craft.merge), craft-par-v1 (the same run reaches it in at most par merges) and craft-discovery-v1 (the oldest World First of the learner's that no rule has paid yet; each World First pays once ever; optional minWordLevel basic|elementary|intermediate|advanced|epic makes tiers: either every craft-discovery-v1 rule has one or none does; each World First pays under exactly one tier, the highest configured tier at or below its Word Master level, so a series per tier can pay rarer words more and the order of claims never matters; an item whose level is still pending pays under no tier yet). Profiles are platform-owned; an app cannot invent a verifier or authorize its own reward.
 
 ## 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.
@@ -1517,6 +1517,7 @@ world.updatePresence({ x, y, z, facing });
   - Completion rules take no answers: claim({ challengeId }) when the activity is finished. build_reward_too_fast (HTTP 409) means fewer than minSeconds passed since start; show nothing and let play continue. In preview mode the receipt carries preview: true and nothing is paid.
   - A completionProof rule also requires the signed completionToken from a successful rewards.progress response. The server simulates the registered game physics and must reach the goal. A timer, forged position, client win flag, altered inventory or token from another viewer, challenge or release cannot authorize payment. maxLifetimeClaims is enforced from receipts in the same award transaction; every receipt counts, including one capped by the daily budget (cappedFrom). build_reward_lifetime_claims_reached means all rewards for this rule have been collected; do not retry it.
   - For study-record-v1, the server verifies the settled private review row and its viewer, app, exact release, challenge and day binding. It never trusts the client’s decision, requested award amount or AI answer. Each successful daily study record is claimable once; display only canonical receipt/balances. For groove-lab-song-v1, pass completionToken as the published song's sharedDb entry id; for groove-lab-heard-v1, pass none; for vigil-guest-coplay-v1, pass the guest's world guestId (from world events) or the co-play record id; for minecraft-first-link-v1, pass nothing or the Minecraft UUID to use; for reading-quiz-v1, pass completionToken as the chapter commentId and answers as the three chosen option indexes (all three must be right; a wrong attempt cannot be retried that day); for groove-lab-listen-v1 and groove-lab-own-listen-v1, pass the same song entry id after listenSeconds of foreground playback; for reading-readers-v1, pass nothing; for writing-words-v1, pass nothing (the server counts today's chapters itself and refuses with a plain reason, e.g. "320 of 500 counted words today" or "still being checked"). The server reads the app's own groove-lab-songs, groove-lab-song-parts and groove-lab-listens rows and refuses with build_reward_completion_proof_required and a plain reason when the song or listeners do not qualify.
+  - For craft-target-v1 and craft-par-v1, pass completionToken as JSON.stringify({ v: 1, merges: [[a, b], ...] }): the item ids of the run's successful merges in order, starting from the starters (at most 300 merges, 32 KB). The server replays it against this app's known pairs, needs today's target (Twinkle.craft.getState().today) to appear, every result to be in the learner's collection, and at least one second per merge since start; it refuses an unknown pair, an item the run had not made yet, an over-par run (par rule) or a run on another day. For craft-discovery-v1, pass nothing: the server pays the oldest unpaid World First (receipt slot craft:<itemId>) and puts its name on the bounty story ("discovered <item>"). With tiers, a rule pays only World Firsts of its own tier (refused with a plain reason when the learner has none).
 - await Twinkle.rewards.getLeaderboard({ metric?: "xp" | "coins", period?: "day" | "week" | "all", limit? }) | scopes: rewards:claim
   - Returns: { mode: "live", metric, period, limit, dayKey, from, available: { xp, coins }, entries: [{ rank, userId, username, profilePicUrl, xp, coins, claims, lastAt }], me: { rank, xp, coins, claims } | null } | { mode: "preview", metric, period, available, entries: [], me: null, message }
   - Standings of who earned the most XP or Coins in THIS app, computed by Twinkle from its own receipts (never from anything the app submits). period 'day' is today (site day, UTC), 'week' the last 7 site days, 'all' (default) every day since approval. limit defaults to 20, max 100.
@@ -1652,6 +1653,36 @@ spawnPet(asset.kind, asset.params, asset.palette, asset.tier.effects);
   - 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.
 
+### Twinkle.craft
+- await Twinkle.craft.getState() | scopes: craft:read
+  - Returns: { starters: [item], counts: { mine, world }, today: { day, target: item | null, par: number | null, done: boolean }, reason?: "sign_in_required" }
+  - item is { id, name, emoji, category, wordLevel: "basic" | "elementary" | "intermediate" | "advanced" | "epic" | null, isStarter }. wordLevel is Word Master's level of the name's rarest word (null while it is being looked up); show it by name, never as a number.
+  - Starters are always in the player's hands and are not in list(). counts.mine is the player's collection without starters; counts.world is every item in this universe.
+  - today is Today's Star: the same target for everyone in this app on this site day (UTC), reachable from the starters in par merges or fewer (par is the server's best plan, an upper bound). target is null while the universe is too young. done is true once the player has the target.
+  - Signed-out viewers get the same shape, empty: starters [], counts 0, today with target null, plus reason: "sign_in_required". counts.world may be up to a minute old.
+- await Twinkle.craft.merge({ a, b, requestId? }) | scopes: craft:write
+  - Returns: { status: "ok" | "fizzle", item: item | null, why: string | null, newForMe: boolean, worldFirst: boolean, newPair: boolean, aiUsagePolicy? }
+  - a and b are item ids the player has (starters or their collection); the order does not matter and an item can merge with itself. A known pair answers at once and costs nothing. A new pair asks the AI (usually a few seconds; the SDK waits up to 120 s), costs the player a little AI Energy (newPair: true) and is then known for everyone. fizzle means the pair makes nothing; it is stored too, so it is also free afterwards.
+  - why is one true sentence explaining the result ("Lava cools in water and hardens into rock."): show it, it is the learning part. worldFirst: true means this player is the first in this universe to make the item; their name is on it for good.
+  - Limits: 300 new pairs per player per day (known pairs are unlimited), 20,000 items per collection, and about 1 merge a second. Errors carry code: craft_item_not_owned, craft_item_not_found, craft_in_progress (someone else is discovering the same pair; retry shortly), craft_daily_limit, craft_collection_full, craft_universe_full, craft_generation_failed / craft_generation_timeout (the AI was unavailable or too slow and the pair stays new; try again), craft_check_unavailable (HTTP 503: Twinkle's safety check is briefly down; nothing was stored and the pair stays new, so try again in a minute), craft_app_not_found / craft_forbidden (the app was deleted or the viewer can no longer open it), craft_throttled, and the AI Energy codes of Twinkle.ai.
+  - Pass the same requestId when retrying after a lost reply. Keep a run's successful merges as [a, b] ids for Twinkle.rewards.claim (craft-target-v1 / craft-par-v1).
+  - A result that is a starter (Water + Water = Water) is not added to the collection: newForMe is false. An error can carry aiUsagePolicy when an earlier AI attempt already used Energy.
+  - Items can be taken down by Twinkle moderators: a retired item leaves the player's collection (list, item, getState counts) and its pairs answer fizzle. Treat ids you cached as possibly gone: a merge with one returns craft_item_not_found.
+  - Example: const result = await Twinkle.craft.merge({ a: water.id, b: fire.id });
+if (result.status === 'ok') showCard(result.item, result.why, result.worldFirst);
+- await Twinkle.craft.list({ cursor?, limit? }) | scopes: craft:read
+  - Returns: { items: [{ id, name, emoji, category, wordLevel, firstAt, isWorldFirst }], cursor: number | null }
+  - The player's collection in this app, oldest item id first; limit 1-200 (default 100). firstAt is when this player got the item; isWorldFirst is true for items they discovered first in the universe.
+- await Twinkle.craft.item({ id }) | scopes: craft:read
+  - Returns: { item: { id, name, emoji, category, wordLevel, isStarter, why, firstDiscoverer: { id, username } | null, firstAt, holders, recipes: [[{ id, name, emoji }, { id, name, emoji }]] } | null }
+  - The discovery card of an item the player has (null otherwise, so undiscovered items never leak). why is the explanation from the merge that first made it, holders how many players have it, recipes up to five known pairs that make it whose inputs the player has.
+- await Twinkle.craft.journey({ day? }) | scopes: craft:read
+  - Returns: { day, journey: { target: item, par, steps: [{ a, b, result }] } | null, reason?: "no_target" | "reach_target_first" | "sign_in_required" }
+  - The server's par plan for a day (YYYY-MM-DD, default today), each step { id, name, emoji } items. For today it opens only after the player made the target today (reason reach_target_first before that); past days are open too, except a past day whose target is today's target (same rule as today).
+- await Twinkle.craft.rankings() | scopes: craft:read
+  - Returns: { allTime: { top: [{ rank, userId, username, profilePicUrl, worldFirsts }], me: { rank: number | null, worldFirsts } }, month: { month, top, me: { rank: number | null, worldFirsts } } }
+  - World First rankings in this app: the top 30 discoverers all time and this month (UTC), and the viewer's own rank (null with no World Firsts). The top lists may be up to a minute old. Signed-out viewers get empty top lists and me: { rank: null, worldFirsts: 0 }.
+
 ### Twinkle.network
 - async getHome({}) | scopes: sharedDb:read
   - Returns: { name, buildId, url, communities, counts }

package/sdk/LUMINE_ADMIN.md

@@ -131,7 +131,8 @@ canonical bucket. Use it to distinguish quota bookkeeping from moderation;
 the note itself changes no access, ban, or identity rules.
 
 The commands above are quota bookkeeping only. They cannot ban accounts, block signup,
-add IP/device/risk-key rules, or infer an account family. Identification
+add IP/device/risk-key rules, or infer an account family (the explicit
+restricted-bucket commands below can, on Mikey's instruction). Identification
 remains a human/LLM evidence judgment and must be explicitly requested by
 Mikey; routine administrator runs still escalate suspected alternate accounts
 and never auto-enforce. `accounts add` and `note set` still accept only an
@@ -159,6 +160,85 @@ raw device ID. The private audit records the request before evidence is read
 and records successful completion separately. Routine reviews still never
 auto-enforce; this action requires Mikey's explicit instruction for the device.
 
+### Restricted buckets: inspect, rules and restrictions
+
+These are the operator path for buckets with a restriction (and for adding
+email, IP and device rules to any bucket). They use the same shared operations
+as the Management page, so each change has the same side effects there
+(current-day usage re-attribution, ban cache, member notification and kicks,
+live quota updates). Use them only on Mikey's explicit instruction for that
+bucket, rule or restriction.
+
+```bash
+lumine admin ai-bucket inspect --bucket-id 4 --reason "todo 79 review" --json
+lumine admin ai-bucket restrict --bucket-id 4 --mode signup --dry-run
+lumine admin ai-bucket restrict --bucket-id 4 --mode signup --confirm
+lumine admin ai-bucket rule add --bucket-id 4 --type user --user 18559 --dry-run
+lumine admin ai-bucket rule add --bucket-id 4 --type user --user 18559 --confirm
+lumine admin ai-bucket rule add --bucket-id 4 --type email \
+  --email family@example.com --confirm-email-rule --confirm
+lumine admin ai-bucket rule add --bucket-id 4 --type ip --ip 58.151.12.59 \
+  --scope signup [--include-prefix] --confirm
+lumine admin ai-bucket rule add --bucket-id 4 --type device --user 18559 \
+  --device-key 0123456789abcdef --scope signup --user-ids 18559,20001 \
+  --note "Mikey approved this reviewed device" --confirm
+lumine admin ai-bucket rule disable --bucket-id 4 --rule-id 77 --dry-run
+```
+
+`inspect` works for unrestricted and restricted buckets. It returns the
+canonical bucket (label, note, restriction `none|signup|full`, message), every
+active rule (id, kind, scope, effective restriction, match), the canonical
+members, every account a full restriction would reach, and for each member
+(first 25) their devices (inspection keys, never raw IDs) and network
+addresses with how many accounts share each. A device or address used by many
+accounts (an academy, a school) is counted, marked shared and never listed or
+treated as family evidence. Addresses and email-rule addresses (in evidence, rules and rule notes)
+are masked unless `--include-private-evidence`; every other output, and the
+audit, keeps them masked (with a keyed hash in the audit). `--reason` is required; the API commits an
+access receipt before reading evidence.
+
+`--dry-run` on `restrict`, `rule add` and `rule disable` is a read: it returns
+the current and resulting restriction, the accounts newly affected or released,
+the accounts whose sessions a full restriction drops, admin conflicts and any
+blocker, and changes nothing. Device, IP and email previews read private
+evidence, so they record an access receipt; the others record nothing.
+
+A real run is audited (request receipt with the idempotency key and payload
+fingerprint, then the completed result) and returns the bucket read back from
+the database and checked (`verified: true`); the CLI refuses a result that
+does not confirm the requested state. A failure after the change started is
+recorded as failed; a replay with the same idempotency key returns the stored
+result instead of running again.
+
+- `restrict` always needs `--confirm`. `signup` blocks only new accounts:
+  existing logins and existing bans (`users.banned`) stay as they are. `full`
+  drops members' sessions and is refused while any member is an admin. `none`
+  lifts the restriction; each member gets its effective ban state pushed again.
+  Without `--message` the current message is kept. The preview and the
+  result list every IP, prefix and device rule whose effective restriction
+  changes, with how many accounts it reaches (exact IPs from site activity;
+  prefixes and devices from a year of AI usage, a lower bound). A rule that
+  gets stronger on a shared network (more than 8 accounts) or whose reach
+  can't be measured refuses the change unless `--allow-shared-network` is
+  passed; use it only on Mikey's explicit word. The CLI prints the override.
+  Saving a full bucket again (even only a new message) re-kicks its members,
+  as on the Management page; the preview lists them.
+- `rule add` / `rule disable` always need `--confirm` too: on an unrestricted
+  bucket a rule still pools AI Energy, on a restricted one it changes who is
+  blocked. On a fully restricted bucket an account or email rule re-kicks every
+  account the bucket reaches (as on the Management page); the preview lists them.
+  Email rules cover every account with that verified address and also need
+  `--confirm-email-rule`. IP and device rules need `--scope`; IP prefix rules
+  (`--include-prefix`, the whole /24 or /64) are opt-in, their reach measured
+  as above. A shared exact address or prefix, or an unmeasured prefix under a
+  full restriction, is refused unless `--allow-shared-network`. An address or
+  prefix rule held by another bucket is refused, never moved. Device rules
+  keep the `device block-signup` guards: the reviewed `--user-ids` must equal
+  the accounts seen on the device, all inside the bucket; a device more than
+  9 accounts used is shared (counted, not listed, refused). Disabling an exact
+  IP rule leaves its prefix rules active (the preview names them).
+  `rule disable` keeps `--note` in the audit receipt only.
+
 ### Shared verified-email policies
 
 A verified address proves that an account can use that mailbox; it does not
@@ -1320,10 +1400,19 @@ lumine admin reward-review approve 2 --config rules.json \
 lumine admin reward-review show 2 --dir /private/tmp/reward-review-2 --json   # then edit that directory…
 lumine admin reward-review propose 2 --dir /private/tmp/reward-review-2 \
   --config rules.json --reason "Moved the claim after the stage clears" --json  # …and offer it
+lumine admin reward-review propose 2 --dir /private/tmp/reward-review-2 --config rules.json \
+  --title "Word Forge" --thumbnail cover.png --json         # …also offering a new name and thumbnail
 lumine admin reward-review reject 2 --reason "Rewards fire on game over; nothing is earned" --json
 lumine admin reward-review revoke 2 --reason "Farmable; pausing until redesigned" --json
 ```
 
+A proposal can also offer the app a new name (`--title`, at most 100
+characters) and a new thumbnail (`--thumbnail <jpg|png|webp>`, uploaded to your
+proposal workspace copy first; `--thumbnail workspace` offers the one already
+set on that copy, e.g. from the website). Both are frozen with the offer and
+applied together with the files and rules when the creator accepts. An offer
+may change only the name or thumbnail; the files can then stay as submitted.
+
 `show --dir` writes the exact reviewed snapshot (private files, including the
 app's own `rewards.json`) so the agent can read it like a pulled workspace. The
 result's `config` is the proposal: the declared economy with the sheet's
@@ -1503,6 +1592,99 @@ lumine admin roles --min-level 3       # only the admin types' holders
 lumine admin roles --min-level 0 --limit 200 --json
 ```
 
+### Twinkle.craft universes: seed, audit, revise (any time; added 2026-10-12)
+
+An app using `Twinkle.craft` (Infinity Craft, build 1499) has its own
+universe of items and pairs. Players' new pairs are answered by the AI on
+their own Energy; we seed and curate the rest with Claude Code agents, not
+API calls (Mikey 10-12): an initial seed, then expansion and a daily audit,
+Math Lab style. No daily run is needed. `seed` and `revise` are dry runs
+unless `--confirm` is given.
+
+```bash
+lumine admin craft stats --build 1499 [--limit 50]       # sizes, frontier, today's star, newest AI answers, kept flagged names
+lumine admin craft seed --build 1499 --file pairs.json   # ALWAYS first: what would be added, skipped, rejected, warned
+lumine admin craft seed --build 1499 --file pairs.json --confirm   # only after reading every warning
+lumine admin craft revise --build 1499 --item Obsidian --why "Lava that cools very fast turns into glassy rock." --confirm
+```
+
+- `pairs.json` is up to 500 pairs, in order: `[{ "a": "Water", "b": "Fire",
+  "result": { "name": "Steam", "emoji": "♨️", "category": "science", "why":
+  "Fire heats water until it turns into vapour." } }]` (or `{ "pairs": [...] }`).
+  `a` and `b` are item names: starters (Water, Fire, Earth, Wind, Tree,
+  Nature), items already in the universe, or results earlier in the same file.
+- Every result passes the same checks as AI answers: 1-3 English words of
+  letters (32 characters), exactly one emoji, a category from nature, weather,
+  earth, space, life, body, science, energy, materials, food, tools, places,
+  ideas, and one plain-text why of at most 140 characters (no links or
+  markup). No AI or JEV call runs, so the content is ours to get right: real,
+  common English nouns or ideas, no people, characters or brands, child-safe,
+  and a true why that teaches the link.
+- **Always dry-run a seed first and read every warning before `--confirm`.**
+  A warning means a word of the name is on Word Master's censored list; the
+  pair is still written on `--confirm`, so drop or rename any pair whose name
+  could read rudely before confirming.
+- A pair that already has an answer is skipped, never overwritten. Each
+  chunk of 100 is one audited transaction (`craft.seed`); a re-run is safe.
+  Word levels (Word Master's basic..epic) are looked up as for player items.
+- Seeded items have no World First: the first player to make one claims it
+  (name on the item, rankings, the discovery reward). Seeded pairs count for
+  Today's Star like any answered pair and never count toward the admin's
+  daily new-pair limit.
+- `stats` lists the newest AI-made pairs (`source: ai`, newest first, `--limit`
+  1-100, default 20) with each result's name, emoji, category, word level and
+  why. Audit them daily; fix a wrong or weak explanation with `revise`.
+- `stats` also lists **kept flagged names**: AI items JEV kept although a word
+  matched the censored list (name, matched word, JEV's score, when). Read
+  each one as a child would; `retire` any that reads rudely.
+- `revise` changes an item's `--why` (the explanation on its card: the pair
+  that first made it), `--emoji` or `--category`, through the same checks. The
+  name never changes: players hold it. Audited as `craft.revise`.
+- Expansion: `stats` shows the frontier (items no pair uses yet, and untried
+  pairs); seed pairs that use frontier items so Today's Star has fresh targets.
+
+Take-down and repair (added 2026-10-13):
+
+```bash
+lumine admin craft retire --build 1499 --item "<name or id>" --reason "Not suitable for children"            # dry run
+lumine admin craft retire --build 1499 --item "<name or id>" --reason "Not suitable for children" --confirm
+lumine admin craft unfizzle --build 1499 [--since 2026-10-13T00:00:00Z] [--pair Water+Fire]                # dry run
+lumine admin craft unfizzle --build 1499 --since 2026-10-13T00:00:00Z --confirm
+```
+
+- `retire` takes a bad item down everywhere: it leaves collections, item
+  cards, rankings, journeys and the daily target (today's star is re-picked);
+  the pairs that make it fizzle and no AI answer or seed can make it again;
+  its unpaid World First no longer pays (a paid one stays paid); its name
+  leaves bounty story lines. Who, when and why are stored on the item and in
+  the admin audit (`craft.retire`). Starters cannot be retired. There is no
+  un-retire.
+- Word Master's censored list (`content_words_censored`) is a Wordle filter,
+  not a moderation list, so a hit never decides anything on its own. A name
+  with a listed word (whole words only, simple inflections both ways: -s,
+  -es, -ed, -ing; hyphens count as spaces) is always judged by JEV as a
+  whole, told which word to look at, and must clear a stricter bar. Crystal
+  Ball, Sperm Whale, Pork Loin or Blue-Footed Booby pass when JEV finds them
+  innocent; a rude reading is regenerated once, then the pair fizzles.
+  Only JEV itself judges such a name: if JEV is down and its fallback model
+  answers, the merge takes the outage path below (the answer is kept and
+  re-checked once JEV is back). There is no allowlist. For seeds a hit is a
+  **warning** in the report (printed as `warning …` lines, and in `warnings`
+  with `--json`), never a rejection.
+- During a safety-check outage players get `craft_check_unavailable`. A
+  pair's answer is paid for once and re-checked free for 24 h from when the
+  model wrote it; after that a new try generates fresh. (If JEV later judges
+  the kept answer low, the one normal regeneration is billed as usual.) Each
+  server pauses new runs for a minute after an outage (per pair, or
+  everywhere after three); the pause never stops the free re-check of a kept
+  answer or a run that has already paid.
+- `unfizzle` repairs pairs that fizzled because the safety check itself
+  failed (an outage before 2026-10-13; a check outage now fails the merge
+  without storing anything). It resets only fizzles whose stored checks all
+  errored, never a real low verdict or a censored word; the next player to
+  try the pair asks again. `--since` and `--pair` narrow it; up to 5,000
+  fizzles are scanned per run.
+
 ### Reward question-bank seeding (every full daily review; added 2026-09-28)
 
 `generated-quiz` rules fill a question bank on the server: a question is