@stage5/lumine 0.3.85 → 0.3.87

package/README.md

@@ -377,22 +377,85 @@ 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.
 
+## Previewing and testing like Lumine
+
+`lumine preview` and `lumine test` run Lumine's own preview tools
+(`view_preview` and `run_preview_test`) on Twinkle's capture browser, so
+Codex, Claude Code and Lumine check a build the same way. They are read-only:
+the capture sandbox refuses SDK writes, reward claims, notifications and paid
+app AI, nothing is saved, and no AI or Energy is used. Run them from a pulled
+workspace (they send its files, saved or not) or pass `--saved` to check the
+saved project, and `--build <id>` outside a workspace. They work on builds you
+own; on a team project, preview your own branch.
+
+```bash
+# Screenshot (saved under .twinkle/previews/ unless --out), runtime errors and
+# layout overflow. Actions run in order from the opening screen (up to 24).
+lumine preview --viewport phone --actions '[{"type":"click","x":500,"y":620},{"type":"touch","x":500,"y":700,"endX":500,"endY":300}]'
+
+# A throwaway test: inputs plus checks, each step reported.
+lumine test .twinkle/tests/map-scroll.json
+```
+
+Keep test files under `.twinkle/tests/` (or outside the workspace): anything
+among the project files is uploaded by `lumine save`.
+
+`.twinkle/tests/map-scroll.json`:
+
+```json
+{
+  "name": "world map scrolls to the status bar",
+  "viewport": "phone",
+  "steps": [
+    { "type": "click", "x": 500, "y": 620 },
+    { "type": "expect", "text": "World Map", "state": "visible" },
+    { "type": "touch", "x": 500, "y": 800, "endX": 500, "endY": 200, "durationMs": 400 },
+    { "type": "expect", "selector": "#status", "state": "in_view", "timeoutMs": 1500 },
+    { "type": "expect_value", "path": "game.screen", "op": "equals", "value": "map" },
+    { "type": "call", "module": "/rules.js", "export": "scoreWord", "args": ["CAT"], "op": "equals", "value": 3 }
+  ]
+}
+```
+
+- Inputs: `click`, `touch` (add `endX`/`endY` to drag or swipe, `durationMs`
+  to hold), `scroll` (`deltaY`), `key` (`key`), `wait` (`durationMs`).
+  Coordinates are 0-1000 across the app frame.
+- Checks: `expect` (`text` or a CSS `selector`; `state` visible, in_view,
+  present or absent; `which` any/first/last; `timeoutMs` up to 3000),
+  `expect_value` (a `path` the app keeps on `window`, `op` equals, not_equals,
+  gt, gte, lt, lte, truthy, falsy or contains, and the expected `value`; a
+  string value is read as JSON when it parses, so `"3"` means the number 3),
+  `call` (a project module's export with `args` as a list; `op` may
+  also be throws), `expect_pixels` (a region `x`,`y` to `endX`,`endY` with at
+  least `minShare` % within `tolerance` of `color` #rrggbb).
+- Up to 24 steps; a test stops at the first failed check. The result lists
+  each step as passed, done, failed, could_not_run or not_run, and `checked`
+  lists exactly what passed. A screenshot comes back only when a step fails.
+  A pass proves those checks at that moment in that browser, nothing more:
+  not saving, rewards, shared data or multiplayer.
+- Every call starts at the app's opening screen and closes the page after.
+  You get 8 looks per 10 minutes (the same budget as one Lumine run); a test
+  is one look, a preview is one look per 8 actions.
+- `--json` prints the full result; the exit code is 1 when a preview fails or
+  a test does not pass.
+
 ## Thumbnails
 
 `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.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 }] }
@@ -7489,7 +7507,7 @@ function printRewardBankReport(data) {
   );
   for (const row of data.questionsToReview.reported) {
     console.log(
-      `  reported #${row.id} (${row.reports}, ${row.status}) ${row.ruleId}/${row.topicKey} s${row.step}: ${row.reasons}`,
+      `  reported #${row.id} (${row.reports}, ${row.status}) ${row.ruleId}/${row.topicKey} s${row.step}: ${row.reasons}${typeof row.lastReportedAt === "number" ? ` · last ${new Date(row.lastReportedAt * 1000).toISOString().slice(0, 10)}${row.reportsInWindow ? ` · ${row.reportsInWindow} new in window` : " · none new"}` : ""}`,
     );
   }
   for (const row of data.questionsToReview.hardest) {

package/lib/agent/mcp-server.js

@@ -94,7 +94,10 @@ async function handleMcpMessage({ line, session, tools }) {
     const toolName = String(message?.params?.name || "");
     const toolArguments = message?.params?.arguments || {};
     try {
-      const output = await session.call(toolName, toolArguments);
+      const { output, image } = await session.callTool(
+        toolName,
+        toolArguments,
+      );
       const isError = output?.ok === false || Boolean(output?.error);
       return writeMcpResult(id, {
         content: [
@@ -102,6 +105,16 @@ async function handleMcpMessage({ line, session, tools }) {
             type: "text",
             text: JSON.stringify(output),
           },
+          // A preview screenshot, as an MCP image block in the same result.
+          ...(image?.base64
+            ? [
+                {
+                  type: "image",
+                  data: image.base64,
+                  mimeType: image.mimeType || "image/jpeg",
+                },
+              ]
+            : []),
         ],
         isError,
       });

package/lib/agent/providers/codex.js

@@ -225,16 +225,36 @@ async function runCodexAppServerTurn({
       return;
     }
     try {
-      const output = await toolSession.call(
-        message.params?.tool,
-        message.params?.arguments || {},
-      );
+      // A preview screenshot rides in the same tool result as an image item.
+      const { output, image } =
+        typeof toolSession.callTool === "function"
+          ? await toolSession.callTool(
+              message.params?.tool,
+              message.params?.arguments || {},
+            )
+          : {
+              output: await toolSession.call(
+                message.params?.tool,
+                message.params?.arguments || {},
+              ),
+              image: null,
+            };
       const success = output?.ok !== false && !output?.error;
       send({
         jsonrpc: "2.0",
         id: message.id,
         result: {
-          contentItems: [{ type: "inputText", text: JSON.stringify(output) }],
+          contentItems: [
+            { type: "inputText", text: JSON.stringify(output) },
+            ...(image?.base64
+              ? [
+                  {
+                    type: "inputImage",
+                    imageUrl: `data:${image.mimeType || "image/jpeg"};base64,${image.base64}`,
+                  },
+                ]
+              : []),
+          ],
           success,
         },
       });

package/lib/agent/tool-session.js

@@ -1,7 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { executeExternalAgentTool } from "../api.js";
+import { executeExternalAgentTool, runBuildPreviewTool } from "../api.js";
+import { PREVIEW_TOOL_TIMEOUT_MS } from "../preview.js";
 import {
   collectWorkspaceTextFilesLenient,
   resolveLocalProjectFilePath,
@@ -10,6 +11,16 @@ import {
 import { appendAgentTrace } from "./trace.js";
 
 const EXTERNAL_AGENT_MAX_TOOL_CALLS_PER_HOSTED_ROUND = 8;
+// Lumine's preview tools run on Twinkle's capture browser through POST
+// /cli/build/:id/preview-tool (the same route as lumine preview / lumine
+// test), not through /agent/tool. Each call takes one look from the member's
+// shared look quota. Twinkle keeps no page between calls, so this session
+// keeps the walk the last call recorded and sends it back: "continue"
+// replays it before the new input, exactly like a Build run after an edit.
+const EXTERNAL_AGENT_PREVIEW_TOOL_NAMES = new Set([
+  "view_preview",
+  "run_preview_test",
+]);
 
 export async function createExternalAgentToolSession({
   options,
@@ -60,16 +71,68 @@ export class ExternalAgentToolSession {
     this.provider = provider;
     this.projectFiles = projectFiles;
     this.readPaths = [];
+    this.previewWalk = null;
     this.sequence = 0;
     this.queue = Promise.resolve();
   }
 
-  call(name, toolArguments) {
+  // The tool output only (text tools and adapters without image support).
+  async call(name, toolArguments) {
+    return (await this.callTool(name, toolArguments)).output;
+  }
+
+  // { output, image }: image is a preview screenshot ({ mimeType, width,
+  // height, base64 }) for the adapter to attach to the tool result, or null.
+  callTool(name, toolArguments) {
     const pending = this.queue.then(() => this.#call(name, toolArguments));
     this.queue = pending.catch(() => undefined);
     return pending;
   }
 
+  offersPreviewTool(toolName) {
+    return (
+      EXTERNAL_AGENT_PREVIEW_TOOL_NAMES.has(toolName) &&
+      (Array.isArray(this.runtime?.tools) ? this.runtime.tools : []).some(
+        (tool) => tool?.name === toolName,
+      )
+    );
+  }
+
+  async #callPreview(toolName, toolArguments) {
+    try {
+      const result = await runBuildPreviewTool({
+        options: this.options,
+        auth: this.auth,
+        buildId: this.buildId,
+        tool: toolName,
+        arguments: toolArguments,
+        projectFiles: this.projectFiles,
+        agent: { walk: this.previewWalk },
+        timeoutMs: Math.max(
+          Number(this.options?.timeoutMs || 0),
+          PREVIEW_TOOL_TIMEOUT_MS,
+        ),
+      });
+      if (result && "walk" in result) this.previewWalk = result.walk || null;
+      return {
+        output: result?.output ?? { ok: false, error: "No preview result." },
+        image: result?.image?.base64 ? result.image : null,
+      };
+    } catch (error) {
+      // A refusal (look quota, busy, not the owner) is a tool result the
+      // model can act on, not a crash of the pass.
+      if (!error?.status) throw error;
+      return {
+        output: {
+          ok: false,
+          error: String(error.message || "The preview request failed."),
+          ...(error.data?.code ? { code: error.data.code } : {}),
+        },
+        image: null,
+      };
+    }
+  }
+
   async #call(name, toolArguments) {
     this.sequence += 1;
     const sequence = this.sequence;
@@ -98,7 +161,7 @@ export class ExternalAgentToolSession {
         ok: false,
         result: output.error,
       });
-      return output;
+      return { output, image: null };
     }
 
     const toolName = String(name || "").trim();
@@ -114,6 +177,38 @@ export class ExternalAgentToolSession {
           : [],
     });
     const startedAt = Date.now();
+    if (this.offersPreviewTool(toolName)) {
+      try {
+        const { output, image } = await this.#callPreview(
+          toolName,
+          toolArguments,
+        );
+        await appendAgentTrace(this.traceFile, {
+          type: "tool_result",
+          provider: this.provider,
+          phase: this.runtime?.phase || null,
+          sequence,
+          tool: toolName,
+          durationMs: Date.now() - startedAt,
+          ok: output?.ok !== false && !output?.error,
+          changedPaths: [],
+          result: summarizeToolResult(output),
+        });
+        return { output, image };
+      } catch (error) {
+        await appendAgentTrace(this.traceFile, {
+          type: "tool_result",
+          provider: this.provider,
+          phase: this.runtime?.phase || null,
+          sequence,
+          tool: toolName,
+          durationMs: Date.now() - startedAt,
+          ok: false,
+          error: String(error?.message || error).slice(0, 500),
+        });
+        throw error;
+      }
+    }
     const previousFiles = this.projectFiles;
     try {
       const result = await executeExternalAgentTool({
@@ -152,7 +247,7 @@ export class ExternalAgentToolSession {
         changedPaths,
         result: summarizeToolResult(output),
       });
-      return output;
+      return { output, image: null };
     } catch (error) {
       await appendAgentTrace(this.traceFile, {
         type: "tool_result",
@@ -294,8 +389,15 @@ function summarizeToolResult(output) {
     "pathsOmitted",
     "matchCount",
     "filesRead",
+    "capturesLeft",
   ]) {
     if (output[key] !== undefined) summary[key] = output[key];
   }
+  // Preview results: what happened, never the screenshot or page text.
+  if (typeof output.test?.status === "string") summary.test = output.test.status;
+  if (typeof output.interaction?.status === "string") {
+    summary.interaction = output.interaction.status;
+  }
+  if (typeof output.replay?.status === "string") summary.replay = output.replay.status;
   return Object.keys(summary).length > 0 ? summary : "completed";
 }

package/lib/api.js

@@ -246,6 +246,34 @@ export async function validateExternalAgentCandidate({
   });
 }
 
+// Lumine's view_preview / run_preview_test on Twinkle's capture browser.
+// projectFiles null previews the saved project. agent ({ walk }) is the
+// lumine agent form: Lumine's tool contract, one look per call.
+export async function runBuildPreviewTool({
+  options,
+  auth,
+  buildId,
+  tool,
+  arguments: toolArguments,
+  projectFiles,
+  agent,
+  timeoutMs,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/preview-tool`,
+    authToken: auth.token,
+    body: {
+      tool,
+      arguments: toolArguments,
+      ...(Array.isArray(projectFiles) ? { projectFiles } : {}),
+      // lumine agent: one look per call and the walk from its last call.
+      ...(agent ? { agent } : {}),
+    },
+    timeoutMs: timeoutMs || options.timeoutMs,
+  });
+}
+
 export async function loadBuildVersions({ options, auth, buildId, limit }) {
   const url = new URL(`${options.apiUrl}/cli/build/${buildId}/versions`);
   if (limit) url.searchParams.set("limit", String(limit));

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

@@ -58,6 +58,7 @@ import {
   writeAssetsManifest,
 } from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
+import { previewCommand, testCommand } from "./preview.js";
 import { rewardsCommand, reportRewardDeclaration } from "./rewards.js";
 import { cardcraftCommand } from "./cardcraft.js";
 import { chatlogCommand } from "./chatlog.js";
@@ -305,6 +306,14 @@ export async function main() {
     await thumbnailCommand(options);
     return;
   }
+  if (options.command === "preview") {
+    await previewCommand(options);
+    return;
+  }
+  if (options.command === "test") {
+    await testCommand(options);
+    return;
+  }
   if (options.command === "doctor") {
     await doctorCommand(options);
     return;
@@ -2525,6 +2534,8 @@ export function parseArgs(args) {
     "includePrefix",
     "allowSharedNetwork",
     "send",
+    // lumine preview|test --saved
+    "saved",
   ]);
   // A flag that may stand alone (true) or carry a value: `--confirm` confirms
   // an AI bucket change.
@@ -2942,10 +2953,22 @@ export function parseArgs(args) {
     assetName: raw.name ? String(raw.name) : "",
     transparent: parseBoolean(raw.transparent, false),
     out: raw.out ? String(raw.out) : "",
+    // lumine preview / lumine test (lib/preview.js)
+    previewViewport: raw.viewport ? String(raw.viewport) : "",
+    previewFocus: raw.focus ? String(raw.focus) : "",
+    previewActions: raw.actions ? String(raw.actions) : "",
+    previewSteps: raw.steps ? String(raw.steps) : "",
+    previewName: raw.name ? String(raw.name) : "",
+    previewSaved: parseBoolean(raw.saved, false),
     target:
       raw.url ||
       raw.target ||
-      (command === "rename" || command === "describe" || command === "suggest"
+      (command === "rename" ||
+      command === "describe" ||
+      command === "suggest" ||
+      // the positional is the test file; the build comes from --build or the workspace
+      command === "preview" ||
+      command === "test"
         ? ""
         : command === "suggestions"
           ? suggestionListTarget
@@ -3282,12 +3305,14 @@ export function printHelp() {
   lumine update-from-main [twinkle-branch-url]
   lumine save [--summary <text>] [--publish] [--json]
   lumine check [twinkle-build-url]
+  lumine preview [--viewport phone|desktop] [--actions <json|file>] [--focus <text>] [--out <file>] [--saved] [--build <id>] [--json]
+  lumine test <test.json> | --steps <json|file> [--viewport phone|desktop] [--name <text>] [--out <file>] [--saved] [--build <id>] [--json]
   lumine launch [twinkle-build-url]
   lumine sdk list
   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 +3326,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)
@@ -3412,7 +3437,7 @@ export function printHelp() {
   lumine admin member-trace list | on <username> --reason <why> | off <username> | [read] <username> [--since 2h|30m|3d|<iso>] [--source all|client|server] [--type reload,route,chat-select,boot,session,error,rejection,boundary-error,api] [--path <substring>] [--limit 300] [--json]   (the owner trace switched on for specific member accounts to chase a bug they report: on/off are audited admin actions and take effect within 30 s; the website side records page loads with version and bundle, routes, chat channel/subchannel selection, every self-reload with its reason (kept on the device across the reload), error screens and window errors; the API side records each request from that account with its route, status, time and the website version it reported, so a device stuck on an old cached bundle still shows; read prints a plain summary first; kept 30 days)
   lumine admin roles [--min-level 1] [--limit 50] [--json]   (every user type with its management level and who holds it; admin pages need level 3, achievement points never pass level 2)
   lumine admin jev-images report [--days 1..30] | switch --area <all|arena_paper|arena_picture|study_record|thumbnail|sdk_decide> --mode on|off [--daily-cap <0-5000>] [--build <id>, sdk_decide only, no --daily-cap] | decide --area <area> --key <subject key> --decision <decision> | thumbnails --targets <subject:<id>,build:<id>,...> | --featured [--saved-only] [--json]   (JEV image checks: advisory only; per-area health, cost, agreement with final decisions and escalations for the daily run; switch is owner-only and needs no deploy; thumbnails adds notes for Featured review and never replaces or unfeatures anything)
-  lumine admin jev-routing review --since <unix|ISO> --until <unix|ISO> [--limit 1..20] [--cursor <cursor> | --all --checkpoint <file> [--resume]] [--include-synthetic] [--json]   (bounded frozen evidence for paired disagreements and Auto fallbacks; collection is not review)
+  lumine admin jev-routing review --since <unix|ISO> --until <unix|ISO> [--limit 1..20] [--cursor <cursor> | --all --checkpoint <file> [--resume]] [--include-synthetic] [--json]   (bounded frozen evidence for paired disagreements, Auto fallbacks and self-contradictory JEV answers; collection is not review)
   lumine admin comment draft <target> [--type subject|comment|build|aiStory|dailyReflection] [--file <comment.md>] [--review-receipt <review.json>|--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment reply comment:<id> [--file <reply.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment post --draft-id <id> [--json]
@@ -3494,7 +3519,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 +3613,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
@@ -239,6 +242,25 @@ lumine save --summary "Describe the change"
 \`\`\`
 
 - Run lumine check before launch when possible.
+- See and test the app the way Lumine does, on Twinkle's own capture browser
+  (read-only: nothing is saved, no rewards, no AI, no Energy). Both use this
+  workspace's files, saved or not (--saved uses the saved project):
+  - \`lumine preview [--viewport phone|desktop] [--actions <json|file>]\`
+    saves a screenshot (path printed) plus runtime errors and layout overflow.
+    Actions: click, touch (endX/endY to drag), scroll, key, wait, with x/y
+    0-1000 across the app; up to 24, in order from the opening screen.
+  - \`lumine test .twinkle/tests/<name>.json\` runs a throwaway test
+    ({"name","viewport","steps"}; keep test files under .twinkle/tests/, never
+    among the project files, or lumine save uploads them): the same inputs plus checks (expect text or
+    a CSS selector visible/in_view/present/absent, expect_value on a path the
+    app keeps on window, call a project module's export, expect_pixels on a
+    region). It reports each step and lists exactly what passed; a screenshot
+    comes back only when a step fails. Use it before you say a fix works that a
+    screenshot cannot show (a scroll that must end somewhere, a screen several
+    taps deep, a rule in your JS). A pass proves only its listed checks: not
+    saving, rewards, shared data or multiplayer.
+  - Every call starts at the opening screen. 8 looks per 10 minutes, like one
+    Lumine run; previews run on builds you own (use your branch).
 - \`lumine versions\` lists this build's previous saves (add --main inside a
   branch workspace for the team project's main history). \`lumine pull
   --version <n>\` checks a previous save out read-only alongside the workspace
@@ -314,12 +336,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 +375,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.
@@ -458,6 +484,9 @@ export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
   "assets",
   // versions only reads save history.
   "versions",
+  // preview/test only read: the capture sandbox never saves or writes.
+  "preview",
+  "test",
 ]);
 export const COMMANDS = new Set([
   "network",
@@ -491,6 +520,8 @@ export const COMMANDS = new Set([
   "save",
   "push",
   "check",
+  "preview",
+  "test",
   "launch",
   "versions",
   "restore",

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/preview.js

@@ -0,0 +1,238 @@
+import fs from "fs/promises";
+import path from "path";
+
+import { runBuildPreviewTool } from "./api.js";
+import { ensureAuth } from "./auth.js";
+import { resolveSdkBuildId } from "./sdk.js";
+import {
+  collectProjectFiles,
+  findLocalProjectMetadata,
+  isReadOnlyReferenceMetadata,
+} from "./workspace.js";
+
+// `lumine preview` and `lumine test` run Lumine's own view_preview and
+// run_preview_test on Twinkle's capture browser (POST
+// /cli/build/:id/preview-tool), so an agent working through the CLI checks a
+// build exactly the way Lumine does in a Build run: same sandbox, same step
+// format, same results. Read-only, no AI and no Energy. Each call starts at
+// the app's opening screen and closes the page when it is done.
+
+export const PREVIEW_TOOL_TIMEOUT_MS = 330_000;
+export const PREVIEW_USAGE = `Usage:
+  lumine preview [--viewport phone|desktop] [--actions <json|file>] [--focus <text>] [--out <file>] [--saved] [--build <id>] [--json]
+  lumine test <test.json> [--viewport phone|desktop] [--name <text>] [--out <file>] [--saved] [--build <id>] [--json]
+  lumine test --steps <json|file> [--name <text>] ...
+Keep test files under .twinkle/tests/ so lumine save never uploads them.`;
+
+function usageError(message) {
+  const error = new Error(`${message}\n${PREVIEW_USAGE}`);
+  error.exitCode = 2;
+  return error;
+}
+
+// A flag value is inline JSON or a path to a JSON file.
+export async function readJsonArgument(value, label) {
+  const text = String(value || "").trim();
+  if (!text) return undefined;
+  if (/^[[{]/.test(text)) {
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw usageError(`${label} is not valid JSON: ${error.message}`);
+    }
+  }
+  let fileText;
+  try {
+    fileText = await fs.readFile(path.resolve(text), "utf8");
+  } catch (error) {
+    throw usageError(`Could not read ${label} file ${text}: ${error.code || error.message}`);
+  }
+  try {
+    return JSON.parse(fileText);
+  } catch (error) {
+    throw usageError(`${label} file ${text} is not valid JSON: ${error.message}`);
+  }
+}
+
+function normalizeViewport(value, fallback = "phone") {
+  const viewport = String(value || fallback).trim().toLowerCase();
+  if (viewport !== "phone" && viewport !== "desktop") {
+    throw usageError(`--viewport must be phone or desktop, not "${value}".`);
+  }
+  return viewport;
+}
+
+// What `lumine test` sends: a test file ({ name, viewport, steps }) or a bare
+// list of steps, with flags taking precedence.
+export async function resolveTestArguments(options) {
+  const fromFile = options.positional?.[0]
+    ? await readJsonArgument(options.positional[0], "test")
+    : undefined;
+  const fromFlag = options.previewSteps
+    ? await readJsonArgument(options.previewSteps, "--steps")
+    : undefined;
+  if (fromFile === undefined && fromFlag === undefined) {
+    throw usageError("Give a test file or --steps.");
+  }
+  const spec = Array.isArray(fromFile) ? { steps: fromFile } : fromFile || {};
+  const steps = fromFlag !== undefined
+    ? Array.isArray(fromFlag) ? fromFlag : fromFlag?.steps
+    : spec.steps;
+  if (!Array.isArray(steps) || steps.length === 0) {
+    throw usageError("A test needs a non-empty steps list.");
+  }
+  return {
+    name: String(options.previewName || spec.name || "test").slice(0, 80),
+    viewport: normalizeViewport(options.previewViewport || spec.viewport),
+    steps,
+  };
+}
+
+export async function resolvePreviewArguments(options) {
+  const actions = options.previewActions
+    ? await readJsonArgument(options.previewActions, "--actions")
+    : [];
+  const list = Array.isArray(actions) ? actions : actions?.actions;
+  if (!Array.isArray(list)) throw usageError("--actions must be a JSON list of steps.");
+  return {
+    viewport: normalizeViewport(options.previewViewport),
+    focus: options.previewFocus ? String(options.previewFocus).slice(0, 160) : null,
+    actions: list,
+  };
+}
+
+// The working files in this workspace (saved or not), or none to preview
+// the saved project. A read-only reference checkout is never sent as if it
+// were the build's own files.
+async function resolvePreviewProjectFiles(options, buildId) {
+  if (options.previewSaved) return { projectFiles: null, source: "saved" };
+  const localProject = await findLocalProjectMetadata(
+    options.dir ? path.resolve(options.dir) : process.cwd(),
+  );
+  const localBuildId = Number(localProject?.metadata?.buildId || 0);
+  if (
+    !localProject?.rootDir ||
+    localBuildId !== Number(buildId) ||
+    isReadOnlyReferenceMetadata(localProject.metadata)
+  ) {
+    return { projectFiles: null, source: "saved" };
+  }
+  const files = await collectProjectFiles(localProject.rootDir);
+  return {
+    projectFiles: files.map((file) => ({ path: file.path, content: file.content })),
+    source: "workspace",
+    rootDir: localProject.rootDir,
+  };
+}
+
+function defaultScreenshotPath({ rootDir, kind }) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const base = rootDir
+    ? path.join(rootDir, ".twinkle", "previews")
+    : process.cwd();
+  return path.join(base, `${kind}-${stamp}.jpg`);
+}
+
+async function saveScreenshot({ image, out, rootDir, kind }) {
+  if (!image?.base64) return null;
+  const target = out ? path.resolve(out) : defaultScreenshotPath({ rootDir, kind });
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.writeFile(target, Buffer.from(image.base64, "base64"));
+  return target;
+}
+
+export function formatTestReport(output) {
+  const test = output?.test;
+  if (!test) return [output?.error || "The test did not run."];
+  const icon = { passed: "PASS", done: "done", failed: "FAIL", could_not_run: "STOP", not_run: "skip" };
+  const lines = [`Test "${test.name}": ${String(test.status).toUpperCase()}`];
+  for (const step of test.steps || []) {
+    lines.push(`  ${String(step.step).padStart(2)}. [${icon[step.result] || step.result}] ${step.does}${step.observed ? ` (saw: ${step.observed})` : ""}${step.reason ? ` (${step.reason})` : ""}`);
+  }
+  if (test.meaning) lines.push(test.meaning);
+  return lines;
+}
+
+export function formatPreviewReport(output) {
+  if (output?.ok !== true) return [`Preview failed: ${output?.error || "no result"}`];
+  const lines = [];
+  const interaction = output.interaction;
+  if (interaction?.status && interaction.status !== "not_requested") {
+    lines.push(`Input: ${interaction.status}${interaction.completed !== undefined ? ` (${interaction.completed}/${interaction.requested} steps)` : ""}`);
+  }
+  if (output.walk?.steps) lines.push(`Walk: ${output.walk.steps}`);
+  const runtime = output.runtime;
+  if (runtime?.summary) lines.push(`Runtime: ${runtime.summary}`);
+  else if (Array.isArray(runtime?.issues) && runtime.issues.length) {
+    lines.push(`Runtime issues: ${runtime.issues.length}`);
+  }
+  if (output.captureBrowser?.note) lines.push(`Note: ${output.captureBrowser.note}`);
+  return lines;
+}
+
+async function runPreviewTool(options, { tool, args, kind }) {
+  const buildId = await resolveSdkBuildId(options);
+  const auth = await ensureAuth(options);
+  const files = await resolvePreviewProjectFiles(options, buildId);
+  const result = await runBuildPreviewTool({
+    options,
+    auth,
+    buildId,
+    tool,
+    arguments: args,
+    projectFiles: files.projectFiles,
+    timeoutMs: Math.max(options.timeoutMs || 0, PREVIEW_TOOL_TIMEOUT_MS),
+  });
+  const screenshot = await saveScreenshot({
+    image: result?.image,
+    out: options.out,
+    rootDir: files.rootDir,
+    kind,
+  });
+  return { buildId, files, result, screenshot };
+}
+
+function printJson({ buildId, files, result, screenshot }) {
+  console.log(JSON.stringify({
+    buildId,
+    files: files.source,
+    output: result?.output ?? null,
+    screenshot,
+    looks: result?.looks ?? null,
+    looksLeft: result?.looksLeft ?? null,
+  }, null, 2));
+}
+
+export async function previewCommand(options) {
+  if (options.help) {
+    console.log(PREVIEW_USAGE);
+    return;
+  }
+  const args = await resolvePreviewArguments(options);
+  const run = await runPreviewTool(options, { tool: "view_preview", args, kind: "preview" });
+  if (options.json) printJson(run);
+  else {
+    console.log(`Build #${run.buildId} preview (${args.viewport}, ${run.files.source === "workspace" ? "this workspace's files" : "saved files"}):`);
+    for (const line of formatPreviewReport(run.result?.output)) console.log(line);
+    if (run.screenshot) console.log(`Screenshot: ${run.screenshot}`);
+    console.log(`Looks left in this 10-minute window: ${run.result?.looksLeft ?? "?"}`);
+  }
+  if (run.result?.output?.ok !== true) process.exitCode = 1;
+}
+
+export async function testCommand(options) {
+  if (options.help) {
+    console.log(PREVIEW_USAGE);
+    return;
+  }
+  const args = await resolveTestArguments(options);
+  const run = await runPreviewTool(options, { tool: "run_preview_test", args, kind: "test-failure" });
+  if (options.json) printJson(run);
+  else {
+    console.log(`Build #${run.buildId} test (${args.viewport}, ${run.files.source === "workspace" ? "this workspace's files" : "saved files"}):`);
+    for (const line of formatTestReport(run.result?.output)) console.log(line);
+    if (run.screenshot) console.log(`Screenshot at the failed step: ${run.screenshot}`);
+    console.log(`Looks left in this 10-minute window: ${run.result?.looksLeft ?? "?"}`);
+  }
+  if (run.result?.output?.test?.status !== "passed") process.exitCode = 1;
+}

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.85",
+  "version": "0.3.87",
   "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

@@ -5633,7 +5633,7 @@ Legacy aliases such as `subjects list`, `subjects get`, `subjects featured`,
 `comments get`, and `recommend` remain accepted, but the singular command forms
 shown above are the canonical interface.
 
-For bounded case evidence, use `lumine admin jev-routing review --since <UTC-day> --until <next-UTC-day> --json` and follow every cursor, or `--all --checkpoint <persistent-file>`. Daily gather retains every20-event source page for the preceding complete UTC day. The reader covers paired disagreements and Auto fallbacks once per event; synthetic traffic is excluded unless `--include-synthetic` is explicit. It returns only currently unexpired frozen input and labels absent/expired input. A missing endpoint is unavailable coverage, not an empty healthy day. Collection never acknowledges reading or proves classification accuracy. This October28 reader and independent Auto-input capture are local until the matching release is verified.
+For bounded case evidence, use `lumine admin jev-routing review --since <UTC-day> --until <next-UTC-day> --json` and follow every cursor, or `--all --checkpoint <persistent-file>`. Daily gather retains every20-event source page for the preceding complete UTC day. The reader covers paired disagreements, Auto fallbacks and `candidate_inconsistent` events (JEV answered with fields that contradict each other, such as `lumine_turn` edit without `mutate_project`; `inconsistentFields` names them) once per event; synthetic traffic is excluded unless `--include-synthetic` is explicit. It returns only currently unexpired frozen input and labels absent/expired input. A missing endpoint is unavailable coverage, not an empty healthy day. Collection never acknowledges reading or proves classification accuracy. This October28 reader and independent Auto-input capture are local until the matching release is verified.
 
 Before calling a reply unrelated, check its original generation trigger and the bounded `askedAbout` descriptor. A member may have edited the visible turn or asked about linked content. The descriptor explicitly represents current stored metadata, not a separately frozen generation snapshot; never bypass deleted context.
 
@@ -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