@stage5/lumine 0.2.92 → 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/commands.js

@@ -2601,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) : "",
@@ -2629,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) : "",
@@ -2916,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>]
@@ -2955,6 +2961,8 @@ 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
@@ -2991,8 +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

package/lib/util.js

@@ -47,7 +47,34 @@ export function formatBytes(bytes) {
   const value = Math.max(0, Number(bytes) || 0);
   if (value < 1024) return `${value} B`;
   if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KB`;
-  return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+  if (value < 1024 * 1024 * 1024) {
+    return `${(value / (1024 * 1024)).toFixed(1)} MB`;
+  }
+  return `${(value / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+
+// Storage sizes for the Lumine file storage unlock: "500MB", "1GB", "1.5gb",
+// or a bare number of MB ("750"). Binary units, matching the server quota.
+export function parseStorageSizeBytes(value) {
+  const raw = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "");
+  const match = raw.match(/^(\d+(?:\.\d+)?)(mb|m|gb|g)?$/);
+  if (!match) {
+    throw new Error(
+      `Pass a storage size like 500MB, 1GB or 2GB (got "${String(value ?? "")}").`,
+    );
+  }
+  const amount = Number(match[1]);
+  const unit = match[2] && match[2].startsWith("g") ? "gb" : "mb";
+  const bytes = Math.round(
+    amount * (unit === "gb" ? 1024 * 1024 * 1024 : 1024 * 1024),
+  );
+  if (!Number.isSafeInteger(bytes) || bytes <= 0) {
+    throw new Error("The storage size must be positive.");
+  }
+  return bytes;
 }
 
 export function isNewerVersion(latestVersion, currentVersion) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.92",
+  "version": "0.2.94",
   "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.60.0
-Updated: 2026-09-27
-Generated: 2026-09-27T13:54:27.792Z
+Version: 1.61.0
+Updated: 2026-09-28
+Generated: 2026-09-27T17:21:08.257Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -137,7 +137,9 @@ files:read, media:read, media:write, live:read, live:write, user:read, users:rea
   - Returns: { success, session } when opened by lumine app-mcp
   - Register the live iframe handlers for the published app's static MCP tool manifest.
   - Tool discovery comes only from /app-tools.json in the pinned published artifact; runtime code cannot add or rename tools.
-  - Every declared tool needs a same-named handler. Outside an app-mcp session, registration stores the handlers and resolves with active:false without starting a relay.
+  - Every declared tool needs a same-named handler. Outside an app-mcp session, registration stores the handlers, tells Twinkle the app offers tools (so the signed-in viewer can click Connect AI helper and pair this open tab with lumine app-mcp <buildId> --code <code>), and resolves with active:false.
+  - Mark each tool that only reads with "readOnly": true in /app-tools.json; for a tool whose action argument decides, declare "readOnlyWhen": { "action": ["list", "export"] }. A helper paired through Connect AI helper can use only read-only calls until the viewer switches on Allow edits; undeclared tools count as edits.
+  - Include what the viewer has selected or is looking at in the state-reading tool (for example the selected range and active item), so a paired helper can see what the viewer is pointing at.
   - Handlers run serially inside the visible app iframe and should return the confirmed post-action state.
   - Do not synthesize server-owned state; await Twinkle SDK mutations before returning.
   - Example: await Twinkle.appTools.register({ handlers: { get_state: () => ({ view, data }), open_view: ({ view }) => navigateTo(view) } });

package/sdk/LUMINE_ADMIN.md

@@ -1083,6 +1083,34 @@ mutation when a caller needs the same retry identity across processes. The CLI
 generates a fresh key for every mutation invocation; if a mutation fails, its
 JSON error includes `details.retryIdempotencyKey` for a safe exact retry.
 
+### Build review requests: one queue for every unlock (any time; added 2026-09-28)
+
+Everything a creator asks Mikey to unlock is one review request with a type:
+`rewards` (XP & Coin rewards, below), `project-limit` (more project room),
+`storage-limit` (more Lumine file storage, per creator) and `cardcraft` (an AI
+Card crafting recipe). Mikey sees them in one list (Management → **Build
+approvals**, or the CLI below), gets the same DM card for each, and decides
+them the same way. Each type keeps its own rules: reward approvals carry the
+earning rules and publish the frozen version; storage approvals take a size
+(500 MB / 1 GB / 2 GB tiers, any size up to the 2 GB cap, never lowering an
+existing approval); project room approvals raise Main to the fixed bounds;
+card crafting approvals make the recipe live in the published app without a
+new release. Only rewards and card crafting approvals can be revoked. The
+older per-type commands (`reward-review`, `cardcraft-review`, `storage
+approve|reject|list`) are aliases of these routes and keep working.
+
+```bash
+lumine admin review list --json                       # waiting on a decision (default)
+lumine admin review list --status queue --type storage,project --json
+lumine admin review show storage:12 --json             # <type>:<id>, or <id> --type storage
+lumine admin review approve storage:12 --size 1GB --json
+lumine admin review reject project:4 --reason "Split the big file first" --json
+lumine admin review approve cardcraft:3 --json
+lumine admin review revoke cardcraft:3 --reason "Too strong for level 1 cards" --json
+lumine admin review approve rewards:70 --config rules.json --json
+lumine admin review propose rewards:70 --dir /private/tmp/reward-review-70 --config rules.json --json
+```
+
 ### Build XP/Coin reward approvals (any time; also a full-daily-review duty)
 
 The creator's Lumine designs the rewards and writes them into the app. The