@stage5/lumine 0.2.5 → 0.2.6

package/README.md

@@ -77,6 +77,32 @@ which can differ from a method's `Twinkle.*` SDK return shape — check
 `TWINKLE_BUILD_SDK.md` for SDK return shapes. Methods that change data require
 `--allow-write`.
 
+## Assets and AI image generation
+
+Binary media never lives in the workspace — assets are uploaded to Twinkle and
+referenced from code by URL. `lumine assets upload <file...>` uploads images or
+audio; `lumine assets list` prints your uploads and refreshes
+`.twinkle/assets.json`.
+
+`lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana>` creates
+an AI-generated image asset instead of uploading one. `--model` is required
+(gpt-image-2 = best quality, slower, pricier; nano-banana = Gemini, faster,
+cheaper). 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` applies to gpt-image-2 only.
+
+## 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|nano-banana>`
+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;
+pass `--yes` for non-interactive runs. Thumbnail commands are blocked in
+read-only `pull --main` checkouts.
+
 The CLI checks npm for the latest `@stage5/lumine` version on normal commands.
 If the installed copy is outdated, it prints an update warning and records the
 version state in `.twinkle/lumine-project.json` so local agents can tell when

package/lib/api.js

@@ -219,17 +219,81 @@ export async function buildApiJson({
   buildApiToken,
   endpointPath,
   body,
+  timeoutMs,
 }) {
   return requestJson({
     method: "POST",
     url: `${options.apiUrl}/build/${buildId}/${endpointPath}`,
     authToken: auth.token,
     body: body || {},
-    timeoutMs: options.timeoutMs,
+    timeoutMs: timeoutMs || options.timeoutMs,
     headers: { "x-build-api-token": buildApiToken },
   });
 }
 
