@stage5/lumine 0.1.6 → 0.1.8

package/README.md

@@ -5,6 +5,8 @@ Launch Twinkle Lumine builds from any terminal.
 ```bash
 npx @stage5/lumine@latest
 npx @stage5/lumine@latest login
+npx @stage5/lumine@latest new "Daily Reflection App"
+npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Private journal with streaks"
 npx @stage5/lumine@latest projects
 npx @stage5/lumine@latest explore --sort forks
 npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
@@ -19,6 +21,13 @@ Run `lumine` with no subcommand for the easiest flow: sign in when needed,
 choose one of your owned or team projects, and pull the saved project files into
 a local folder.
 
+Use `lumine new` to create a new Twinkle Build with the same website create
+route used by Build Studio. The CLI asks for a title when one is not passed and
+asks for an optional description. It creates the Build and pulls an editable
+local workspace, but it does not auto-start a Lumine greeting or prompt run, so
+creating a project from the CLI does not spend AI battery. Add project files
+locally, including `/index.html`, then run `lumine save`.
+
 For team projects, Lumine mirrors the website workspace flow: choosing or
 pulling the owner's main project creates or reuses your contribution branch and
 checks out that branch locally. Saves go to your branch, so the project owner

package/bin/lumine.js

@@ -119,12 +119,16 @@ const COMMANDS = new Set([
   "login",
   "logout",
   "whoami",
+  "new",
   "projects",
   "explore",
   "select",
   "pull",
   "reference",
   "fork",
+  "diff",
+  "merge",
+  "replace-main",
   "save",
   "push",
   "check",
@@ -164,6 +168,10 @@ async function main() {
     await whoami(options);
     return;
   }
+  if (options.command === "new") {
+    await newBuild(options);
+    return;
+  }
   if (options.command === "projects") {
     await projects(options);
     return;
@@ -188,6 +196,18 @@ async function main() {
     await fork(options);
     return;
   }
+  if (options.command === "diff") {
+    await diff(options);
+    return;
+  }
+  if (options.command === "merge") {
+    await mergeBranch(options);
+    return;
+  }
+  if (options.command === "replace-main") {
+    await replaceMainWithBranch(options);
+    return;
+  }
   if (options.command === "save" || options.command === "push") {
     await save(options);
     return;
@@ -299,14 +319,30 @@ async function whoami(options) {
   );
 }
 
+async function newBuild(options) {
+  const title = await resolveNewBuildTitle(options);
+  const description = await resolveNewBuildDescription(options);
+  const auth = await ensureAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const createResult = await createBuild({
+    options,
+    auth,
+    title,
+    description,
+  });
+  const buildId = Number(createResult.build?.id || 0);
+  if (!buildId) {
+    throw new Error("Twinkle did not return a created Build.");
+  }
+  const result = await pullBuildFiles({ options, auth, buildId });
+  await saveSelectedBuild({ options, auth, build: result.build });
+  printNewBuildResult({ createResult, pullResult: result });
+}
+
 async function workspace(options) {
   const auth = await ensureAuth(options);
   const selectedBuild = options.target
-    ? await loadBuildMetadata({
-        options,
-        auth,
-        buildId: resolveRequiredBuildId(options.target),
-      })
+    ? await loadTargetBuildMetadata({ options, auth })
     : await chooseProject({
         builds: await listBuilds({ options, auth }),
       });
@@ -337,11 +373,7 @@ async function explore(options) {
 async function selectProject(options) {
   const auth = await resolveAuth(options);
   const selectedBuild = options.target
-    ? await loadBuildMetadata({
-        options,
-        auth,
-        buildId: resolveRequiredBuildId(options.target),
-      })
+    ? await loadTargetBuildMetadata({ options, auth })
     : await chooseProject({
         builds: await listBuilds({ options, auth }),
       });
@@ -376,7 +408,7 @@ async function pull(options) {
 
 async function reference(options) {
   const auth = await resolveAuth(options);
-  const buildId = resolveRequiredBuildId(options.target);
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
   const result = await pullReferenceFiles({ options, auth, buildId });
   printReferenceResult(result);
 }
@@ -384,7 +416,7 @@ async function reference(options) {
 async function fork(options) {
   const auth = await resolveAuth(options);
   await assertAuthScope({ options, auth, scope: "build:write" });
-  const buildId = resolveRequiredBuildId(options.target);
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
   const forkResult = await forkBuild({ options, auth, buildId });
   const forkedBuildId = Number(forkResult.build?.id || 0);
   if (!forkedBuildId) {
@@ -399,6 +431,60 @@ async function fork(options) {
   printForkResult({ forkResult, pullResult: result });
 }
 
+async function diff(options) {
+  const auth = await resolveAuth(options);
+  const build = await loadTargetBuildMetadata({ options, auth });
+  const { rootBuildId, contributionBuildId } =
+    resolveContributionActionBuildIds(build);
+  const result = await loadContributionDiff({
+    options,
+    auth,
+    rootBuildId,
+    contributionBuildId,
+  });
+  printContributionDiff({ result, build });
+}
+
+async function mergeBranch(options) {
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const build = await loadTargetBuildMetadata({ options, auth });
+  const { rootBuildId, contributionBuildId } =
+    resolveContributionActionBuildIds(build);
+  const result = await mergeContributionIntoMain({
+    options,
+    auth,
+    rootBuildId,
+    contributionBuildId,
+  });
+  printContributionActionResult({
+    action: "Merged",
+    result,
+    rootBuildId,
+    contributionBuildId,
+  });
+}
+
+async function replaceMainWithBranch(options) {
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const build = await loadTargetBuildMetadata({ options, auth });
+  const { rootBuildId, contributionBuildId } =
+    resolveContributionActionBuildIds(build);
+  const result = await replaceMainWithContribution({
+    options,
+    auth,
+    rootBuildId,
+    contributionBuildId,
+  });
+  printContributionActionResult({
+    action: "Replaced main with",
+    result,
+    rootBuildId,
+    contributionBuildId,
+  });
+}
+
 async function save(options) {
   const auth = await resolveAuth(options);
   await assertAuthScope({ options, auth, scope: "build:write" });
@@ -415,6 +501,11 @@ async function save(options) {
     buildId,
     localProject,
   });
+  if (build?.canWrite === false) {
+    throw new Error(
+      "This checkout is read-only for the current CLI login. Pull or diff it for review, then merge or replace main from the project owner workflow.",
+    );
+  }
   buildId = Number(build?.id || buildId);
   const dir = resolveProjectDirForSave({ options, localProject });
   const files = await collectProjectFiles(dir);
@@ -566,6 +657,11 @@ async function publishBuild({ options, buildId, auth }) {
 function printCheck(result) {
   const checks = result.checks || {};
   console.log(`Launch check: ${result.ok ? "ok" : "fail"}`);
+  if (checks.canonicalBuild) {
+    console.log(
+      `- canonical build: ${checks.canonicalBuild.ok ? "ok" : "fail"}`,
+    );
+  }
   console.log(
     `- project files: ${checks.projectFiles?.ok ? "ok" : "fail"} ` +
       `files=${checks.projectFiles?.fileCount ?? 0}`,
@@ -645,6 +741,11 @@ async function loadBuildMetadata({ options, auth, buildId }) {
   return result.build;
 }
 
+async function loadTargetBuildMetadata({ options, auth }) {
+  const buildId = await resolveRequiredBuildIdOrSelected(options, auth);
+  return await loadBuildMetadata({ options, auth, buildId });
+}
+
 async function loadOpenSourceBuildFiles({
   options,
   auth,
@@ -670,6 +771,24 @@ async function loadBuildFiles({ options, auth, buildId, includeContent }) {
   });
 }
 
+async function resolveBranchBuild({
+  options,
+  auth,
+  rootBuildId,
+  branchNumber,
+}) {
+  const result = await requestJson({
+    url: `${options.apiUrl}/cli/build/${rootBuildId}/branches/${branchNumber}`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+  const branchBuildId = Number(result.build?.id || 0);
+  if (!branchBuildId) {
+    throw new Error(`Branch ${branchNumber} for Build ${rootBuildId} could not be loaded.`);
+  }
+  return result.build;
+}
+
 async function forkBuild({ options, auth, buildId }) {
   return await requestJson({
     method: "POST",
@@ -680,6 +799,19 @@ async function forkBuild({ options, auth, buildId }) {
   });
 }
 
+async function createBuild({ options, auth, title, description }) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/create`,
+    authToken: auth.token,
+    body: {
+      title,
+      ...(description ? { description } : {}),
+    },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 async function saveProjectFiles({ options, auth, buildId, files, summary }) {
   return await requestJson({
     method: "PUT",
@@ -694,6 +826,49 @@ async function saveProjectFiles({ options, auth, buildId, files, summary }) {
   });
 }
 
+async function loadContributionDiff({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  return await requestJson({
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+async function mergeContributionIntoMain({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/merge`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+async function replaceMainWithContribution({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/replace-main`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 async function resolveBuildForSave({ options, auth, buildId, localProject }) {
   const localBuild = localProject?.metadata?.build;
   const localBuildId =
@@ -1226,6 +1401,11 @@ function assertLocalProjectCanBeSaved(localProject) {
       `This is a read-only Lumine reference${sourceBuildId ? ` for Build ${sourceBuildId}` : ""}. Run \`lumine fork${sourceBuildId ? ` ${sourceBuildId}` : ""}\` to create an editable workspace.`,
     );
   }
+  if (metadata.build?.canWrite === false) {
+    throw new Error(
+      "This Lumine checkout is read-only for the current CLI login. Pull or diff it for review; project-owner branch edits must go through merge or replace-main.",
+    );
+  }
 }
 
 function isReadOnlyReferenceMetadata(metadata) {
@@ -1344,6 +1524,17 @@ function isContributionBranch(build) {
   );
 }
 
+function resolveContributionActionBuildIds(build) {
+  const contributionBuildId = Number(build?.id || 0);
+  const rootBuildId = Number(build?.contributionRootBuildId || 0);
+  if (!contributionBuildId || !rootBuildId || !isContributionBranch(build)) {
+    throw new Error(
+      "Pass a branch URL such as https://www.twin-kle.com/build/884/4, or run this from a pulled branch workspace.",
+    );
+  }
+  return { rootBuildId, contributionBuildId };
+}
+
 function printPullResult(result) {
   const build = result.build || {};
   const entryPath = result.manifest?.entryPath || "unknown";
@@ -1356,8 +1547,17 @@ function printPullResult(result) {
   console.log(`Next: cd ${shellQuote(result.dir)}`);
   if (build.canWrite === false) {
     console.log("This checkout is read-only for the current CLI login.");
+    if (isContributionBranch(build)) {
+      console.log("Review changes: lumine diff");
+      if (build.role === "project_owner") {
+        console.log("Owner actions: lumine merge, or lumine replace-main");
+      }
+    }
     return;
   }
+  if (result.fileCount === 0) {
+    console.log("No project files yet. Create /index.html before your first save.");
+  }
   console.log('Codex: codex "Read AGENTS.md, then make the requested change."');
   console.log(
     'Claude Code: claude "Read CLAUDE.md, then make the requested change."',
@@ -1370,6 +1570,12 @@ function printPullResult(result) {
   }
 }
 
+function printNewBuildResult({ createResult, pullResult }) {
+  const build = pullResult.build || createResult.build || {};
+  console.log(`Created ${formatBuildTitle(build)}.`);
+  printPullResult(pullResult);
+}
+
 function printReferenceResult(result) {
   const build = result.build || {};
   const sourceBuildId =
@@ -1426,6 +1632,57 @@ function printSaveResult({ result, build, dir, files }) {
   }
 }
 
+function printContributionDiff({ result, build }) {
+  const summary = result.diff?.summary || {};
+  const files = Array.isArray(result.diff?.changedFiles)
+    ? result.diff.changedFiles
+    : [];
+  const branchNumber = Number(build.contributionBranchNumber || 0) || 0;
+  const branchLabel = branchNumber ? `branch ${branchNumber}` : `branch #${build.id}`;
+  console.log(`Diff for ${branchLabel}:`);
+  console.log(
+    `- total=${summary.total ?? files.length} added=${summary.added ?? 0} ` +
+      `updated=${summary.updated ?? 0} deleted=${summary.deleted ?? 0}`,
+  );
+  if (result.rootDrifted) {
+    console.log("- main changed after this branch was created");
+  }
+  if (!files.length) {
+    console.log("No file changes.");
+    return;
+  }
+  for (const file of files) {
+    const mergeStatus = file.mergeStatus ? ` (${file.mergeStatus})` : "";
+    console.log(`- ${file.status || "changed"} ${file.path}${mergeStatus}`);
+  }
+}
+
+function printContributionActionResult({
+  action,
+  result,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  if (!result?.success) {
+    console.log(result?.error || "Branch action did not complete.");
+    process.exitCode = 1;
+    return;
+  }
+  const projectFiles = Array.isArray(result.projectFiles)
+    ? result.projectFiles
+    : [];
+  console.log(`${action} branch #${contributionBuildId} for Build #${rootBuildId}.`);
+  if (projectFiles.length > 0) {
+    console.log(
+      `Main now has ${projectFiles.length} project file${projectFiles.length === 1 ? "" : "s"}.`,
+    );
+  }
+  if (result.mergeConflictsWritten || result.conflicts?.length > 0) {
+    console.log("Merge wrote conflict markers. Resolve them in the Build workspace.");
+  }
+  console.log(`Main workspace: ${rootBuildId}`);
+}
+
 async function resolveAuth(options) {
   if (options.authToken) {
     return { token: options.authToken };
@@ -1658,6 +1915,7 @@ function parseArgs(args) {
   const booleanFlags = new Set([
     "noOpen",
     "open",
+    "noDescription",
     "publish",
     "save",
     "noUpdateCheck",
@@ -1688,6 +1946,20 @@ function parseArgs(args) {
   return {
     command,
     target: raw.url || raw.target || positional[0] || "",
+    title:
+      String(
+        raw.title ||
+          (command === "new" ? positional.join(" ") : ""),
+      ).trim() || "",
+    description:
+      Object.prototype.hasOwnProperty.call(raw, "description")
+        ? String(raw.description || "").trim()
+        : null,
+    descriptionProvided: Object.prototype.hasOwnProperty.call(
+      raw,
+      "description",
+    ),
+    noDescription: parseBoolean(raw.noDescription, false),
     searchQuery:
       String(
         raw.search ||
@@ -1745,8 +2017,14 @@ async function resolveRequiredBuildIdOrSelected(
   auth,
   { localProject = null } = {},
 ) {
-  const buildId = resolveBuildId(options.target);
-  if (buildId > 0) return buildId;
+  const targetReference = resolveBuildReference(options.target);
+  if (targetReference.buildId > 0) {
+    return await resolveBuildReferenceBuildId({
+      options,
+      auth,
+      reference: targetReference,
+    });
+  }
   const resolvedLocalProject =
     localProject ||
     (await findLocalProjectMetadata(
@@ -1774,8 +2052,42 @@ async function resolveRequiredBuildIdOrSelected(
   );
 }
 
+async function resolveNewBuildTitle(options) {
+  const title = String(options.title || "").trim();
+  if (title) return title;
+  if (!input.isTTY || !output.isTTY) {
+    throw new Error('Pass a title: `lumine new "My Build"` or `lumine new --title "My Build"`.');
+  }
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question("Build title: ");
+    const normalized = String(answer || "").trim();
+    if (!normalized) {
+      throw new Error("Title is required.");
+    }
+    return normalized;
+  } finally {
+    rl.close();
+  }
+}
+
+async function resolveNewBuildDescription(options) {
+  if (options.noDescription) return null;
+  if (options.descriptionProvided) {
+    return String(options.description || "").trim() || null;
+  }
+  if (!input.isTTY || !output.isTTY) return null;
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question("Description (optional): ");
+    return String(answer || "").trim() || null;
+  } finally {
+    rl.close();
+  }
+}
+
 function resolveRequiredBuildId(value) {
-  const buildId = resolveBuildId(value);
+  const buildId = resolveBuildReference(value).buildId;
   if (buildId > 0) return buildId;
   throw new Error(
     "Pass a Twinkle build URL, app URL, preview URL, or build id.",
@@ -1783,40 +2095,74 @@ function resolveRequiredBuildId(value) {
 }
 
 function resolveBuildId(value) {
+  return resolveBuildReference(value).buildId;
+}
+
+async function resolveBuildReferenceBuildId({ options, auth, reference }) {
+  if (reference.branchNumber > 0) {
+    const build = await resolveBranchBuild({
+      options,
+      auth,
+      rootBuildId: reference.buildId,
+      branchNumber: reference.branchNumber,
+    });
+    return Number(build.id || 0);
+  }
+  return Number(reference.buildId || 0);
+}
+
+function resolveBuildReference(value) {
   const rawValue = String(value || "").trim();
   const directId = Number(rawValue);
-  if (Number.isFinite(directId) && directId > 0) return directId;
-  if (!rawValue) return 0;
+  if (Number.isFinite(directId) && directId > 0) {
+    return { buildId: directId, branchNumber: 0 };
+  }
+  if (!rawValue) return { buildId: 0, branchNumber: 0 };
 
   try {
     const parsedUrl = new URL(rawValue);
     const host = parsedUrl.hostname.toLowerCase();
     const previewHost = host.match(/^b-(\d+)\.preview\.lumine\.app$/);
-    if (previewHost) return Number(previewHost[1]) || 0;
+    if (previewHost) {
+      return { buildId: Number(previewHost[1]) || 0, branchNumber: 0 };
+    }
 
     const parts = parsedUrl.pathname.split("/").filter(Boolean);
     const appIndex = parts.indexOf("app");
-    if (appIndex >= 0) return Number(parts[appIndex + 1]) || 0;
+    if (appIndex >= 0) {
+      return { buildId: Number(parts[appIndex + 1]) || 0, branchNumber: 0 };
+    }
 
     const buildIndex = parts.indexOf("build");
     if (buildIndex >= 0) {
       if (parts[buildIndex + 1] === "preview") {
         const nestedBuildIndex = parts.indexOf("build", buildIndex + 2);
-        return Number(parts[nestedBuildIndex + 1]) || 0;
+        return {
+          buildId: Number(parts[nestedBuildIndex + 1]) || 0,
+          branchNumber: 0,
+        };
       }
-      return Number(parts[buildIndex + 1]) || 0;
+      return {
+        buildId: Number(parts[buildIndex + 1]) || 0,
+        branchNumber: Number(parts[buildIndex + 2]) || 0,
+      };
     }
 
-    return (
-      Number(parsedUrl.searchParams.get("buildId")) ||
-      Number(parsedUrl.searchParams.get("build")) ||
-      0
-    );
+    return {
+      buildId:
+        Number(parsedUrl.searchParams.get("buildId")) ||
+        Number(parsedUrl.searchParams.get("build")) ||
+        0,
+      branchNumber: 0,
+    };
   } catch {
     const match = rawValue.match(
-      /(?:^|\/)(?:app|build)\/(?:preview\/build\/)?(\d+)(?:\/|$)/,
+      /(?:^|\/)(?:app|build)\/(?:preview\/build\/)?(\d+)(?:\/(\d+))?(?:\/|$)/,
     );
-    return Number(match?.[1] || 0) || 0;
+    return {
+      buildId: Number(match?.[1] || 0) || 0,
+      branchNumber: Number(match?.[2] || 0) || 0,
+    };
   }
 }
 
@@ -1920,12 +2266,16 @@ function printHelp() {
   lumine login
   lumine whoami
   lumine logout
+  lumine new [title]
   lumine projects
   lumine explore [search terms]
   lumine select [twinkle-build-url]
   lumine pull [twinkle-build-url]
   lumine reference <twinkle-build-url>
   lumine fork <twinkle-build-url>
+  lumine diff <twinkle-branch-url>
+  lumine merge <twinkle-branch-url>
+  lumine replace-main <twinkle-branch-url>
   lumine save
   lumine check [twinkle-build-url]
   lumine launch [twinkle-build-url]
@@ -1933,9 +2283,13 @@ function printHelp() {
 Examples:
   npx @stage5/lumine@latest
   npx @stage5/lumine@latest login
+  npx @stage5/lumine@latest new "Daily Reflection App"
+  npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Private journal with streaks"
   npx @stage5/lumine@latest explore --sort forks
   npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
   npx @stage5/lumine@latest fork https://www.twin-kle.com/app/123
+  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
   npx @stage5/lumine@latest save
   npx @stage5/lumine@latest save --publish
@@ -1948,6 +2302,9 @@ Options:
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
+  --title <text>        New Build title
+  --description <text>  Optional New Build description
+  --no-description      Skip the New Build description prompt
   --summary <text>      Save summary
   --search <text>       Search public open-source Builds
   --sort <sort>         Sort open-source Builds: forks, popular, recent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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.25.0
+Version: 1.25.1
 Updated: 2026-05-28
-Generated: 2026-05-28T09:34:12.631Z
+Generated: 2026-05-28T10:24:18.784Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -203,15 +203,15 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
 
 ### Twinkle.aiCards
 - async list({ limit, cursor, level, minLevel, maxLevel, quality, userId, hasImage, hasExample } = {}) | scopes: content:read
-  - Returns: { cards: [{ id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
+  - Returns: { cards: [{ id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, isMysteryCard, isImageGenerating, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
   - List existing public AI Cards newest first, including each card word, example sentence text, word level, and quality.
   - Example: const { cards } = await Twinkle.aiCards.list({ level: 2, hasExample: true, limit: 20 });
 - async search({ query, limit, cursor, level, minLevel, maxLevel, quality, userId, hasImage, hasExample } = {}) | scopes: content:read
-  - Returns: { cards: [{ id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
+  - Returns: { cards: [{ id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, isMysteryCard, isImageGenerating, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction }], cursor?, pagination: { limit, hasMore, nextCursor }, filters }
   - Search existing public AI Cards by word, with optional level and quality filters.
   - Example: const { cards } = await Twinkle.aiCards.search({ query: searchText, minLevel: 1, maxLevel: 3, hasExample: true, limit: 12 });
 - async get(cardId) | scopes: content:read
-  - Returns: { card: { id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction } }
+  - Returns: { card: { id, contentType, contentId, word, text, exampleText, prompt, level, wordLevel, quality, style, imagePath, imageUrl, isMysteryCard, isImageGenerating, creatorId, ownerId, username, profilePicUrl, timeStamp, lastInteraction } }
   - Fetch one existing public AI Card by id, including word, example text, and level metadata.
   - Example: const { card } = await Twinkle.aiCards.get(cardId);