@stage5/lumine 0.2.91 → 0.2.94

package/lib/api.js

@@ -94,6 +94,38 @@ export async function createAppMcpSession({ options, auth, buildId }) {
   });
 }
 
+export async function claimAppMcpPairing({
+  options,
+  auth,
+  buildId,
+  code,
+  helperName,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/pairings/claim`,
+    authToken: auth.token,
+    body: { code, helperName: helperName || null },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function setAppMcpHelperName({
+  options,
+  auth,
+  buildId,
+  sessionId,
+  helperName,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/build/${buildId}/app-mcp/sessions/${sessionId}/helper`,
+    authToken: auth.token,
+    body: { helperName },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function createAppMcpCall({
   options,
   auth,
@@ -288,6 +320,32 @@ export async function upgradeBuildProjectLimits({ options, auth, buildId }) {
   });
 }
 
+export async function getRuntimeStorageLimit({ options, auth }) {
+  return await requestJson({
+    url: `${options.apiUrl}/build/runtime-storage-limit`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function requestRuntimeStorageLimit({
+  options,
+  auth,
+  requestedBytes,
+  reason,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/runtime-storage-limit-request`,
+    authToken: auth.token,
+    body: {
+      ...(requestedBytes ? { requestedBytes } : {}),
+      ...(reason ? { reason } : {}),
+    },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function saveProjectFiles({
   options,
   auth,

package/lib/app-mcp/server.js

@@ -2,10 +2,12 @@ import { spawn } from "node:child_process";
 import readline from "node:readline";
 
 import {
+  claimAppMcpPairing,
   closeAppMcpSession,
   createAppMcpCall,
   createAppMcpSession,
   loadAppMcpCall,
+  setAppMcpHelperName,
 } from "../api.js";
 import { assertAuthScope, resolveAuth } from "../auth.js";
 import { resolveRequiredBuildId } from "../util.js";
@@ -18,6 +20,77 @@ function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+const PAIRED_SESSION_ENDED_MESSAGE =
+  'The AI helper connection ended (the user clicked Disconnect or left the app). Ask them to click "Connect AI helper" in the app for a new code, then restart with lumine app-mcp <buildId> --code <code>.';
+
+function rethrowPairedSessionError(error) {
+  if (
+    Number(error?.status || 0) === 404 &&
+    /MCP session not found/i.test(String(error?.message || ""))
+  ) {
+    const ended = new Error(PAIRED_SESSION_ENDED_MESSAGE);
+    ended.status = 404;
+    throw ended;
+  }
+  throw error;
+}
+
+// MCP clients name themselves in initialize (clientInfo.name). This is only a
+// label for the viewer's "AI helper connected" badge.
+export function helperDisplayName(clientInfo) {
+  const raw = String(clientInfo?.name || "").trim();
+  if (!raw) return "";
+  const known = [
+    [/^claude[-_ ]?code/i, "Claude Code"],
+    [/^codex/i, "Codex"],
+    [/^claude/i, "Claude"],
+    [/^cursor/i, "Cursor"],
+  ];
+  for (const [pattern, label] of known) {
+    if (pattern.test(raw)) return label;
+  }
+  return raw.slice(0, 80);
+}
+
+// Read-only declarations travel to the MCP client as the standard
+// readOnlyHint, plus a plain note for tools whose action decides.
+export function toMcpTool(tool) {
+  const readOnlyWhen =
+    tool.readOnlyWhen && typeof tool.readOnlyWhen === "object"
+      ? Object.entries(tool.readOnlyWhen)[0]
+      : null;
+  const note =
+    readOnlyWhen && Array.isArray(readOnlyWhen[1])
+      ? ` (Works without "Allow edits" when ${readOnlyWhen[0]} is ${readOnlyWhen[1].join(", ")}.)`
+      : "";
+  return {
+    name: tool.name,
+    description: `${tool.description || ""}${note}`.trim(),
+    inputSchema: tool.inputSchema || {
+      type: "object",
+      additionalProperties: false,
+    },
+    ...(tool.readOnly === true ? { annotations: { readOnlyHint: true } } : {}),
+  };
+}
+
+function pairedInstructions(session) {
+  const readTools = (session.manifest?.tools || [])
+    .filter((tool) => tool.readOnly === true)
+    .map((tool) => tool.name);
+  return [
+    session.manifest?.description ||
+      `Use the semantic tools exposed by ${session.buildTitle}.`,
+    `You are attached to the user's own open ${session.buildTitle} tab: they see every change you make, live.`,
+    "Start with a read-only state tool; what the user has selected or is looking at is usually in it.",
+    session.allowEdits
+      ? "Edits are allowed right now; the user can switch them off at any time."
+      : `Edits are OFF until the user switches on "Allow edits" in the app. Until then only read-only calls work${
+          readTools.length ? ` (${readTools.join(", ")})` : ""
+        }; a write returns an "edits not allowed" error, so ask the user to switch it on.`,
+  ].join(" ");
+}
+
 function rethrowAppMcpSessionError(error) {
   const message = String(error?.message || error);
   if (
@@ -56,12 +129,23 @@ function openApp(url) {
 export async function appMcpCommand(options) {
   const buildId = resolveRequiredBuildId(options.target || options.buildIdFlag);
   if (!buildId) {
-    throw new Error("Usage: lumine app-mcp <published-app-url-or-id>");
+    throw new Error(
+      "Usage: lumine app-mcp <published-app-url-or-id> [--code <code>]",
+    );
   }
   const auth = await resolveAuth(options);
   await assertAuthScope({ options, auth, scope: "build:read" });
   await assertAuthScope({ options, auth, scope: "build:write" });
-  const created = await createAppMcpSession({ options, auth, buildId });
+  const paired = Boolean(options.pairingCode);
+  const created = paired
+    ? await claimAppMcpPairing({
+        options,
+        auth,
+        buildId,
+        code: options.pairingCode,
+        helperName: options.helperName || null,
+      })
+    : await createAppMcpSession({ options, auth, buildId });
   const session = created?.session;
   if (!session?.id || !session?.manifest?.tools?.length) {
     if (session?.id) {
@@ -75,26 +159,28 @@ export async function appMcpCommand(options) {
     throw new Error("Twinkle did not return an app MCP session.");
   }
   try {
-    if (options.openBrowser !== false) {
+    if (paired) {
+      process.stderr.write(
+        `lumine app-mcp: attached to your open ${session.buildTitle} tab. ` +
+          (session.allowEdits
+            ? "Edits are allowed.\n"
+            : 'Edits stay off until you switch on "Allow edits" in the app.\n'),
+      );
+    } else if (options.openBrowser !== false) {
       openApp(session.appUrl);
     } else {
       process.stderr.write(
         `lumine app-mcp: open this signed-in app tab: ${session.appUrl}\n`,
       );
     }
-    process.stderr.write(
-      `lumine app-mcp: ${session.buildTitle} is pinned to artifact ${session.artifactVersionId}. ` +
-        `Keep the opened Twinkle tab running.\n`,
-    );
+    if (!paired) {
+      process.stderr.write(
+        `lumine app-mcp: ${session.buildTitle} is pinned to artifact ${session.artifactVersionId}. ` +
+          `Keep the opened Twinkle tab running.\n`,
+      );
+    }
 
-    const tools = session.manifest.tools.map((tool) => ({
-      name: tool.name,
-      description: tool.description || "",
-      inputSchema: tool.inputSchema || {
-        type: "object",
-        additionalProperties: false,
-      },
-    }));
+    const tools = session.manifest.tools.map(toMcpTool);
     const input = readline.createInterface({
       input: process.stdin,
       crlfDelay: Infinity,
@@ -112,6 +198,7 @@ export async function appMcpCommand(options) {
           buildId,
           session,
           tools,
+          paired,
         });
       let isToolCall = false;
       try {
@@ -152,7 +239,9 @@ async function callAppTool({
   sessionId,
   name,
   arguments: toolArguments,
+  paired = false,
 }) {
+  const rethrow = paired ? rethrowPairedSessionError : rethrowAppMcpSessionError;
   const created = await createAppMcpCall({
     options,
     auth,
@@ -160,7 +249,7 @@ async function callAppTool({
     sessionId,
     name,
     arguments: toolArguments,
-  }).catch(rethrowAppMcpSessionError);
+  }).catch(rethrow);
   const callId = created?.call?.id;
   if (!callId) throw new Error("Twinkle did not create the app tool call.");
   const deadline = Date.now() + CALL_TIMEOUT_MS;
@@ -171,7 +260,7 @@ async function callAppTool({
       buildId,
       sessionId,
       callId,
-    }).catch(rethrowAppMcpSessionError);
+    }).catch(rethrow);
     const call = payload?.call;
     if (call?.status === "completed") return call.result;
     if (call?.status === "failed") {
@@ -185,7 +274,7 @@ async function callAppTool({
     buildId,
     sessionId,
     callId,
-  }).catch(rethrowAppMcpSessionError);
+  }).catch(rethrow);
   if (finalPayload?.call?.status === "completed") {
     return finalPayload.call.result;
   }
@@ -193,11 +282,21 @@ async function callAppTool({
     throw new Error(finalPayload.call.errorMessage || "App tool failed.");
   }
   throw new Error(
-    "App tool call timed out. Reload the appUrl tab, or restart the Lumine app-mcp driver and reopen its new appUrl.",
+    paired
+      ? "App tool call timed out. Ask the user to keep the app tab open in front (background tabs can pause), then retry."
+      : "App tool call timed out. Reload the appUrl tab, or restart the Lumine app-mcp driver and reopen its new appUrl.",
   );
 }
 
-async function handleMcpMessage({ line, options, auth, buildId, session, tools }) {
+async function handleMcpMessage({
+  line,
+  options,
+  auth,
+  buildId,
+  session,
+  tools,
+  paired = false,
+}) {
   let message;
   try {
     message = JSON.parse(line);
@@ -208,6 +307,17 @@ async function handleMcpMessage({ line, options, auth, buildId, session, tools }
   const method = String(message?.method || "");
   if (id === undefined || id === null) return;
   if (method === "initialize") {
+    const helperName = helperDisplayName(message?.params?.clientInfo);
+    if (paired && helperName && !options.helperName) {
+      // Label only; a failure here must never break the MCP handshake.
+      await setAppMcpHelperName({
+        options,
+        auth,
+        buildId,
+        sessionId: session.id,
+        helperName,
+      }).catch(() => {});
+    }
     return writeMcpResult(id, {
       protocolVersion: MCP_PROTOCOL_VERSION,
       capabilities: { tools: { listChanged: false } },
@@ -215,9 +325,10 @@ async function handleMcpMessage({ line, options, auth, buildId, session, tools }
         name: `lumine-app-${buildId}`,
         version: "1.0.0",
       },
-      instructions:
-        session.manifest.description ||
-        `Use the semantic tools exposed by ${session.buildTitle}.`,
+      instructions: paired
+        ? pairedInstructions(session)
+        : session.manifest.description ||
+          `Use the semantic tools exposed by ${session.buildTitle}.`,
     });
   }
   if (method === "ping") return writeMcpResult(id, {});
@@ -235,6 +346,7 @@ async function handleMcpMessage({ line, options, auth, buildId, session, tools }
         sessionId: session.id,
         name,
         arguments: message?.params?.arguments || {},
+        paired,
       });
       return writeMcpResult(id, {
         content: [{ type: "text", text: JSON.stringify(result) }],

package/lib/assets.js

@@ -16,12 +16,14 @@ import {
 import {
   buildApiJson,
   fetchAllRuntimeAssets,
+  getRuntimeStorageLimit,
   loadBuildFiles,
   mintBuildApiToken,
+  requestRuntimeStorageLimit,
 } from "./api.js";
 import { assertAuthScope, ensureAuth } from "./auth.js";
 import { resolveSdkBuildId } from "./sdk.js";
-import { formatBytes, sleep } from "./util.js";
+import { formatBytes, parseStorageSizeBytes, sleep } from "./util.js";
 import {
   collectWorkspaceTextFilesLenient,
   findLocalProjectMetadata,
@@ -55,8 +57,97 @@ export async function assetsCommand(options) {
     await assetsGenerate(options);
     return;
   }
+  if (subcommand === "storage") {
+    await assetsStorage(options);
+    return;
+  }
+  if (subcommand === "request-storage") {
+    await assetsRequestStorage(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> | lumine assets delete <assetId> | lumine assets prune [--yes]',
+    '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> | lumine assets delete <assetId> | lumine assets prune [--yes] | lumine assets storage | lumine assets request-storage [--size 500MB|1GB|2GB] [--reason "<what it is for>"]',
+  );
+}
+
+// Lumine file storage is counted per user across all their Builds. Past the
+// default quota, Mikey approves more (like the per-project file-limit unlock).
+export function formatStorageApproval(approval) {
+  if (!approval) return [];
+  const lines = [
+    `Storage limit: ${formatBytes(approval.maxRuntimeFileStorageBytes)}${approval.hasOverride ? " (approved by Mikey)" : ""} · ${formatBytes(approval.runtimeFileStorageBytes || 0)} used across ${Number(approval.runtimeFileCount || 0)} file(s) in all your builds`,
+  ];
+  const latest = approval.latestRequest;
+  if (latest?.status === "pending") {
+    lines.push(
+      `Request #${latest.requestId} for ${formatBytes(latest.requestedMaxRuntimeFileStorageBytes)} is waiting for Mikey's review.`,
+    );
+  } else if (latest?.status === "rejected") {
+    lines.push(
+      `Request #${latest.requestId} was declined${latest.reviewReason ? `: ${latest.reviewReason}` : "."}`,
+    );
+  } else if (latest?.status === "approved") {
+    lines.push(
+      `Request #${latest.requestId} was approved (${formatBytes(latest.approvedMaxRuntimeFileStorageBytes || latest.requestedMaxRuntimeFileStorageBytes)}).`,
+    );
+  }
+  if (approval.canRequest && latest?.status !== "pending") {
+    lines.push(
+      `Need more? \`lumine assets request-storage --size <${(approval.requestTiers || []).map((tier) => formatBytes(tier).replace(".0 ", "")).join("|")}> --reason "<what it is for>"\` asks Mikey.`,
+    );
+  } else if (!approval.canRequest) {
+    lines.push("This is the most Lumine file storage that can be approved.");
+  }
+  return lines;
+}
+
+export async function assetsStorage(options) {
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:read" });
+  const result = await getRuntimeStorageLimit({ options, auth });
+  const approval = result?.storageLimitApproval;
+  if (!approval) {
+    throw new Error("Twinkle did not return your storage limit.");
+  }
+  if (options.json) {
+    console.log(JSON.stringify(approval, null, 2));
+    return;
+  }
+  for (const line of formatStorageApproval(approval)) console.log(line);
+}
+
+export async function assetsRequestStorage(options) {
+  const requestedBytes = options.storageSize
+    ? parseStorageSizeBytes(options.storageSize)
+    : null;
+  const reason = String(options.adminReason || "").trim();
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const result = await requestRuntimeStorageLimit({
+    options,
+    auth,
+    requestedBytes,
+    reason,
+  });
+  const request = result?.request;
+  const approval = result?.storageLimitApproval;
+  if (result?.success !== true || !request) {
+    throw new Error("Twinkle did not confirm the storage request.");
+  }
+  if (options.json) {
+    console.log(JSON.stringify({ request, storageLimitApproval: approval }, null, 2));
+    return;
+  }
+  if (request.status === "approved") {
+    console.log(
+      `Approved: your Lumine file storage is now ${formatBytes(approval?.maxRuntimeFileStorageBytes || request.approvedMaxRuntimeFileStorageBytes)}.`,
+    );
+    return;
+  }
+  console.log(
+    result.changed
+      ? `Sent storage request #${request.requestId} for ${formatBytes(request.requestedMaxRuntimeFileStorageBytes)} to Mikey. Nothing changes until he approves it.`
+      : `Storage request #${request.requestId} for ${formatBytes(request.requestedMaxRuntimeFileStorageBytes)} is already waiting for Mikey.`,
   );
 }
 

package/lib/cardcraft.js

@@ -0,0 +1,141 @@
+import fs from "fs/promises";
+import path from "path";
+
+import { requestJson } from "./http.js";
+import { findLocalProjectMetadata } from "./workspace.js";
+import { ensureAuth, assertAuthScope } from "./auth.js";
+import { resolveRequiredBuildIdOrSelected } from "./commands.js";
+
+// Creator-side AI Card crafting tooling (Twinkle.cardCraft).
+//
+// An app declares what AI Cards can become in it in `cardcraft.json` at the
+// project root: kinds (pet, snack, furniture …) with their parameters, and
+// which kinds each card colour (1 blue … 6 black) can become. A reviewer
+// approves the recipe; the approved copy is what crafting uses, so editing
+// the file changes nothing live until the next approval.
+
+const CARDCRAFT_FILE = "cardcraft.json";
+
+async function readWorkspaceCardCraftJson(options) {
+  const localProject = await findLocalProjectMetadata(
+    path.resolve(options.dir || process.cwd()),
+  );
+  if (!localProject?.rootDir) return { present: false, value: undefined };
+  let raw;
+  try {
+    raw = await fs.readFile(path.join(localProject.rootDir, CARDCRAFT_FILE), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return { present: false, value: undefined };
+    throw error;
+  }
+  try {
+    return { present: true, value: JSON.parse(raw) };
+  } catch (error) {
+    throw new Error(`${CARDCRAFT_FILE} is not valid JSON: ${error?.message || error}`);
+  }
+}
+
+function printCheck(result) {
+  if (!result?.ok) {
+    console.log("Card crafting recipe: NOT ready.");
+    for (const error of result?.errors || []) console.log(`  - ${error}`);
+    return;
+  }
+  const summary = result.summary || {};
+  console.log(
+    `Card crafting recipe: ok (${(summary.kinds || []).length} kind(s); card colours ${(summary.acceptedLevels || []).join(", ") || "none"}).`,
+  );
+  for (const kind of summary.kinds || [])
+    console.log(`  ${kind.id}: ${kind.label} · params ${kind.params.join(", ") || "none"}`);
+  if (result.nextStep) console.log(result.nextStep);
+}
+
+export async function cardcraftCommand(options) {
+  const action = String(options.positional?.[0] || "check");
+  if (options.help) {
+    printCardCraftHelp();
+    return;
+  }
+  const auth = await ensureAuth(options);
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
+  if (action === "check") {
+    const local = await readWorkspaceCardCraftJson(options);
+    const result = await requestJson({
+      url: `${options.apiUrl}/build/${buildId}/cardcraft/check`,
+      method: "POST",
+      authToken: auth.token,
+      timeoutMs: options.timeoutMs,
+      body: local.present ? { cardcraftJson: local.value } : {},
+    });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(
+        local.present
+          ? `Checked ${CARDCRAFT_FILE} from this workspace.`
+          : `No ${CARDCRAFT_FILE} in this workspace; checked the saved version instead.`,
+      );
+      printCheck(result);
+    }
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === "status") {
+    const result = await requestJson({
+      url: `${options.apiUrl}/build/${buildId}/cardcraft`,
+      authToken: auth.token,
+      timeoutMs: options.timeoutMs,
+    });
+    if (options.json) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log(`Card crafting: ${result.state}. ${result.message || ""}`.trim());
+      if (result.latestReview)
+        console.log(
+          `Latest review #${result.latestReview.id}: ${result.latestReview.status}${result.latestReview.reason ? ` · ${result.latestReview.reason}` : ""}`,
+        );
+      for (const problem of result.problems || []) console.log(`  - ${problem}`);
+    }
+    return;
+  }
+  if (action === "review") {
+    await assertAuthScope({ options, auth, scope: "build:write" });
+    const result = await requestJson({
+      url: `${options.apiUrl}/build/${buildId}/cardcraft/reviews`,
+      method: "POST",
+      authToken: auth.token,
+      timeoutMs: options.timeoutMs,
+      body: {},
+    });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    if (result.state === "approved")
+      console.log(`The saved ${CARDCRAFT_FILE} is already the approved recipe (#${result.reviewId}).`);
+    else
+      console.log(
+        `Sent the saved ${CARDCRAFT_FILE} of Build ${buildId} for review (request #${result.reviewId}${result.duplicate ? ", already waiting" : ""}). Any approved recipe keeps working until this one is approved.`,
+      );
+    return;
+  }
+  printCardCraftHelp();
+  throw new Error(`Unknown cardcraft action: ${action}`);
+}
+
+function printCardCraftHelp() {
+  console.log(`Usage:
+  lumine cardcraft check    Validate cardcraft.json (workspace, else the saved version)
+  lumine cardcraft status   Approved / waiting for review / needs review
+  lumine cardcraft review   Send the saved cardcraft.json for review
+
+cardcraft.json (project root) says what AI Cards can become in this app:
+  { "guidance"?: "short creative brief",
+    "kinds": [{ "id", "label", "description"?,
+                "params": { "<name>": { "type": "enum", "values": [...] }
+                                     | { "type": "integer" | "number", "min", "max", "scaleWithTier"? }
+                                     | { "type": "boolean" } | { "type": "string", "maxLength" } } }],
+    "tiers": { "1": ["<kind>"], … "6": ["<kind>"] } }
+Card colours: 1 blue, 2 pink, 3 orange, 4 magenta, 5 gold, 6 black (grander as they go up);
+quality (common … legendary) sets the finish effects. A card can be crafted once, ever;
+the asset stays with the card when it is sold. Use Twinkle.cardCraft in the app.`);
+}

package/lib/commands.js

@@ -58,6 +58,7 @@ import {
 } from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
 import { rewardsCommand, reportRewardDeclaration } from "./rewards.js";
+import { cardcraftCommand } from "./cardcraft.js";
 import { chatlogCommand } from "./chatlog.js";
 import {
   assertAuthScope,
@@ -284,6 +285,10 @@ export async function main() {
     await rewardsCommand(options);
     return;
   }
+  if (options.command === "cardcraft") {
+    await cardcraftCommand(options);
+    return;
+  }
   if (options.command === "thumbnail") {
     await thumbnailCommand(options);
     return;
@@ -2596,6 +2601,7 @@ export function parseArgs(args) {
     draftId: raw.draftId ? String(raw.draftId) : "",
     twinkles: raw.twinkles ? String(raw.twinkles) : "",
     adminReason: raw.reason ? String(raw.reason) : "",
+    storageSize: raw.size ? String(raw.size) : "",
     adminContextLimit: raw.limit === undefined ? 20 : Number(raw.limit),
     adminRun: raw.run ? String(raw.run) : "",
     adminTarget: raw.target ? String(raw.target) : "",
@@ -2624,6 +2630,10 @@ export function parseArgs(args) {
       .map((scope) => scope.trim())
       .filter(Boolean),
     buildIdFlag: raw.build ? String(raw.build) : "",
+    // `lumine app-mcp <id> --code <code>` attaches to the viewer's own open
+    // app tab ("Connect AI helper") instead of opening a new tab.
+    pairingCode: raw.code ? String(raw.code).trim() : "",
+    helperName: raw.helperName ? String(raw.helperName).trim() : "",
     model: raw.model ? String(raw.model) : "",
     quality: raw.quality ? String(raw.quality) : "",
     assetName: raw.name ? String(raw.name) : "",
@@ -2911,6 +2921,7 @@ export function printHelp() {
   lumine sponsor job fail <job-id> --reason <text>
   lumine sponsor jobs
   lumine app-mcp <published-app-url-or-id> [--no-open]
+  lumine app-mcp <app-url-or-id> --code <code> [--helper-name <name>]
   lumine new [title]
   lumine rename [title] [--target <twinkle-build-url-or-id>]
   lumine describe [description] [--target <twinkle-build-url-or-id>]
@@ -2950,12 +2961,15 @@ export function printHelp() {
   lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>
   lumine assets delete <assetId>
   lumine assets prune [--yes]
+  lumine assets storage [--json]
+  lumine assets request-storage [--size 500MB|1GB|2GB] [--reason <what it is for>]
   lumine chatlog [build] [--since 2h] [--limit 100] [--instance <id>] [--json]
   lumine chatlog enable|disable [build]
   lumine rewards check
   lumine rewards sheet <file.json>
   lumine rewards sheet --show
   lumine rewards review
+  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>
@@ -2985,7 +2999,10 @@ export function printHelp() {
   lumine admin sponsor integrity cases [--status open|pending|held|flagged|cleared|disqualified] [--json]
   lumine admin sponsor integrity get <case-id> [--json]
   lumine admin sponsor integrity review <case-id> --decision clear|hold|flag|disqualify [--note <evidence>] [--json]
+  lumine admin review list [--type rewards|project|storage|cardcraft] [--status queue|pending|approved|rejected|all] [--cursor <c>] | show <type:id> [--dir <path>] | approve <type:id> [--config <rules.json>] [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject|revoke <type:id> [--reason <text>] | propose rewards:<id> --dir <edited-snapshot> --config <rules.json>
   lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] [--json]
+  lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
+  lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]
   lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
   lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] [--json]
   lumine admin chat-reports show <report-id> [--json]   (reported message snapshot + surrounding context)

package/lib/constants.js

@@ -253,6 +253,11 @@ lumine save --summary "Describe the change"
   \`lumine assets prune\` deletes your uploads that nothing references (server
   checks draft files, published/version snapshots, and derived builds; local
   unsaved edits are scanned too). The server enforces storage quotas.
+- Storage is per user across all their builds (\`lumine assets storage\`
+  shows the limit and usage). If the quota blocks an upload and pruning is not
+  enough, tell the user and, with their OK, run
+  \`lumine assets request-storage --reason "<what the space is for>"\` to ask
+  Mikey for more (500MB/1GB/2GB tiers; nothing changes until he approves).
 - CAUTION: asset URLs an app stores in privateDb/sharedDb/user DBs at runtime
   (Twinkle.files uploads), or URLs referenced only inside uploaded files such as
   .gltf manifests, are invisible to prune. Keep those asset URLs in project
@@ -447,6 +452,7 @@ export const COMMANDS = new Set([
   "sdk",
   "assets",
   "rewards",
+  "cardcraft",
   "chatlog",
   "thumbnail",
   "doctor",