+export async function requestThumbnailSignedUpload({
+  options,
+  auth,
+  buildId,
+  fileSize,
+  contentType,
+}) {
+  return requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${buildId}/thumbnail`,
+    authToken: auth.token,
+    body: { fileSize, contentType },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function updateBuildThumbnailUrl({
+  options,
+  auth,
+  buildId,
+  thumbnailUrl,
+}) {
+  return requestJson({
+    method: "PUT",
+    url: `${options.apiUrl}/build/${buildId}`,
+    authToken: auth.token,
+    body: { thumbnailUrl },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function captureBuildThumbnailPreview({
+  options,
+  auth,
+  buildId,
+  previewPath,
+  timeoutMs,
+}) {
+  return requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${buildId}/thumbnail/capture-preview`,
+    authToken: auth.token,
+    body: { previewPath },
+    timeoutMs: timeoutMs || options.timeoutMs,
+  });
+}
+
+export async function generateBuildThumbnailRequest({
+  options,
+  auth,
+  buildId,
+  body,
+  timeoutMs,
+}) {
+  return requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${buildId}/thumbnail/generate`,
+    authToken: auth.token,
+    body: body || {},
+    timeoutMs: timeoutMs || options.timeoutMs,
+  });
+}
+
 export async function fetchAllRuntimeAssets({
   options,
   auth,

package/lib/assets.js

@@ -4,9 +4,12 @@ import readline from "readline/promises";
 import { stdin as input, stdout as output } from "process";
 
 import {
+  ASSET_GENERATE_TIMEOUT_MS,
   ASSET_MIME_BY_EXTENSION,
   ASSET_UPLOAD_CHUNK_BYTES,
   ASSETS_METADATA_FILE,
+  GENERATE_MODEL_ALIASES,
+  GENERATE_QUALITIES,
   PROJECT_METADATA_DIR,
   RUNTIME_ASSET_REFERENCE_PATTERN,
 } from "./constants.js";
@@ -48,9 +51,169 @@ export async function assetsCommand(options) {
     await assetsPrune(options);
     return;
   }
+  if (subcommand === "generate") {
+    await assetsGenerate(options);
+    return;
+  }
   throw new Error(
-    "Usage: lumine assets [list] | lumine assets upload <file...> | lumine assets delete <assetId> | lumine assets prune [--yes]",
+    'Usage: lumine assets [list] | lumine assets upload <file...> | lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana> | lumine assets delete <assetId> | lumine assets prune [--yes]',
+  );
+}
+
+export function resolveGenerateModel(options) {
+  const rawModel = String(options.model || "").trim();
+  const model = GENERATE_MODEL_ALIASES[rawModel];
+  if (!model) {
+    throw new Error(
+      "--model is required: gpt-image-2 (best quality, slower, pricier) or nano-banana (Gemini — faster, cheaper). No default model is applied.",
+    );
+  }
+  const rawQuality = String(options.quality || "").trim();
+  if (rawQuality && !GENERATE_QUALITIES.has(rawQuality)) {
+    throw new Error("--quality must be low, medium, or high.");
+  }
+  if (rawQuality && model !== "gpt-image-2") {
+    throw new Error(
+      "--quality only applies to gpt-image-2; nano-banana has a single quality tier.",
+    );
+  }
+  return { model, quality: rawQuality || null };
+}
+
+export function formatBatteryPercent(energyUnits, fullBatteryUnits) {
+  const total = Number(fullBatteryUnits) || 1_000_000;
+  const percent = ((Number(energyUnits) || 0) / total) * 100;
+  if (percent <= 0) return "~0%";
+  if (percent < 1) return "<1%";
+  return `~${Math.round(percent)}%`;
+}
+
+export function describeGenerateHttpError(error) {
+  const code = String(error?.data?.code || "").trim();
+  if (error?.status === 429 && code === "ai_energy_depleted") {
+    return "Your AI battery is empty. Recharge on Twinkle or try again tomorrow.";
+  }
+  if (error?.status === 409) {
+    return "Another image generation is already running for your account — wait for it to finish, then retry.";
+  }
+  if (code === "build_runtime_file_storage_limit_exceeded") {
+    return `${error?.data?.error || "Storage quota exceeded."} Free space with \`lumine assets prune\`.`;
+  }
+  if (error?.status === 404) {
+    return "Twinkle API does not support asset generation yet (deploy the latest API first).";
+  }
+  return null;
+}
+
+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|nano-banana> [--quality low|medium|high] [--name <fileName>] [--yes]',
+    );
+  }
+  const { model, quality } = resolveGenerateModel(options);
+  const fileName = String(options.assetName || "").trim();
+  const buildId = await resolveSdkBuildId(options);
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:sdk" });
+  const { token } = await mintBuildApiToken({
+    options,
+    auth,
+    buildId,
+    scopes: ["files:read", "files:write"],
+  });
+
+  const requestBody = {
+    prompt,
+    model,
+    ...(quality ? { quality } : {}),
+    ...(fileName ? { fileName } : {}),
+  };
+
+  if (!options.assumeYes) {
+    let estimate = null;
+    try {
+      const estimateResult = await buildApiJson({
+        options,
+        auth,
+        buildId,
+        buildApiToken: token,
+        endpointPath: "api/assets/generate",
+        body: { ...requestBody, estimateOnly: true },
+      });
+      estimate = estimateResult?.estimate || null;
+    } catch (error) {
+      const friendly = describeGenerateHttpError(error);
+      if (friendly) throw new Error(friendly);
+      throw error;
+    }
+    const selectedOption = (estimate?.options || []).find(
+      (option) => option.model === model,
+    );
+    const costLine = selectedOption
+      ? `  Estimated battery cost: ${formatBatteryPercent(selectedOption.energyUnits, estimate?.fullBatteryUnits)} of a full AI battery (~$${Number(selectedOption.estimatedUsd || 0).toFixed(2)})`
+      : "  Estimated battery cost: unavailable";
+    const remainingLine = estimate
+      ? `  Battery remaining now:  ${formatBatteryPercent(estimate.energyRemaining, estimate.fullBatteryUnits)}`
+      : "";
+    console.log(
+      `Generate 1 image with ${model}${quality ? ` (quality ${quality})` : ""}?`,
+    );
+    console.log(costLine);
+    if (remainingLine) console.log(remainingLine);
+    const confirmed = await confirmPrompt("Proceed? [y/N] ");
+    if (confirmed === null) {
+      console.log("Not a TTY — re-run with --yes to generate.");
+      return;
+    }
+    if (!confirmed) {
+      console.log("Aborted. Nothing generated.");
+      return;
+    }
+  }
+
+  console.log("Generating image... this can take a minute.");
+  let result;
+  try {
+    result = await buildApiJson({
+      options,
+      auth,
+      buildId,
+      buildApiToken: token,
+      endpointPath: "api/assets/generate",
+      body: requestBody,
+      timeoutMs: ASSET_GENERATE_TIMEOUT_MS,
+    });
+  } catch (error) {
+    const friendly = describeGenerateHttpError(error);
+    if (friendly) throw new Error(friendly);
+    throw error;
+  }
+  const asset = result?.asset;
+  if (!asset?.url) {
+    throw new Error("Generation finished but no asset was returned.");
+  }
+  console.log(
+    `Generated ${asset.originalFileName || asset.fileName} (${formatBytes(asset.sizeBytes)}) as asset #${asset.id}`,
   );
