@stage5/lumine 0.2.5 → 0.2.7

package/lib/commands.js

@@ -14,6 +14,8 @@ import {
   DEFAULT_TIMEOUT_MS,
   LUMINE_MAIN_CHECKOUT_INSTRUCTIONS,
   LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER,
+  LUMINE_VERSION_CHECKOUT_INSTRUCTIONS,
+  LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER,
   MAIN_CHECKOUT_READONLY_COMMANDS,
   PROJECT_METADATA_DIR,
   SDK_REFERENCE_FILE,
@@ -26,6 +28,8 @@ import {
   listOpenSourceBuilds,
   loadBuildFiles,
   loadBuildMetadata,
+  loadBuildVersionFiles,
+  loadBuildVersions,
   loadContributionDiff,
   loadLumineCliVersionInfo,
   loadOpenSourceBuildFiles,
@@ -38,6 +42,7 @@ import {
   saveProjectFiles,
 } from "./api.js";
 import { assetsCommand, writeAssetsManifest } from "./assets.js";
+import { thumbnailCommand } from "./thumbnail.js";
 import {
   assertAuthScope,
   ensureAuth,
@@ -52,10 +57,12 @@ import { sdkCommand } from "./sdk.js";
 import {
   defaultMainCheckoutDir,
   defaultReferenceDir,
+  defaultVersionCheckoutDir,
   defaultWorkspaceDir,
   parseBoolean,
   resolveBuildId,
   resolveBuildReference,
+  resolveRequiredBuildId,
   shellQuote,
   toCamelCase,
   trimTrailingSlash,
@@ -74,6 +81,7 @@ import {
   writeInstructionFiles,
   writeMainCheckoutMetadata,
   writeProjectFiles,
+  writeVersionCheckoutMetadata,
   writeProjectMetadata,
   writeReferenceInstructions,
   writeReferenceMetadata,
@@ -159,6 +167,14 @@ export async function main() {
     await check(options);
     return;
   }
+  if (options.command === "versions") {
+    await versionsCommand(options);
+    return;
+  }
+  if (options.command === "restore") {
+    await restoreVersion(options);
+    return;
+  }
   if (options.command === "launch") {
     await launch(options);
     return;
@@ -171,6 +187,10 @@ export async function main() {
     await assetsCommand(options);
     return;
   }
+  if (options.command === "thumbnail") {
+    await thumbnailCommand(options);
+    return;
+  }
 
   printHelp();
 }
@@ -245,6 +265,11 @@ export async function selectProject(options) {
 }
 
 export async function pull(options) {
+  if (options.versionProvided && !(options.pullVersion > 0)) {
+    throw new Error(
+      "Pass a save number: `lumine pull --version <n>` (run `lumine versions` to see save numbers).",
+    );
+  }
   const auth = await resolveAuth(options);
   const localProject = await findLocalProjectMetadata(
     path.resolve(options.dir || process.cwd()),
@@ -259,6 +284,10 @@ export async function pull(options) {
     auth,
     buildId: requestedBuildId,
   });
+  if (options.pullVersion > 0) {
+    await pullVersionBuildFiles({ options, auth, build: selectedBuild });
+    return;
+  }
   if (options.pullMain) {
     await pullMainBuildFiles({ options, auth, build: selectedBuild });
     return;
@@ -676,6 +705,18 @@ export function shouldUseContributionBranch(build) {
   );
 }
 
+// A canonical team build the viewer contributes to: plain pull/restore would
+// switch to their contribution branch, so version-history follow-up commands
+// for THIS build's history need --main. An owner's canonical build is their
+// editable workspace and never needs it.
+export function isCollaboratorMainBuild(build) {
+  return (
+    build?.role === "collaborator" &&
+    build.canWrite !== true &&
+    !Number(build?.contributionRootBuildId || 0)
+  );
+}
+
 export async function ensureDefaultContributionBranch({ options, auth, build }) {
   const rootBuildId =
     Number(build?.contributionRootBuildId || 0) || Number(build?.id || 0);
@@ -914,6 +955,269 @@ export async function pullMainBuildFiles({ options, auth, build }) {
   );
 }
 
+// Read-only checkout of ONE previous save (`lumine pull --version <n>`).
+// Without --main it targets the build the workspace edits (your branch on team
+// projects); with --main it targets the team project's main history.
+export async function pullVersionBuildFiles({ options, auth, build }) {
+  const versionNumber = options.pullVersion;
+  let targetBuild = build;
+  if (options.pullMain) {
+    const rootBuildId =
+      Number(build?.contributionRootBuildId || 0) || Number(build?.id || 0);
+    targetBuild =
+      rootBuildId === Number(build?.id || 0)
+        ? build
+        : await loadBuildMetadata({ options, auth, buildId: rootBuildId });
+  } else {
+    targetBuild = await resolveEditableWorkspaceBuild({
+      options,
+      auth,
+      build,
+    });
+  }
+  const buildId = Number(targetBuild?.id || 0);
+  const result = await loadBuildVersionFiles({
+    options,
+    auth,
+    buildId,
+    versionNumber,
+  });
+  const resolvedBuild = result.build || targetBuild;
+  const version = result.version || { version: versionNumber };
+  const files = Array.isArray(result.projectFiles) ? result.projectFiles : [];
+  // Same nesting rules as a main checkout: never create a version checkout
+  // inside another Lumine workspace; re-pulling the same checkout refreshes it
+  // in place.
+  const enclosing = options.dir
+    ? null
+    : await findLocalProjectMetadata(process.cwd());
+  const enclosingIsThisCheckout =
+    enclosing?.metadata?.versionCheckout === true &&
+    Number(enclosing.metadata.buildId || 0) === buildId &&
+    Number(enclosing.metadata.checkoutVersion || 0) ===
+      Number(version.version || 0);
+  const dirName = defaultVersionCheckoutDir(resolvedBuild, version.version);
+  const dir = path.resolve(
+    options.dir ||
+      (enclosingIsThisCheckout
+        ? enclosing.rootDir
+        : enclosing
+          ? path.join(path.dirname(enclosing.rootDir), dirName)
+          : dirName),
+  );
+  await writeProjectFiles({ dir, files });
+  if (files.some((file) => isIndexHtmlPath(String(file.path)))) {
+    await removeLocalProjectFilesNotIn({ dir, files });
+  }
+  await writeInstructionFiles({
+    dir,
+    marker: LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER,
+    content: LUMINE_VERSION_CHECKOUT_INSTRUCTIONS,
+  });
+  await writeSdkReference({ dir });
+  await writeVersionCheckoutMetadata({
+    dir,
+    options,
+    build: resolvedBuild,
+    manifest: result.projectManifest || null,
+    version,
+    pulledAt: new Date().toISOString(),
+  });
+  const summaryText = version.summary ? ` — "${version.summary}"` : "";
+  console.log(
+    `Pulled save v${version.version} of ${formatBuildTitle(resolvedBuild)} (read-only)${summaryText}`,
+  );
+  console.log(
+    `Pulled ${files.length} file${files.length === 1 ? "" : "s"} to ${dir}`,
+  );
+  console.log(
+    isCollaboratorMainBuild(resolvedBuild)
+      ? `Restore it with \`lumine restore ${version.version} --main\` from your branch workspace, then \`lumine save\`.`
+      : `Restore it with \`lumine restore ${version.version}\` from Build ${buildId}'s editable workspace, then \`lumine save\`.`,
+  );
+}
+
+// List a build's previous saves (every workspace/CLI save creates one).
+// Targets the SAME build `lumine pull --version <n>` would snapshot, so the
+// listed numbers and the printed follow-up commands always agree: without
+// --main that's the editable workspace build (a collaborator's branch on team
+// projects), with --main the team project's main.
+export async function versionsCommand(options) {
+  const auth = await resolveAuth(options);
+  const localProject = await findLocalProjectMetadata(
+    path.resolve(options.dir || process.cwd()),
+  );
+  const requestedBuildId = options.buildIdFlag
+    ? resolveRequiredBuildId(options.buildIdFlag)
+    : await resolveRequiredBuildIdOrSelected(options, auth, { localProject });
+  const requestedBuild = await loadBuildMetadata({
+    options,
+    auth,
+    buildId: requestedBuildId,
+  });
+  // Standing in a read-only checkout (pull --main / pull --version), the
+  // resolved id IS the build being looked at — don't bounce it to the
+  // viewer's contribution branch.
+  const resolvedFromReadOnlyCheckout =
+    !options.buildIdFlag &&
+    !(resolveBuildReference(options.target).buildId > 0) &&
+    (localProject?.metadata?.mainCheckout === true ||
+      localProject?.metadata?.versionCheckout === true);
+  let buildId = requestedBuildId;
+  if (options.pullMain) {
+    buildId =
+      Number(requestedBuild?.contributionRootBuildId || 0) || requestedBuildId;
+  } else if (!resolvedFromReadOnlyCheckout) {
+    const editableBuild = await resolveEditableWorkspaceBuild({
+      options,
+      auth,
+      build: requestedBuild,
+    });
+    buildId = Number(editableBuild?.id || 0) || requestedBuildId;
+  }
+  const result = await loadBuildVersions({
+    options,
+    auth,
+    buildId,
+    limit: options.limit,
+  });
+  printVersionList({ result });
+}
+
+export function printVersionList({ result }) {
+  const build = result.build || {};
+  const versions = Array.isArray(result.versions) ? result.versions : [];
+  if (!versions.length) {
+    console.log(`No previous saves found for ${formatBuildTitle(build)}.`);
+    return;
+  }
+  console.log(
+    `Previous saves for ${formatBuildTitle(build)} (newest first):`,
+  );
+  for (const version of versions) {
+    const author =
+      version.createdByUsername ||
+      (version.createdByRole === "assistant" ? "Lumine" : null) ||
+      version.createdByRole ||
+      "unknown";
+    const fileText =
+      Number(version.fileCount || 0) > 0
+        ? `${version.fileCount} file${Number(version.fileCount) === 1 ? "" : "s"}`
+        : "single-file save";
+    const summaryText = version.summary ? ` — ${version.summary}` : "";
+    console.log(
+      `  v${version.version}  ${formatVersionTimestamp(version.createdAt)}  by ${author}  (${fileText})${summaryText}`,
+    );
+  }
+  // The follow-up commands must hit exactly the history that was just listed,
+  // regardless of where the user runs them or which flags produced this list.
+  // Embedding the listed build id makes pull workspace-independent; --main is
+  // needed only when the listed build is a canonical team build the viewer
+  // contributes to (plain pull/restore would switch to their branch — mirrors
+  // shouldUseContributionBranch). An owner's canonical build never needs
+  // --main: it IS their editable workspace.
+  const listedBuildId = Number(build.id || 0);
+  const collaboratorMain = isCollaboratorMainBuild(build);
+  const pullTarget = listedBuildId ? ` ${listedBuildId}` : "";
+  console.log(
+    `View one read-only: lumine pull${pullTarget} --version <n>${collaboratorMain ? " --main" : ""}`,
+  );
+  console.log(
+    collaboratorMain
+      ? `Bring one back: lumine restore <n> --main (run from your branch workspace; then lumine save)`
+      : `Bring one back: lumine restore <n> (run from ${listedBuildId ? `Build ${listedBuildId}'s` : "the build's"} editable workspace; then lumine save)`,
+  );
+}
+
+function formatVersionTimestamp(seconds) {
+  const timestamp = Number(seconds || 0);
+  if (!timestamp) return "unknown time";
+  const date = new Date(timestamp * 1000);
+  const pad = (value) => String(value).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+// Write a previous save's files into the CURRENT editable workspace. Local
+// only on purpose: the user reviews the result and `lumine save` makes it a
+// new version (nothing on the server is rewritten in place). With --main in a
+// branch workspace, the save is read from the team project's MAIN history —
+// the recovery path when work was lost on main itself.
+export async function restoreVersion(options) {
+  // Same strictness as `pull --version`: only a plain positive integer may
+  // reach the workspace-overwriting path below. "2.5" must error, not
+  // silently restore v2.
+  const rawInput = String(options.positional[0] ?? "").trim();
+  let versionNumber = 0;
+  if (rawInput) {
+    if (!/^\d+$/.test(rawInput)) {
+      throw new Error(
+        "Pass a plain save number, e.g. `lumine restore 41` (see `lumine versions`).",
+      );
+    }
+    versionNumber = parseInt(rawInput, 10);
+  } else if (options.pullVersion > 0) {
+    // --version <n>, already strict-parsed by parseArgs.
+    versionNumber = options.pullVersion;
+  } else if (options.versionProvided) {
+    throw new Error(
+      "Pass a plain save number, e.g. `lumine restore 41` (see `lumine versions`).",
+    );
+  }
+  if (!(versionNumber > 0)) {
+    throw new Error(
+      "Pass the save number to restore, e.g. `lumine restore 41` (see `lumine versions`).",
+    );
+  }
+  const auth = await resolveAuth(options);
+  const localProject = await findLocalProjectMetadata(
+    path.resolve(options.dir || process.cwd()),
+  );
+  if (!Number(localProject?.metadata?.buildId || 0)) {
+    throw new Error(
+      "Run `lumine restore` inside a pulled Lumine workspace (or pass --dir <workspace>).",
+    );
+  }
+  assertLocalProjectCanBeSaved(localProject);
+  const workspaceBuildId = Number(localProject.metadata.buildId);
+  let sourceBuildId = workspaceBuildId;
+  if (options.pullMain) {
+    const rootBuildId = Number(
+      localProject.metadata.build?.contributionRootBuildId || 0,
+    );
+    if (!rootBuildId) {
+      throw new Error(
+        "--main restores from the team project's main history, which needs a contribution-branch workspace.",
+      );
+    }
+    sourceBuildId = rootBuildId;
+  }
+  const result = await loadBuildVersionFiles({
+    options,
+    auth,
+    buildId: sourceBuildId,
+    versionNumber,
+  });
+  const files = Array.isArray(result.projectFiles) ? result.projectFiles : [];
+  if (!files.length) {
+    throw new Error(`Save v${versionNumber} has no files to restore.`);
+  }
+  const dir = resolveProjectDirForSave({ options, localProject });
+  await writeProjectFiles({ dir, files });
+  if (files.some((file) => isIndexHtmlPath(String(file.path)))) {
+    await removeLocalProjectFilesNotIn({ dir, files });
+  }
+  const version = result.version || { version: versionNumber };
+  const sourceBuild = result.build || { id: sourceBuildId };
+  const summaryText = version.summary ? ` ("${version.summary}")` : "";
+  console.log(
+    `Restored ${files.length} file${files.length === 1 ? "" : "s"} from ${formatBuildTitle(sourceBuild)} save v${version.version}${summaryText} into ${dir}`,
+  );
+  console.log("Local only so far — review the files, then run:");
+  console.log(
+    `  lumine save --summary ${shellQuote(`Restore from ${options.pullMain ? "main " : ""}v${version.version}`)}`,
+  );
+}
+
 export function printBuildList(builds) {
   if (!builds.length) {
     console.log("No owned or team Twinkle builds found.");
@@ -1233,6 +1537,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(
@@ -1277,6 +1585,14 @@ export function parseArgs(args) {
     clientName: String(raw.clientName || "Lumine CLI").slice(0, 120),
     dir: raw.dir ? String(raw.dir) : "",
     pullMain: parseBoolean(raw.main, false),
+    // Strict: only a plain positive integer counts. Anything else (missing
+    // value, "foo", a swallowed flag like "--main", "2.5") stays 0 and the
+    // consuming command must reject it via versionProvided instead of
+    // silently falling back to a live pull.
+    versionProvided: Object.prototype.hasOwnProperty.call(raw, "version"),
+    pullVersion: /^\d+$/.test(String(raw.version ?? "").trim())
+      ? parseInt(String(raw.version).trim(), 10)
+      : 0,
     summary: raw.summary ? String(raw.summary) : "",
     publish: parseBoolean(raw.publish, false),
     saveFirst: parseBoolean(raw.save, false),
@@ -1335,6 +1651,22 @@ export async function resolveRequiredBuildIdOrSelected(
     }
     if (mainBuildId > 0) return mainBuildId;
   }
+  // Same deal for a `pull --version <n>` checkout: read-only commands resolve
+  // the build it snapshots; mutating commands are pointed back at the
+  // editable workspace.
+  if (resolvedLocalProject?.metadata?.versionCheckout === true) {
+    const checkoutBuildId =
+      Number(resolvedLocalProject.metadata.buildId || 0) ||
+      Number(resolvedLocalProject.metadata.build?.id || 0);
+    const checkoutVersion =
+      Number(resolvedLocalProject.metadata.checkoutVersion || 0) || 0;
+    if (!MAIN_CHECKOUT_READONLY_COMMANDS.has(options.command)) {
+      throw new Error(
+        `This is a read-only checkout of a previous save${checkoutVersion ? ` (v${checkoutVersion})` : ""}${checkoutBuildId ? ` for Build ${checkoutBuildId}` : ""}; \`lumine ${options.command}\` isn't available here. Run it from the editable workspace, or pass an explicit Build URL.`,
+      );
+    }
+    if (checkoutBuildId > 0) return checkoutBuildId;
+  }
   if (
     resolvedLocalProject?.metadata &&
     isReadOnlyReferenceMetadata(resolvedLocalProject.metadata)
@@ -1424,6 +1756,9 @@ export function printHelp() {
   lumine select [twinkle-build-url]
   lumine pull [twinkle-build-url]
   lumine pull [twinkle-build-url] --main
+  lumine pull [twinkle-build-url] --version <n> [--main]
+  lumine versions [twinkle-build-url] [--main] [--limit <n>]
+  lumine restore <n> [--main]
   lumine reference <twinkle-build-url>
   lumine fork <twinkle-build-url>
   lumine diff <twinkle-branch-url>
@@ -1437,8 +1772,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
@@ -1451,6 +1790,9 @@ Examples:
   npx @stage5/lumine@latest diff https://www.twin-kle.com/build/884/4
   npx @stage5/lumine@latest merge https://www.twin-kle.com/build/884/4
   npx @stage5/lumine@latest pull 884 --main
+  npx @stage5/lumine@latest versions --main
+  npx @stage5/lumine@latest pull --version 41 --main
+  npx @stage5/lumine@latest restore 41 --main
   npx @stage5/lumine@latest update-from-main
   npx @stage5/lumine@latest pull
   npx @stage5/lumine@latest save
@@ -1462,6 +1804,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
@@ -1469,7 +1815,8 @@ Options:
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
-  --main                With pull: read-only checkout of the team project's main
+  --main                With pull/versions/restore: target the team project's main
+  --version <n>         With pull: read-only checkout of previous save v<n>
   --title <text>        New Build title
   --description <text>  Optional New Build description
   --no-description      Skip the New Build description prompt
@@ -1481,11 +1828,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";
@@ -69,6 +88,8 @@ export const LUMINE_REFERENCE_INSTRUCTIONS_MARKER =
   "<!-- Lumine CLI Reference Instructions -->";
 export const LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER =
   "<!-- Lumine CLI Main Checkout Instructions -->";
+export const LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER =
+  "<!-- Lumine CLI Version Checkout Instructions -->";
 export const BUNDLED_SDK_REFERENCE_URL = new URL(
   "../sdk/BUILD_SDK_INDEX.md",
   import.meta.url,
@@ -120,6 +141,12 @@ lumine save --summary "Describe the change"
 \`\`\`
 
 - Run lumine check before launch when possible.
+- \`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
+  for inspection; \`lumine restore <n>\` writes that save's files into THIS
+  workspace (local only — review, then lumine save). Use these to recover work
+  lost to a bad edit, merge, or overwrite instead of rebuilding it from memory.
 - Use \`lumine sdk call <namespace.method> '{...}'\` to inspect real endpoint
   data and measure latency (add --repeat <n>); \`lumine sdk list\` shows
   callable methods. It prints the raw HTTP endpoint response, which can differ
@@ -152,6 +179,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
 
@@ -167,6 +214,7 @@ lumine save --summary "Describe the change"
 
 - Use local project files with relative or root-local imports only. Do not add package imports, CDN scripts, external network calls, or app-local /api/* routes.
 - Build apps run in sandboxed iframes without allow-forms. Do not use <form> elements, native form submission, requestSubmit(), or browser form navigation. Build input flows with JavaScript-handled inputs and buttons instead.
+- Interface text must not be selectable on touch devices: long-pressing UI on mobile must not highlight it. Apply user-select: none plus -webkit-user-select: none and -webkit-touch-callout: none to interface text (HUD, buttons, labels, menus, scores, game controls). Keep text inputs and genuinely user-copyable content (story text, chat messages, user-written text) selectable. lumine check flags projects whose reachable files have clickable UI but no user-select: none rule.
 - CAUTION: the preview runtime AUTO-DETECTS "game apps" — any <canvas> in the body (even a decorative background canvas) or game-y words in visible text switch the app to viewport-app mode: html/body get overflow:hidden !important and body becomes a centering flexbox, so tall document-flow pages clip and stop scrolling. Document-style apps that use a canvas must call Twinkle.preview.subscribe (or getLayout/reserveInsets) early at boot — any of those opts out of auto game mode — then pad by layout.safeInsets and scroll within layout.viewport.height.
 - For canvas, WebGL, Three.js, fullscreen, or game builds, use Twinkle.preview for layout. Do not size roots from 100vh, 100vw, 100dvh, 100dvw, window.innerWidth, window.innerHeight, visualViewport, or document viewport dimensions.
 - For Three.js, use import * as THREE from '/build/vendor/three/0.184.0/three.module.min.js';. Addons (OrbitControls, GLTFLoader, ...) live under /build/vendor/three/0.184.0/addons/, e.g. import { OrbitControls } from '/build/vendor/three/0.184.0/addons/controls/OrbitControls.js';. Builds saved with the older /build/vendor/three/0.160.0/ path keep working.
@@ -201,6 +249,22 @@ the workspace to save.
 - To start from this Build, run lumine fork with the source build id and edit the forked workspace.
 - Do not edit another local checkout to bypass reference read-only semantics.
 `;
+export const LUMINE_VERSION_CHECKOUT_INSTRUCTIONS = `${LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER}
+# Lumine Version Checkout (Read-Only)
+
+This directory is a read-only snapshot of ONE PREVIOUS SAVE of a Twinkle Build,
+pulled with \`lumine pull --version <n>\`. Use it to inspect or diff what the
+project looked like at that save; it is not the workspace to edit or save.
+
+## Source Of Truth
+
+- Read .twinkle/lumine-project.json before using these files.
+- metadata.versionCheckout is true here: do not run lumine save from this directory.
+- To bring this save's files back into the live project, run \`lumine restore
+  <n>\` from the editable workspace (then \`lumine save\`), or copy the specific
+  parts you need into that workspace.
+- Do not edit another local checkout to bypass read-only semantics.
+`;
 export const LUMINE_MAIN_CHECKOUT_INSTRUCTIONS = `${LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER}
 # Lumine Main Checkout (Read-Only)
 
@@ -229,6 +293,8 @@ export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
   // assets never touch main's project files (uploads go to the current
   // user's own asset space), so listing/uploading from a main checkout is safe.
   "assets",
+  // versions only reads save history.
+  "versions",
 ]);
 export const COMMANDS = new Set([
   "workspace",
@@ -250,7 +316,10 @@ export const COMMANDS = new Set([
   "push",
   "check",
   "launch",
+  "versions",
+  "restore",
   "sdk",
   "assets",
+  "thumbnail",
   "help",
 ]);