@stage5/lumine 0.3.84 → 0.3.86

package/README.md

@@ -377,14 +377,15 @@ To preserve Pro output in an existing script, change the option to
 using Pro through the server's legacy model alias. This CLI release must be
 published after the API update that accepts the new model IDs.
 
-`lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana|nano-banana-pro>` creates
+`lumine assets generate "<prompt>" --model <flare|sunburst|gpt-image-2|nano-banana|nano-banana-pro>` creates
 an AI-generated image asset instead of uploading one. `--model` is required
-(Flare = fast generation; Sunburst = precise editing; gpt-image-2 = original
-model; nano-banana = Gemini Nano Banana 2.1, nano-banana-pro = Gemini Nano Banana Pro). Generation spends your Twinkle AI Battery, so the
+(flare = GPT Image 2.6 Flare, fast generation; sunburst = GPT Image 2.6
+Sunburst, precise editing; the full ids gpt-image-2.6-flare/-sunburst work too,
+and the retired 2.5 ids now mean 2.6; gpt-image-2 = original model; nano-banana = Gemini Nano Banana 2.1, nano-banana-pro = Gemini Nano Banana Pro). Generation spends your Twinkle AI Battery, so the
 CLI shows the estimated cost and asks for confirmation first — non-interactive
 runs must pass
 `--yes` to consent. `--quality low|medium|high|xhigh|max` applies to GPT Image
-models; `xhigh` and `max` require a 2.5 model. Estimates describe image output;
+models; `xhigh` and `max` require a 2.6 model (flare or sunburst). Estimates describe image output;
 actual battery usage also includes prompt and reference input.
 
 ## Thumbnails
@@ -392,7 +393,7 @@ actual battery usage also includes prompt and reference input.
 `lumine thumbnail set <file>` uploads a jpg/png/webp (max 8MB) as the build's
 thumbnail. `lumine thumbnail capture` screenshots the running app server-side
 and sets the result (add `--out <file>` to keep a local copy).
-`lumine thumbnail generate ["<prompt>"] --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana|nano-banana-pro>`
+`lumine thumbnail generate ["<prompt>"] --model <flare|sunburst|gpt-image-2|nano-banana|nano-banana-pro>`
 generates an AI image and sets it as the thumbnail (the image is also kept as a
 normal reusable asset); without a prompt the server composes one from the build
 title and description. Replacing an existing thumbnail asks for confirmation;

package/lib/admin-arena.js

@@ -13,6 +13,10 @@ import path from "node:path";
 //                              at once; a dry run (validation only) unless --confirm;
 //                              re-importing a folder retires that paper's earlier items
 //   status --item <id> --to live|retired|checked
+//   paper-assemble --file <manifest.json>   publish a complete paper from existing,
+//                              never-served IDs, including reviewed text passages
+//                              and unscored writing; preview unless --confirm;
+//                              preserves content versions and exposures
 //   revise --file <revisions.json>   in-place text/passage/visual/review fixes to
 //                              live items: same item id, a new content version;
 //                              a dry run unless --confirm; audited
@@ -25,7 +29,7 @@ import path from "node:path";
 //                              <itemId>.png renders of picture-option items
 //                              (panels are drawn by the web, not stored)
 export const ARENA_USAGE =