+  console.log(`  ${asset.url}`);
+  const remaining = result?.aiUsagePolicy?.energyRemaining;
+  if (Number.isFinite(Number(remaining))) {
+    console.log(
+      `Battery remaining: ${formatBatteryPercent(Number(remaining), result?.aiUsagePolicy?.fullBatteryUnits)}`,
+    );
+  }
+  console.log(
+    "Reference this URL from your project files (e.g. a src/assets.js module).",
+  );
+  await refreshWorkspaceAssetsManifest({
+    options,
+    auth,
+    buildId,
+    buildApiToken: token,
+  });
+  return asset;
 }
 
 export async function assetsList(options) {

package/lib/commands.js

@@ -38,6 +38,7 @@ import {
   saveProjectFiles,
 } from "./api.js";
 import { assetsCommand, writeAssetsManifest } from "./assets.js";
+import { thumbnailCommand } from "./thumbnail.js";
 import {
   assertAuthScope,
   ensureAuth,
@@ -171,6 +172,10 @@ export async function main() {
     await assetsCommand(options);
     return;
   }
+  if (options.command === "thumbnail") {
+    await thumbnailCommand(options);
+    return;
+  }
 
   printHelp();
 }
@@ -1233,6 +1238,10 @@ export function parseArgs(args) {
       .map((scope) => scope.trim())
       .filter(Boolean),
     buildIdFlag: raw.build ? String(raw.build) : "",
+    model: raw.model ? String(raw.model) : "",
+    quality: raw.quality ? String(raw.quality) : "",
+    assetName: raw.name ? String(raw.name) : "",
+    out: raw.out ? String(raw.out) : "",
     target: raw.url || raw.target || positional[0] || "",
     title:
       String(
@@ -1437,8 +1446,12 @@ export function printHelp() {
   lumine sdk call <namespace.method> [jsonArgs]
   lumine assets [list]
   lumine assets upload <file...>
+  lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana>
   lumine assets delete <assetId>
   lumine assets prune [--yes]
+  lumine thumbnail set <file>
+  lumine thumbnail capture [--out <file>]
+  lumine thumbnail generate ["<prompt>"] --model <gpt-image-2|nano-banana>
 
 Examples:
   npx @stage5/lumine@latest
@@ -1462,6 +1475,10 @@ Examples:
   npx @stage5/lumine@latest sdk call aiStories.list '{"difficulty": 1}' --repeat 5
   npx @stage5/lumine@latest assets upload art/hero.png sounds/theme.mp3
   npx @stage5/lumine@latest assets list --build 917
+  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
 
 Options:
   --api-url <url>       Twinkle API origin
@@ -1481,11 +1498,15 @@ Options:
   --limit <number>      Number of projects to show
   --no-update-check     Skip the npm latest-version check
   --no-open             Print the approval URL without opening a browser
-  --build <id>          Build id for sdk/assets calls outside a workspace
+  --build <id>          Build id for sdk/assets/thumbnail calls outside a workspace
   --repeat <n>          Repeat an sdk call (1-20) and print latency stats
   --allow-write         Permit sdk methods that mutate app data
   --path <api/...>      Call an sdk endpoint not in the curated list
   --scopes <a,b>        Override requested build API token scopes
-  --yes                 Skip the confirmation prompt (assets prune)
+  --model <model>       Image model for generate: gpt-image-2 or nano-banana (required, no default)
+  --quality <q>         gpt-image-2 quality: low, medium, high (default high)
+  --name <fileName>     File name hint for a generated asset
+  --out <path>          With thumbnail capture: also save the capture locally
+  --yes                 Skip confirmation prompts (assets prune/generate, thumbnail)
 `);
 }

package/lib/constants.js

@@ -10,6 +10,25 @@ export const DEFAULT_AUTH_FILE = path.join(
   "lumine-cli-auth.json",
 );
 export const DEFAULT_TIMEOUT_MS = 20000;
+// Image generation runs a multi-minute provider call; thumbnail capture runs a
+// headless browser server-side. Both need per-call timeouts far above the
+// 20s default.
+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": "gpt-image-2",
+  "nano-banana": "gemini-3-pro-image-preview",
+  "gemini-3-pro-image-preview": "gemini-3-pro-image-preview",
+};
+export const GENERATE_QUALITIES = new Set(["low", "medium", "high"]);
+// Server accepts only these thumbnail content types (8MB max).
+export const THUMBNAIL_CONTENT_TYPE_BY_EXTENSION = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+};
+export const THUMBNAIL_MAX_FILE_SIZE_BYTES = 8 * 1024 * 1024;
 export const UPDATE_CHECK_TIMEOUT_MS = 1500;
 export const DEFAULT_PROJECT_LIMIT = 50;
 export const PROJECT_METADATA_DIR = ".twinkle";
@@ -152,6 +171,26 @@ 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>\` creates
+  an AI-generated image asset. --model is REQUIRED (no default): gpt-image-2 is
+  best quality but slower and pricier; nano-banana (Gemini) is faster and
+  cheaper. 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),
+  --name <fileName>. The asset lands in .twinkle/${ASSETS_METADATA_FILE} like an upload.
+
+## Thumbnail
+
+- \`lumine thumbnail set <file>\` uploads a jpg/png/webp (max 8MB) as the
+  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>\`
+  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.
+- Never run thumbnail commands from a read-only \`pull --main\` checkout; use
+  your contribution-branch workspace or an owned build.
 
 ## Project File Limits
 
@@ -252,5 +291,6 @@ export const COMMANDS = new Set([
   "launch",
   "sdk",
   "assets",
+  "thumbnail",
   "help",
 ]);

package/lib/thumbnail.js

@@ -0,0 +1,330 @@
+import fs from "fs/promises";
+import path from "path";
+
+import {
+  ASSET_GENERATE_TIMEOUT_MS,
+  THUMBNAIL_CAPTURE_TIMEOUT_MS,
+  THUMBNAIL_CONTENT_TYPE_BY_EXTENSION,
+  THUMBNAIL_MAX_FILE_SIZE_BYTES,
+} from "./constants.js";
+import {
+  captureBuildThumbnailPreview,
+  generateBuildThumbnailRequest,
+  loadBuildFiles,
+  mintBuildApiToken,
+  requestThumbnailSignedUpload,
+  updateBuildThumbnailUrl,
+} from "./api.js";
+import { assertAuthScope, ensureAuth } from "./auth.js";
+import { resolveSdkBuildId } from "./sdk.js";
+import {
+  confirmPrompt,
+  describeGenerateHttpError,
+  formatBatteryPercent,
+  putAssetPartWithRetry,
+  resolveGenerateModel,
+} from "./assets.js";
+import { formatBytes } from "./util.js";
+import { findLocalProjectMetadata } from "./workspace.js";
+
+export async function thumbnailCommand(options) {
+  const subcommand = String(options.positional[0] || "");
+  if (subcommand === "set") {
+    await thumbnailSet(options);
+    return;
+  }
+  if (subcommand === "capture") {
+    await thumbnailCapture(options);
+    return;
+  }
+  if (subcommand === "generate") {
+    await thumbnailGenerate(options);
+    return;
+  }
+  throw new Error(
+    'Usage: lumine thumbnail set <file> | lumine thumbnail capture [--out <file>] | lumine thumbnail generate "<prompt>" --model <gpt-image-2|nano-banana>',
+  );
+}
+
+async function refuseMainCheckout(options) {
+  const local = await findLocalProjectMetadata(
+    options.dir ? path.resolve(options.dir) : process.cwd(),
+  );
+  if (local?.metadata?.mainCheckout === true && !options.buildIdFlag) {
+    throw new Error(
+      "This is a read-only main checkout. Set the thumbnail from your contribution-branch workspace (or pass --build for a build you own).",
+    );
+  }
+}
+
+async function resolveThumbnailContext(options) {
+  await refuseMainCheckout(options);
+  const buildId = await resolveSdkBuildId(options);
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const metadata = await loadBuildFiles({
+    options,
+    auth,
+    buildId,
+    includeContent: false,
+  });
+  const build = metadata?.build || {};
+  if (build.canWrite === false) {
+    throw new Error(
+      `You cannot write to Build #${buildId}. Thumbnails can only be set on builds/branches you can save.`,
+    );
+  }
+  return { buildId, auth, build };
+}
+
+async function confirmThumbnailOverwrite({ options, build, buildId }) {
+  if (options.assumeYes) return true;
+  if (!String(build?.thumbnailUrl || "").trim()) return true;
+  const confirmed = await confirmPrompt(
+    `Build #${buildId} already has a thumbnail. Replace it? [y/N] `,
+  );
+  if (confirmed === null) {
+    console.log("Not a TTY — re-run with --yes to replace the thumbnail.");
+    return false;
+  }
+  if (!confirmed) {
+    console.log("Aborted. Thumbnail unchanged.");
+    return false;
+  }
+  return true;
+}
+
+export async function commitThumbnailImage({
+  options,
+  auth,
+  buildId,
+  buffer,
+  contentType,
+}) {
+  const { signedRequest, thumbnailUrl } = await requestThumbnailSignedUpload({
+    options,
+    auth,
+    buildId,
+    fileSize: buffer.length,
+    contentType,
+  });
+  if (!signedRequest || !thumbnailUrl) {
+    throw new Error("The server did not return a thumbnail upload URL.");
+  }
+  await putAssetPartWithRetry({
+    url: signedRequest,
+    chunk: buffer,
+    mimeType: contentType,
+    partLabel: "thumbnail",
+  });
+  const result = await updateBuildThumbnailUrl({
+    options,
+    auth,
+    buildId,
+    thumbnailUrl,
+  });
+  if (result?.success !== true) {
+    throw new Error(result?.error || "Failed to save the thumbnail.");
+  }
+  return { thumbnailUrl, build: result.build || null };
+}
+
+export async function thumbnailSet(options) {
+  const filePath = String(options.positional[1] || "").trim();
+  if (!filePath) {
+    throw new Error("Usage: lumine thumbnail set <file> (jpg, png, or webp)");
+  }
+  const absolutePath = path.resolve(filePath);
+  const extension = path.extname(absolutePath).toLowerCase();
+  const contentType = THUMBNAIL_CONTENT_TYPE_BY_EXTENSION[extension];
+  if (!contentType) {
+    throw new Error(
+      `Unsupported thumbnail type for ${path.basename(absolutePath)}. Thumbnails support ${Object.keys(THUMBNAIL_CONTENT_TYPE_BY_EXTENSION).join(", ")}.`,
+    );
+  }
+  let buffer;
+  try {
+    buffer = await fs.readFile(absolutePath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`Thumbnail file does not exist: ${filePath}`);
+    }
+    throw error;
+  }
+  if (!buffer.length) {
+    throw new Error(`Thumbnail file is empty: ${filePath}`);
+  }
+  if (buffer.length > THUMBNAIL_MAX_FILE_SIZE_BYTES) {
+    throw new Error(
+      `Thumbnail file is too big (${formatBytes(buffer.length)}; max ${formatBytes(THUMBNAIL_MAX_FILE_SIZE_BYTES)}).`,
+    );
+  }
+
+  const { buildId, auth, build } = await resolveThumbnailContext(options);
+  const proceed = await confirmThumbnailOverwrite({ options, build, buildId });
+  if (!proceed) return;
+
+  const { thumbnailUrl } = await commitThumbnailImage({
+    options,
+    auth,
+    buildId,
+    buffer,
+    contentType,
+  });
+  console.log(`Thumbnail set for Build #${buildId}:`);
+  console.log(`  ${thumbnailUrl}`);
+  console.log("Tip: thumbnails display ~16:9; the image was uploaded uncropped.");
+}
+
+function decodeImageDataUrl(dataUrl) {
+  const match = String(dataUrl || "").match(
+    /^data:(image\/[a-z+.-]+);base64,(.+)$/i,
+  );
+  if (!match) return null;
+  return {
+    contentType: match[1].toLowerCase(),
+    buffer: Buffer.from(match[2], "base64"),
+  };
+}
+
+export async function thumbnailCapture(options) {
+  const { buildId, auth, build } = await resolveThumbnailContext(options);
+  await assertAuthScope({ options, auth, scope: "build:sdk" });
+  const proceed = await confirmThumbnailOverwrite({ options, build, buildId });
+  if (!proceed) return;
+
+  const { token: previewToken } = await mintBuildApiToken({
+    options,
+    auth,
+    buildId,
+    scopes: ["preview:read"],
+  });
+  const previewPath = `/build/preview/build/${buildId}/current?rev=${Number(build.updatedAt || 0)}&buildApiToken=${encodeURIComponent(previewToken)}`;
+
+  console.log("Capturing the app preview server-side... this can take ~30s.");
+  const captureResult = await captureBuildThumbnailPreview({
+    options,
+    auth,
+    buildId,
+    previewPath,
+    timeoutMs: THUMBNAIL_CAPTURE_TIMEOUT_MS,
+  });
+  const decoded = decodeImageDataUrl(captureResult?.imageUrl);
+  if (!decoded) {
+    throw new Error(
+      captureResult?.error || "Preview capture returned no image.",
+    );
+  }
+  if (decoded.buffer.length > THUMBNAIL_MAX_FILE_SIZE_BYTES) {
+    throw new Error("Captured image exceeds the 8MB thumbnail limit.");
+  }
+  if (options.out) {
+    const outPath = path.resolve(String(options.out));
+    await fs.writeFile(outPath, decoded.buffer);
+    console.log(`Saved capture to ${outPath}`);
+  }
+  const normalizedContentType = THUMBNAIL_CONTENT_TYPE_BY_EXTENSION[
+    `.${decoded.contentType.split("/")[1] || "png"}`
+  ]
+    ? decoded.contentType
+    : "image/png";
+  const { thumbnailUrl } = await commitThumbnailImage({
+    options,
+    auth,
+    buildId,
+    buffer: decoded.buffer,
+    contentType: normalizedContentType,
+  });
+  console.log(`Thumbnail captured and set for Build #${buildId}:`);
+  console.log(`  ${thumbnailUrl}`);
+}
+
+export async function thumbnailGenerate(options) {
+  const prompt = String(options.positional[1] || "").trim();
+  const { model, quality } = resolveGenerateModel(options);
+  const { buildId, auth, build } = await resolveThumbnailContext(options);
+
+  const requestBody = {
+    model,
+    ...(quality ? { quality } : {}),
+    ...(prompt ? { prompt } : {}),
+  };
+
+  if (!options.assumeYes) {
+    let estimate = null;
+    try {
+      const estimateResult = await generateBuildThumbnailRequest({
+        options,
+        auth,
+        buildId,
+        body: { ...requestBody, estimateOnly: true },
+      });
+      estimate = estimateResult?.estimate || null;
+    } catch (error) {
+      const friendly = describeGenerateHttpError(error);
+      if (friendly) throw new Error(friendly);
+      throw error;
+    }
+    const selectedOption = (estimate?.options || []).find(
+      (option) => option.model === model,
+    );
+    console.log(
+      `Generate a thumbnail with ${model}${quality ? ` (quality ${quality})` : ""}${prompt ? "" : " (prompt auto-composed from the build title/description)"}?`,
+    );
+    if (String(build?.thumbnailUrl || "").trim()) {
+      console.log("  This will REPLACE the existing thumbnail.");
+    }
+    if (selectedOption) {
+      console.log(
+        `  Estimated battery cost: ${formatBatteryPercent(selectedOption.energyUnits, estimate?.fullBatteryUnits)} of a full AI battery (~$${Number(selectedOption.estimatedUsd || 0).toFixed(2)})`,
+      );
+    }
+    if (estimate) {
+      console.log(
+        `  Battery remaining now:  ${formatBatteryPercent(estimate.energyRemaining, estimate.fullBatteryUnits)}`,
+      );
+    }
+    const confirmed = await confirmPrompt("Proceed? [y/N] ");
+    if (confirmed === null) {
+      console.log("Not a TTY — re-run with --yes to generate.");
+      return;
+    }
+    if (!confirmed) {
+      console.log("Aborted. Nothing generated.");
+      return;
+    }
+  }
+
+  console.log("Generating the thumbnail... this can take a minute.");
+  let result;
+  try {
+    result = await generateBuildThumbnailRequest({
+      options,
+      auth,
+      buildId,
+      body: requestBody,
+      timeoutMs: ASSET_GENERATE_TIMEOUT_MS,
+    });
+  } catch (error) {
+    const friendly = describeGenerateHttpError(error);
+    if (friendly) throw new Error(friendly);
+    throw error;
+  }
+  if (result?.success !== true || !result?.thumbnailUrl) {
+    throw new Error(result?.error || "Thumbnail generation failed.");
+  }
+  console.log(`Thumbnail generated and set for Build #${buildId}:`);
+  console.log(`  ${result.thumbnailUrl}`);
+  if (result?.asset?.url) {
+    console.log(
+      `The generated image is also stored as reusable asset #${result.asset.id}:`,
+    );
+    console.log(`  ${result.asset.url}`);
+  }
+  const remaining = result?.aiUsagePolicy?.energyRemaining;
+  if (Number.isFinite(Number(remaining))) {
+    console.log(
+      `Battery remaining: ${formatBatteryPercent(Number(remaining), result?.aiUsagePolicy?.fullBatteryUnits)}`,
+    );
+  }
+}

package/package.json

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