-  "Usage: lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | marking [--cursor <id>] [--limit <1-200>] | import (--dir <paper folder> | --additive --file <reviewed-items.json>) [--audio audio/<exam>/<paper>] [--live] [--confirm] | status --item <id> --to live|retired|checked [--confirm] | revise --file <revisions.json> [--confirm] | today-queue [--cursor <id>] [--limit <1-100>] | today-member --user <id> | today-import --file <reviewed-questions.json> [--confirm] | today-withdraw --user <id> (--keys <key,...> | --file <withdraw.json>) --reason <text> [--confirm] | picture-audit [--items <id,id,...> | --cursor <id>] [--limit <1-20>] [--renders <dir of <itemId>.png>] [--output <review-list.json>] [--json]";
+  "Usage: lumine admin arena queue | paper-queue [--cursor <id>] [--limit <1-100>] | marking [--cursor <id>] [--limit <1-200>] | import (--dir <paper folder> | --additive --file <reviewed-items.json>) [--audio audio/<exam>/<paper>] [--live] [--confirm] | paper-assemble --file <manifest.json> [--confirm] | status --item <id> --to live|retired|checked [--confirm] | revise --file <revisions.json> [--confirm] | today-queue [--cursor <id>] [--limit <1-100>] | today-member --user <id> | today-import --file <reviewed-questions.json> [--confirm] | today-withdraw --user <id> (--keys <key,...> | --file <withdraw.json>) --reason <text> [--confirm] | picture-audit [--items <id,id,...> | --cursor <id>] [--limit <1-20>] [--renders <dir of <itemId>.png>] [--output <review-list.json>] [--json]";
 const MAX_ITEMS = 300;
 
 function validationError(message) {
@@ -154,6 +158,56 @@ function buildTodayWithdraw(options) {
 }
 
 export function buildArenaOperation({ action, options }) {
+  if (action === "paper-assemble") {
+    if (!options.adminFile || options.adminDir || options.adminArenaAdditive || options.adminArenaAudio) {
+      throw validationError("Use paper-assemble --file <manifest.json> [--confirm]; it uses existing item IDs, never a content import.");
+    }
+    const file = path.resolve(options.adminFile);
+    let parsed;
+    try {
+      if (fs.statSync(file).size > 200_000) throw validationError("The assembly manifest must be under 200 KB.");
+      parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch (error) {
+      if (error.code === "CLI_ADMIN_CLI_VALIDATION") throw error;
+      throw validationError(`Cannot read the assembly manifest ${file}: ${error.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) ||
+        typeof parsed.exam !== "string" || !["easy", "normal", "hard"].includes(parsed.difficulty) ||
+        typeof parsed.paper !== "string" || !/^[A-Za-z0-9][A-Za-z0-9-]{0,39}$/.test(parsed.paper) ||
+        !Array.isArray(parsed.items) || !parsed.items.length || parsed.items.length > MAX_ITEMS || !parsed.review) {
+      throw validationError("The manifest needs exam, difficulty, paper, reviewed existing items and review evidence.");
+    }
+    for (const item of parsed.items) {
+      if (!item || !Number.isSafeInteger(item.itemId) || item.itemId <= 0 ||
+          !Number.isSafeInteger(item.expectedVersion) || item.expectedVersion < 1 ||
+          !Number.isSafeInteger(item.number) || item.number < 1 ||
+          typeof item.contentHash !== "string" || !/^[a-f0-9]{64}$/.test(item.contentHash) ||
+          (item.passageId !== undefined && (!Number.isSafeInteger(item.passageId) || item.passageId <= 0)) ||
+          Object.keys(item).some(key => !["itemId", "expectedVersion", "number", "contentHash", "passageId"].includes(key))) {
+        throw validationError("Each entry needs itemId, expectedVersion, number and contentHash; replacement content is not accepted.");
+      }
+    }
+    if (new Set(parsed.items.map(i => i.itemId)).size !== parsed.items.length || new Set(parsed.items.map(i => i.number)).size !== parsed.items.length) {
+      throw validationError("Item IDs and blueprint numbers must be unique.");
+    }
+    if (parsed.passages !== undefined && (!Array.isArray(parsed.passages) || parsed.passages.length > MAX_ITEMS ||
+        parsed.passages.some(p => !p || !Number.isSafeInteger(p.passageId) || p.passageId <= 0 ||
+          !Number.isSafeInteger(p.expectedVersion) || p.expectedVersion <= 0 ||
+          typeof p.contentHash !== "string" || !/^[a-f0-9]{64}$/.test(p.contentHash) ||
+          Object.keys(p).some(key => !["passageId", "expectedVersion", "contentHash"].includes(key))) ||
+        new Set(parsed.passages.map(p => p.passageId)).size !== parsed.passages.length)) {
+      throw validationError("Passages need unique existing IDs, expectedVersion and canonical hashes, never replacement text.");
+    }
+    const referenced = [...new Set(parsed.items.flatMap(i => i.passageId === undefined ? [] : [i.passageId]))].sort((a, b) => a - b);
+    const reviewed = (parsed.passages || []).map(p => p.passageId).sort((a, b) => a - b);
+    if (JSON.stringify(referenced) !== JSON.stringify(reviewed)) throw validationError("Review every referenced passage exactly once and omit unreferenced passages.");
+    const confirm = confirmed(options);
+    return { name: confirm ? "arena.paper.assemble" : "arena.paper.assemble.preview", method: "POST",
+      path: "/cli/admin/arena/papers/assemble",
+      body: { exam: parsed.exam, difficulty: parsed.difficulty, paper: parsed.paper, items: parsed.items,
+        ...(parsed.passages !== undefined ? { passages: parsed.passages } : {}), review: parsed.review, dryRun: !confirm },
+      mutates: confirm, requiresRun: false, timeoutMs: 120000 };
+  }
   if (action === "picture-audit") {
     const limit = Number(options.adminLimit ?? 10);
     if (!Number.isInteger(limit) || limit < 1 || limit > PICTURE_AUDIT_MAX) throw validationError(`Use --limit from 1 to ${PICTURE_AUDIT_MAX}.`);
@@ -307,6 +361,11 @@ export function buildArenaOperation({ action, options }) {
 }
 
 export function formatArenaResult({ operation, data }) {
+  if (operation.name === "arena.paper.assemble" || operation.name === "arena.paper.assemble.preview") {
+    if (data?.alreadyAssembled) return [`${data.paper}: already assembled from the same existing items; nothing changed.`];
+    return [`${data?.dryRun ? "Dry run: would assemble" : "Assembled"} ${data?.wouldAssemble ?? data?.assembled ?? 0} existing items as ${data?.paper}. IDs, content versions and exposures are preserved.`,
+      ...(data?.dryRun ? ["Add --confirm to publish this reviewed complete paper."] : [])];
+  }
   if (operation.name === "arena.paper.queue") return [
     `Checked ${data?.scannedMembers ?? 0} members; ${data?.entries?.length ?? 0} exam tracks are waiting for fresh papers on this page.`,
     ...(data?.entries || []).map(row => `${row.username} (${row.userId}): ${row.examKey} ${row.difficulty}/${row.length}${row.reason === "solo_mastery_paper" ? " — solo mastery ready" : ""}`),

package/lib/admin-daily.js

@@ -250,7 +250,7 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
   step("brief", ["brief"], "brief.json");
   step("todos", ["todo", "list"], "todos.json");
   step("escalations", ["escalation", "list"], "escalations.json");
-  const paperQueue = { complete: false, pages: 0, waitingTracks: 0 };
+  const paperQueue = { complete: false, pages: 0, waitingTracks: 0, demandBases: [] };
   let paperCursor = 0;
   for (;;) {
     paperQueue.pages++;
@@ -260,11 +260,12 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
     if (!res.ok) break;
     const data = res.json?.data;
     const next = data?.nextCursor;
-    if (data?.demandBasis !== "waiting-published-papers-v1" || !Array.isArray(data?.entries) ||
+    if (!["waiting-published-papers-v1", "cleared-exhausted-papers-v2"].includes(data?.demandBasis) || !Array.isArray(data?.entries) ||
         !(next === null || (Number.isSafeInteger(next) && next > paperCursor))) {
       failLast("Invalid or non-advancing Arena paper-waiting page.");
       break;
     }
+    if (!paperQueue.demandBases.includes(data.demandBasis)) paperQueue.demandBases.push(data.demandBasis);
     paperQueue.waitingTracks += data.entries.length;
     if (next === null) { paperQueue.complete = true; break; }
     if (paperQueue.pages >= 100) {

package/lib/admin.js

@@ -430,7 +430,7 @@ function buildApprovalOperation({ action, target, options }) {
 // Code agent passes wrote (no model is called), then review what they could
 // not settle (Mikey 2026-10-06: bulk AI work runs on Claude Code agents).
 const ENGLISH_USAGE =
-  "Use: lumine admin english import <verdicts.json> --pass a|b | adjudicate <verdicts.json> | add-questions <questions.json> | relevel <moves.json> | mastery <userId> --reason <why> | backfill-distractors | summary | review [--limit <n>] | accept|retire <questionId> [--reason <text>] [--fault] | retag <questionId> --skill <code> [--reason <text>] | build-candidates [--after <questionId>] [--limit <n>] | build-import <verdicts.json> | check-candidates [--after <questionId>] [--limit <n>] | check-import <verdicts.json> | check-broken [--after <questionId>] [--limit <n>] | check-apply <fixes.json> | check-verify <checked.json> | check-follow-faulty [--after <next>] [--limit <n>] | audit-backlog [--after <questionId>] [--limit <n>] | audit-mark <marks.json> | lesson-candidates [--after <skillCode>] [--limit <n>] | lesson-import <lessons.json> | lesson-approve <approvals.json> | lessons [--status draft|approved]";
+  "Use: lumine admin english import <verdicts.json> --pass a|b | adjudicate <verdicts.json> | add-questions <questions.json> | relevel <moves.json> | mastery <userId> --reason <why> | backfill-distractors | summary | review [--limit <n>] | accept|retire <questionId> [--reason <text>] [--fault] | retag <questionId> --skill <code> [--reason <text>] | build-candidates [--after <questionId>] [--limit <n>] | build-import <verdicts.json> | check-candidates [--after <questionId>] [--limit <n>] | check-import <verdicts.json> | check-broken [--after <questionId>] [--limit <n>] | check-apply <fixes.json> | check-verify <checked.json> | check-follow-faulty [--after <next>] [--limit <n>] | quest-evidence <case.json> [--confirm] | audit-backlog [--after <questionId>] [--limit <n>] | audit-mark <marks.json> | lesson-candidates [--after <skillCode>] [--limit <n>] | lesson-import <lessons.json> | lesson-approve <approvals.json> | lessons [--status draft|approved]";
 const ENGLISH_IMPORT_MAX = 500;
 
 function buildEnglishOperation({ action, target, options }) {
@@ -512,6 +512,24 @@ function buildEnglishOperation({ action, target, options }) {
     if (after && !/^(?:[ufc]:)?\d+:\d+$/.test(after)) throw cliValidationError("--after takes the last reply's next (<phase:id:version>).");
     return writeOperation("english.check_follow_faulty", "POST", "/cli/admin/english/item-checks/follow-faulty", { after, limit: limitOf(200, 100) }, { requiresRun: false, timeoutMs: 300000 });
   }
+  // A single legacy Quest skill is previewed from its complete saved history.
+  // Applying requires both --confirm and that exact preview's source hash.
+  if (action === "quest-evidence" && target) {
+    const input = readAdminJsonFile(target, "<quest-evidence.json>", { maxBytes: 16 * 1024 });
+    if (!input || !Number.isSafeInteger(input.userId) || input.userId <= 0 ||
+        typeof input.skillCode !== "string" || !input.skillCode || input.skillCode.length > 64) {
+      throw cliValidationError("The file needs one positive userId and one skillCode.");
+    }
+    if (options.adminConfirm && options.adminConfirm !== "true") throw cliValidationError("Pass --confirm on its own, without a value.");
+    const confirm = options.adminConfirm === "true";
+    if (confirm && options.adminDryRun) throw cliValidationError("Choose --confirm or --dry-run, not both.");
+    if (confirm && !/^[a-f0-9]{64}$/.test(String(input.expectedHash || ""))) {
+      throw cliValidationError("Applying needs expectedHash from the exact preview.");
+    }
+    return writeOperation("english.quest-evidence", "POST", "/cli/admin/english/quest-evidence/reconcile",
+      { userId: input.userId, skillCode: input.skillCode, expectedHash: input.expectedHash, dryRun: !confirm },
+      { requiresRun: false, mutates: confirm, timeoutMs: 120000 });
+  }
   // Grammar Quest audit passes (Mikey 2026-10-17): the checked items no pass
   // has looked at yet, first; and marking what a pass read,
   // { audit: "<name>", items: [{ questionId, version, contentHash, outcome }] }

package/lib/assets.js

@@ -66,7 +66,7 @@ export async function assetsCommand(options) {
     return;
   }
   throw new Error(
-    'Usage: lumine assets [list] | lumine assets upload <file...> | lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana|nano-banana-pro> | lumine assets delete <assetId> | lumine assets prune [--yes] | lumine assets storage | lumine assets request-storage [--size 500MB|1GB|2GB] [--reason "<what it is for>"]',
+    'Usage: lumine assets [list] | lumine assets upload <file...> | lumine assets generate "<prompt>" --model <flare|sunburst|gpt-image-2|nano-banana|nano-banana-pro> | lumine assets delete <assetId> | lumine assets prune [--yes] | lumine assets storage | lumine assets request-storage [--size 500MB|1GB|2GB] [--reason "<what it is for>"]',
   );
 }
 
@@ -156,7 +156,7 @@ export function resolveGenerateModel(options) {
   const model = GENERATE_MODEL_ALIASES[rawModel];
   if (!model) {
     throw new Error(
-      "--model is required: gpt-image-2.5-flare (fast generation), gpt-image-2.5-sunburst (precise editing), gpt-image-2, nano-banana (Nano Banana 2.1) or nano-banana-pro. No default model is applied.",
+      "--model is required: flare (GPT Image 2.6 Flare, fast generation), sunburst (GPT Image 2.6 Sunburst, precise editing), gpt-image-2, nano-banana (Nano Banana 2.1) or nano-banana-pro. No default model is applied.",
     );
   }
   const rawQuality = String(options.quality || "").trim();
@@ -169,7 +169,7 @@ export function resolveGenerateModel(options) {
     );
   }
   if (model === "gpt-image-2" && ["xhigh", "max"].includes(rawQuality)) {
-    throw new Error("xhigh and max require a GPT Image 2.5 model.");
+    throw new Error("xhigh and max require a GPT Image 2.6 model (flare or sunburst).");
   }
   return { model, quality: rawQuality || null };
 }
@@ -212,7 +212,7 @@ export async function assetsGenerate(options) {
   const prompt = String(options.positional[1] || "").trim();
   if (!prompt) {
     throw new Error(
-      'Usage: lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana|nano-banana-pro> [--quality low|medium|high|xhigh|max] [--name <fileName>] [--yes]',
+      'Usage: lumine assets generate "<prompt>" --model <flare|sunburst|gpt-image-2|nano-banana|nano-banana-pro> [--quality low|medium|high|xhigh|max] [--name <fileName>] [--yes]',
     );
   }
   const { model, quality } = resolveGenerateModel(options);

package/lib/commands.js

@@ -3287,7 +3287,7 @@ export function printHelp() {
   lumine sdk call <namespace.method> [jsonArgs]
   lumine assets [list]
   lumine assets upload <file...>
-  lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana|nano-banana-pro>
+  lumine assets generate "<prompt>" --model <flare|sunburst|gpt-image-2|nano-banana|nano-banana-pro>
   lumine assets delete <assetId>
   lumine assets prune [--yes]
   lumine assets storage [--json]
@@ -3301,7 +3301,7 @@ export function printHelp() {
   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|nano-banana-pro>
+  lumine thumbnail generate ["<prompt>"] --model <flare|sunburst|gpt-image-2|nano-banana|nano-banana-pro>
   lumine doctor runtime-assets
   lumine admin identity list|status|use <zero|ciel|auto> [--json]
   lumine admin identity inspect <user-id|username> --reason <management-reason> [--include-private-evidence] [--output <file>] [--json]   (nothing kept on disk unless --output; that copy is 0600)
@@ -3494,7 +3494,7 @@ Examples:
   npx @stage5/lumine@latest assets generate "pixel-art forest background" --model nano-banana
   npx @stage5/lumine@latest thumbnail set art/cover.png
   npx @stage5/lumine@latest thumbnail capture --out capture.png
-  npx @stage5/lumine@latest thumbnail generate --model gpt-image-2 --yes
+  npx @stage5/lumine@latest thumbnail generate --model flare --yes
   npx @stage5/lumine@latest doctor runtime-assets --build 917 --json
   npx @stage5/lumine@latest admin daily-run start --identity auto --comment-mode off --json
   npx @stage5/lumine@latest admin daily-run start --scope featured --identity auto --json
@@ -3588,8 +3588,8 @@ Options:
   --json                Print machine-readable output where supported
   --keep-assets         Keep doctor probe assets instead of deleting them
   --no-browser          Skip doctor browser probes
-  --model <model>       Image model for generate: gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2, nano-banana (Nano Banana 2.1) or nano-banana-pro (required)
-  --quality <q>         GPT Image quality: low, medium, high, xhigh, max (default high; xhigh/max require 2.5)
+  --model <model>       Image model for generate: flare (GPT Image 2.6 Flare), sunburst (GPT Image 2.6 Sunburst), gpt-image-2, nano-banana (Nano Banana 2.1) or nano-banana-pro (required)
+  --quality <q>         GPT Image quality: low, medium, high, xhigh, max (default high; xhigh/max require flare or sunburst)
   --name <fileName>     File name hint for a generated asset
   --out <path>          With thumbnail capture: also save the capture locally
   --transparent         Ask GPT Image for a transparent background (assets generate)

package/lib/constants.js

@@ -21,10 +21,13 @@ export const DEFAULT_TIMEOUT_MS = 20000;
 export const ASSET_GENERATE_TIMEOUT_MS = 6 * 60 * 1000;
 export const THUMBNAIL_CAPTURE_TIMEOUT_MS = 90 * 1000;
 export const GENERATE_MODEL_ALIASES = {
-  "gpt-image-2.5-flare": "gpt-image-2.5-flare",
-  "gpt-image-2.5-sunburst": "gpt-image-2.5-sunburst",
-  flare: "gpt-image-2.5-flare",
-  sunburst: "gpt-image-2.5-sunburst",
+  "gpt-image-2.6-flare": "gpt-image-2.6-flare",
+  "gpt-image-2.6-sunburst": "gpt-image-2.6-sunburst",
+  flare: "gpt-image-2.6-flare",
+  sunburst: "gpt-image-2.6-sunburst",
+  // GPT Image 2.6 replaced 2.5 (2026-11-07); old scripts keep working.
+  "gpt-image-2.5-flare": "gpt-image-2.6-flare",
+  "gpt-image-2.5-sunburst": "gpt-image-2.6-sunburst",
   "gpt-image-2": "gpt-image-2",
   // Gemini by tier (the API's NANO_BANANA_MODEL / NANO_BANANA_PRO_MODEL):
   // nano-banana = the fast tier (Nano Banana 2.1 since 2026-10-08), pro = Pro
@@ -314,12 +317,16 @@ lumine save --summary "Describe the change"
   replaces. Update code references, then delete or prune the old asset.
 - Prefer one small assets module (e.g. src/assets.js) mapping names to asset
   URLs over scattering URLs through the code.
-- \`lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana|nano-banana-pro>\` creates
-  an AI-generated image asset. --model is REQUIRED (no default): gpt-image-2 is
-  best quality but slower and pricier; nano-banana (Gemini Nano Banana 2.1) is
-  the fastest and cheapest; nano-banana-pro (Gemini Nano Banana Pro) sits between. It spends the logged-in user's AI Battery, so it asks y/N with the
+- \`lumine assets generate "<prompt>" --model <flare|sunburst|nano-banana|nano-banana-pro|gpt-image-2>\` creates
+  an AI-generated image asset. --model is REQUIRED (no default): flare
+  (GPT Image 2.6 Flare) is the usual choice: high quality, clean lettering,
+  about 10 seconds; sunburst (GPT Image 2.6 Sunburst) is slower and best for
+  careful edits of an existing image; nano-banana (Gemini Nano Banana 2.1) is
+  the cheapest; nano-banana-pro (Gemini Nano Banana Pro) sits between;
+  gpt-image-2 is the older model, several times pricier than flare. It spends the logged-in user's AI Battery, so it asks y/N with the
   estimated cost first; non-interactive runs must pass --yes to consent.
-  Optional: --quality low|medium|high (gpt-image-2 only, default high),
+  Optional: --quality low|medium|high|xhigh|max (GPT Image models only,
+  default high; xhigh and max need flare or sunburst),
   --name <fileName>. The asset lands in .twinkle/${ASSETS_METADATA_FILE} like an upload.
 
 ## Studying Game Music
@@ -349,7 +356,7 @@ lumine save --summary "Describe the change"
   build's thumbnail. Thumbnails display ~16:9; the image is uploaded uncropped.
 - \`lumine thumbnail capture\` screenshots the running app server-side and sets
   the result as the thumbnail (add --out <file> to also save it locally).
-- \`lumine thumbnail generate "<prompt>" --model <gpt-image-2|nano-banana|nano-banana-pro>\`
+- \`lumine thumbnail generate "<prompt>" --model <flare|sunburst|nano-banana|nano-banana-pro|gpt-image-2>\`
   generates an AI image and sets it as the thumbnail (also stored as a normal
   reusable asset). Same battery-cost consent rules as \`assets generate\`.
 - Replacing an existing thumbnail asks y/N; pass --yes for non-interactive runs.

package/lib/platformRules.generated.js

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

package/lib/thumbnail.js

@@ -42,7 +42,7 @@ export async function thumbnailCommand(options) {
     return;
   }
   throw new Error(
-    'Usage: 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|nano-banana-pro>',
+    'Usage: lumine thumbnail set <file> | lumine thumbnail capture [--out <file>] | lumine thumbnail generate "<prompt>" --model <flare|sunburst|gpt-image-2|nano-banana|nano-banana-pro>',
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.84",
+  "version": "0.3.86",
   "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.80.0
-Updated: 2026-11-02
-Generated: 2026-11-02T01:36:03.543Z
+Version: 1.81.0
+Updated: 2026-11-07
+Generated: 2026-11-07T02:35:09.137Z
 
 ## Platform rules
 Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.
@@ -15,10 +15,13 @@ Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed f
 6. Code loads only from project files and Twinkle's vendor paths (/build/vendor/...). Package imports, CDN scripts, external network calls and app-local /api/* routes fail at runtime; use the Twinkle SDK for data, AI and storage.
 7. Call only Twinkle.* methods documented in the SDK reference. An invented or guessed method name throws and breaks the feature.
 8. Twinkle.privateDb and Twinkle.sharedDb save on a user action or as an occasional snapshot, never per frame, tick or keystroke: fast repeated writes are refused with 429 and the data is lost. A privateDb value is at most 16 KB. Keep live state in memory, and use Twinkle.world for realtime multiplayer.
-9. Start sound and image generation inside the viewer's tap or click handler. A Web Audio AudioContext stays silent until it is created or resumed in a tap (iPhones always enforce this), and Twinkle.ai.generateImage called from load or a timer fails with USER_ACTIVATION_REQUIRED.
-10. Call setPointerCapture only inside a pointerdown handler with that event's pointerId, wrapped in try/catch, and release only when hasPointerCapture says the element holds it. From click, mouse, timer or synthetic handlers it throws and the control stops working.
-11. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.
-12. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.
+9. Before changing an existing view, read its relevant event handlers, animations and state flow, and identify the behavior the edit must keep. A new appearance, reference image, renderer or performance improvement does not authorize removing an interaction, animation or capability; preserve it unless the creator explicitly asks for that change. After editing, compare the affected behavior before and after, including its active and inactive states (for example, playing and paused). Exercise those states when tools allow; a still screenshot or a clean console cannot prove motion or interaction. If a state cannot be exercised, report that limit rather than claiming it is preserved.
+10. When changing stored data or a renderer, inspect both the old save/resume shape and every reader, including fallback views. Keep existing saves readable with an explicit, non-destructive conversion and retain fields needed by another supported renderer. Verify an old save in the new version, new state after reload, and switching to the fallback (for example, 2D x/y toppings becoming 3D positions and returning to a flat view). Never silently drop saved objects or reset progress to make the new view work; an incomplete migration is part of this change to finish, not unrelated future polish.
+11. Keep local gameplay and unsaved edits separate from confirmed server state. Await storage writes and replace saved counters, scores and other durable state from the documented canonical response; Twinkle.privateDb.get/set return { item }, and the stored data is item.value (get may return item: null). Never read a guessed response shape, present a local increment as saved, or swallow a save/load error. Keep unfinished work recoverable, show a clear pending or failed-save state, and let the viewer retry deliberately without counting the same action twice. Verify canonical response restoration, rejected saves and delayed replies, not only a successful local animation.
+12. Start sound and image generation inside the viewer's tap or click handler. A Web Audio AudioContext stays silent until it is created or resumed in a tap (iPhones always enforce this), and Twinkle.ai.generateImage called from load or a timer fails with USER_ACTIVATION_REQUIRED.
+13. Call setPointerCapture only inside a pointerdown handler with that event's pointerId, wrapped in try/catch, and release only when hasPointerCapture says the element holds it. From click, mouse, timer or synthetic handlers it throws and the control stops working.
+14. Keyboard games call preventDefault for their keys (Space, arrows, WASD) from a window or document keydown listener added with { passive: false }, skipping inputs, textareas, selects and contenteditable, and make the playfield focusable; otherwise those keys scroll or jump the page during play.
+15. On phones a long press on game controls selects text or opens the Copy/Look Up menu unless the whole game area (controls, HUD, menus, empty play space) is marked data-twinkle-no-select and styled user-select: none; -webkit-user-select: none; -webkit-touch-callout: none. A game drawn without a canvas sets data-twinkle-game on <html> too, so Twinkle's phone touch protections apply. Keep inputs and copyable text selectable with data-twinkle-selectable.
 
 ## Essential SDK features
 Features every app needs whenever they apply. When you build a new app or make a substantial change, add every one that applies as part of that change, without being asked. On a small, targeted request, add a missing one only when the request touches what it covers (a change to levels, scoring or saving: keep-place; a new screen: back-button); otherwise name it in one line so the creator can ask. Say in one line what you added. Never add one that does not apply.
@@ -543,7 +546,7 @@ renderBattery(policy?.energyPercent, policy?.energySegmentsRemaining);
   - Example: const chatHistory = conversation.slice(-12).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text }));
 const result = await Twinkle.ai.chat({ message, history: chatHistory, systemPrompt: 'You are a cheerful pirate helper who answers in one sentence.', onText: (text, meta) => renderReply(text), onStatus: (status) => setThinking(status === 'thinking') });
 - async decide({ state, questions, images }) | scopes: none
-  - Returns: { answers, model, provider, aiUsagePolicy, imageCount? }
+  - Returns: { decisionId, answers, model, provider, aiUsagePolicy, imageCount? }
   - Use JEV for fast contextual choices, yes/no probabilities, and scores inside a running app. Send several independent questions about the same state together.
   - Read the AI decision design guidance when deciding whether this capability benefits the app. This method evaluates supplied context; it does not generate prose, browse, run tools, grant access, or award XP/Coins. It looks at pictures only through the preview images option below.
   - state is non-empty text, a JSON object, or a JSON array. questions maps your question IDs to { type, instructions, criteria? }. Instructions may be non-empty text or structured JSON. Every question sees the same state and answers independently; put the complete question in instructions, not just its ID.
@@ -552,6 +555,7 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Yes/no probability: { type: 'noul', instructions, criteria?: { true: description, false: description } }. Returns { type: 'noul', noul }, where noul is the probability of yes between 0 and 1. There is no separate confidence field. If criteria is supplied, describe both true and false.
   - A request accepts 1–32 questions, at most 64 KB of JSON and 20 levels of nesting. Question IDs and option names must be non-empty, at most 128 characters, and cannot be __proto__, constructor, or prototype. Descriptions may use structured JSON; state must contain only data the app is allowed to access.
   - Requires a signed-in viewer and uses the normal runtime AI rate limits. Twinkle selects and calls JEV on its server; never put provider credentials or an external endpoint in app code. Decisions are covered by Twinkle: they never use the viewer's AI Energy, and a viewer with empty Energy still gets answers. The response includes the viewer's current canonical aiUsagePolicy, unchanged by the call.
+  - Successful decisions include a server-generated decisionId. Keep it with the returned provider and model when recording a decision outcome; it identifies that decision, not a fight or a reward receipt. A failed request may include requestId when server decision handling began; failures before that point may have no ID.
   - Errors include invalid_ai_decision (bad input), ai_decision_unavailable, ai_decision_timeout, ai_decision_rate_limited, ai_decision_invalid_response, and ai_usage_unavailable, plus the existing auth, access, Energy, and rate-limit errors. Invalid answers are rejected. An answer that fails validation is retried once on the server within the same deadline; there is no other provider retry, fabricated answer, or paid LLM fallback. Do not automatically retry a rejected request.
   - Preview: images (not generally available yet). Pass images: { name: picture } with 1-4 entries to let JEV look at pictures. Names use lowercase letters, digits and underscores (e.g. drawing); each name becomes a key of state, so state must then be a JSON object without that key, and instructions refer to the picture by name (e.g. 'Does `drawing` show a cat?'). A picture is this app's own upload URL (from Twinkle.files, at most 5 MB each), a canvas, or a PNG/JPEG/WebP Blob of at most 3 MB (5 MB of snapshots per decision). All pictures of one decision together must be at most 10 MB; a larger one is refused with 'Image too large: max 5 MB each, 10 MB per decision. Resize the picture first.' so resize big pictures before asking. Image decisions are covered by Twinkle like text decisions. Only some run at once (one per player, several per app, and a generous ceiling per minute for the app), so wait for one answer before asking again and do not call decide in a tight loop. Until Twinkle turns them on for the app, and whenever a picture cannot be checked or too many decisions are running, decide throws ai_decision_unavailable with a reason (disabled, app_disabled, rate_limited, capped, images_dropped, timeout, ...). There is never a text-only answer that ignores the pictures. Use images only when the creator asks for it, keep the feature usable without it (for example skip the AI check and let the player continue), and never use the answer for safety, access, XP or Coins.
   - Call on meaningful app events with bounded frequency, batch questions, and keep rendering and deterministic game rules in local code. Ignore a result if the app state or turn changed while it was pending. Test uncertain inputs and choose a fallback appropriate to the experience; confidence is not a correctness guarantee.
@@ -599,10 +603,10 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Pass requestId when you need to correlate browser logs, backend logs, and iframe status events for one generation.
   - partial_image statuses may include partialImageB64 for progressive preview UI before the final imageUrl arrives.
   - referenceImageB64 may be a raw base64 string or a data:image/...;base64 URL.
-  - Optional model: gpt-image-2.5-flare or gpt-image-2.5-sunburst. Without a model, OpenAI uses Flare for new images and Sunburst when a reference image or continuation is supplied. Explicit gpt-image-2 remains supported.
-  - Quality accepts low, medium, high, xhigh, or max. xhigh and max require a GPT Image 2.5 model. Gemini has one quality tier.
+  - Optional model: gpt-image-2.6-flare (fast) or gpt-image-2.6-sunburst (careful edits, slower). Without a model, OpenAI uses Flare for new images and Sunburst when a reference image or continuation is supplied. GPT Image 2.6 replaced 2.5: an app that still sends gpt-image-2.5-flare or gpt-image-2.5-sunburst gets the 2.6 model of the same name. Explicit gpt-image-2 remains supported.
+  - Quality accepts low, medium, high, xhigh, or max. xhigh and max require a GPT Image 2.6 model. Gemini has one quality tier. On 2.6, low and medium are faster but cost almost as much as high (roughly 47% and 82% of high), so pick quality for speed rather than to save energy.
   - engine: 'gemini' uses Google's Nano Banana 2.1 (the fast Gemini image tier; it replaced the retired original Nano Banana on 2026-10-08).
-  - GPT Image 2.5 battery spending uses actual image-model input and output token usage. The confirmation shows an image-output estimate; prompts and reference images use additional energy.
+  - GPT Image 2.6 battery spending uses actual image-model input and output token usage. The confirmation shows an image-output estimate; prompts and reference images use additional energy.
   - responseId and imageId are opaque continuation handles. Pass them back unchanged to edit a prior result; do not assume an OpenAI ID format. Existing GPT Image 2 continuations remain usable.
   - Example: const result = await Twinkle.ai.generateImage({ prompt: 'Create a fashion guide portrait for this face with flattering colors and outfit ideas', referenceImageB64, quality: 'high', onStatus: (status) => console.log(status.stage) });
 - async generateMusic({ prompt, length, instrumental, requestId, timeoutMs } = {}) | scopes: none
@@ -1000,13 +1004,14 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - limit is 1-50 (default 10). kind filters to helper or workshop builds.
   - Example: const { builds } = await Twinkle.minecraft.getZeroBuilds({ limit: 10, kind: 'workshop' });
 - async getPeople() | scopes: content:read
-  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', op, online, isZero, twinkle: { userId, username } | null, ...owner: groups, banned, protected, firstSeenAt, lastSeenAt, endorsements: [{ voucherName, voucherUuid, endorsedAt }] | ...others: seen: 'online'|'today'|'week'|'month'|'older'|null }], roles }
+  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', op, online, isZero, twinkle: { userId, username } | null, ...owner: groups, banned, protected, firstSeenAt, lastSeenAt, endorsements: [{ voucherName, voucherUuid, endorsedAt }] | ...others: seen: 'online'|'today'|'week'|'month'|'older'|null }], visitorBuilders: [{ userId, username, linkedUuids }] | null, roles }
   - Everyone who has joined the server with their in-game rank, for a player directory; the server owner also gets the full records for role management.
   - Every viewer gets the list. Only the server owner, in an app they own, gets canManage: true with full records (groups, bans, exact first/last seen); everyone else gets canManage: false and the public view: banned players left out, and seen is a rough bucket instead of exact times. Show role controls only when canManage is true.
   - Roles: visitor (play and chat), member (/tpa, /home, /back, may ask Zero to build), builder (member + /fly and creative/survival), moderator (builder + teleport others, CoreProtect rollback, /kick). op: true players are server operators and have every power regardless of role.
   - protected: true players (the owner and Zero's account) can't be changed from the app. Sorted online first, then most recently seen.
   - Not cached; call on screen open or after a change, not on a timer.
   - twinkle is the Twinkle account linked to that player with /link, or null.
+  - visitorBuilders lists approved Twinkle-only Builders and linked Minecraft UUIDs; null means unavailable. Merge by userId or linked UUID. This approval permits Zero orders and is not itself an in-game role change.
   - endorsements (owner view only) lists who backed this player's Builder application: a moderator or anyone above typed /vouch for a player already on Twinkle. voucherUuid is the voucher's Minecraft uuid (null when endorsed from the app or console); endorsedAt is an ISO time. Empty when there are none, or when the server's vouch list could not be read.
   - Example: const { canManage, people } = await Twinkle.minecraft.getPeople(); renderDirectory(people, { editable: canManage });
 - async setPlayerRole({ uuid, role }) | scopes: content:write
@@ -1652,6 +1657,7 @@ world.updatePresence({ x, y, z, facing });
   - Returns: { item: { id, key, value, updatedAt } | null }
   - Read one key from the default private per-user JSON store.
   - Reads a single key from the current viewer's private store.
+  - Read the stored value from response.item.value, not response.value or the response itself. item is null when the key is absent; a rejected read is not an empty saved value.
 - async list({ prefix, limit, cursor } = {}) | scopes: privateDb:read
   - Returns: { items: [{ id, key, value, updatedAt }], cursor? }
   - List keys from the default private per-user JSON store.
@@ -1660,6 +1666,7 @@ world.updatePresence({ x, y, z, facing });
   - Returns: { item: { id, key, value, updatedAt } }
   - Upsert one JSON-serializable value in the default private per-user store.
   - Upserts one key for the current viewer. Value must be JSON-serializable (max 16 KB).
+  - Await the write and adopt response.item.value as the confirmed saved state. Keep pending local changes separate; on failure show an unsaved state and retain the work for a deliberate retry instead of swallowing the error or incrementing a saved counter again.
 - async remove(key) | scopes: privateDb:write
   - Returns: { success: true, deleted: boolean }
   - Delete one key from the default private per-user JSON store.

package/sdk/LUMINE_ADMIN.md

@@ -5698,6 +5698,28 @@ Bridge Builder qualifies from QR check-ins: 7 different people, or one meetup a
 Every decision requires Mikey's authorization for that crew and action. Mutations are audited and idempotent; `--output <path>` is an explicit request to retain the canonical JSON. General write receipts omit private crew details.
 
 
+## Grammar Quest legacy Ghost evidence
+
+`lumine admin english quest-evidence <case.json> --json` previews one member's
+held legacy retry-evidence case. The private JSON input contains a numeric
+`userId` and `skillCode`. Compare the returned count, due-date evidence, pending
+runs and `sourceHash` with the individually reviewed history. To apply a
+`ready` preview, add its exact `sourceHash` to the same input as `expectedHash`
+and repeat with `--confirm`. A changed history refuses the request; re-read and
+review it rather than refreshing the hash blindly. The mutation and
+idempotency/audit receipt commit together. Use a stable `--idempotency-key` and
+inspect any unconfirmed outcome before retrying.
+
+The command resolves a no-effect hold or removes one proven excess below the
+Ghost threshold. With no completed or open scheduled review, it can also move
+an erroneously early due date to the reconstructed date only if that date is
+already past or today, so a due review stays available. It never increases a
+miss count or changes an answer or Ghost stage. Advanced or open/completed
+scheduled Ghost reviews, other due-date differences, incomplete history and
+unrecognized evidence remain held for individual review. The source command is
+available in this checkout; check the release receipt before assuming a
+published npm version contains it.
+
 ## Arena timed-bank item revisions
 
 Reviewed text, option and visual fixes to a published paper go live in place, without