@stage5/lumine 0.2.16 → 0.2.18

package/README.md

@@ -9,8 +9,11 @@ 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 rename "My New Build Title"
 npx @stage5/lumine@latest rename "New Title" --target 123
+npx @stage5/lumine@latest describe "A welcoming place to build together"
+npx @stage5/lumine@latest describe --no-description --target 123
 npx @stage5/lumine@latest projects
 npx @stage5/lumine@latest branches 884
+npx @stage5/lumine@latest suggestions 884
 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
@@ -31,6 +34,12 @@ 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`.
 
+Use `lumine rename` to change an existing Build title and `lumine describe` to
+change its description through the same canonical metadata route as the
+website. Both commands target the current workspace or selected Build; pass
+`--target <build-url-or-id>` to update another Build you own. Run
+`lumine describe --no-description` to clear a description explicitly.
+
 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
@@ -40,6 +49,17 @@ Use `lumine branches <build-url-or-id>` to list the contribution branches you
 can review, including each contributor, branch number, status, and URL. Then use
 `lumine diff <branch-url>` to inspect one branch.
 
+Branch contributors can nudge the project owner from their pulled branch with
+`lumine suggest branch [message]` or `lumine suggest thumbnail`. The thumbnail
+command offers the thumbnail currently saved on that branch. Project owners can
+run `lumine suggestions <build-url-or-id>` to see their open suggestion inbox.
+The inbox prints canonical follow-up commands for merging or replacing Main and
+for applying the exact frozen thumbnail shown in a suggestion. The same actions
+are also available directly as `lumine suggestions merge <id>`,
+`lumine suggestions replace-main <id>`, and
+`lumine suggestions adopt-thumbnail <id>`. Large inboxes are cursor-paginated;
+the CLI prints the exact `--cursor` command for the next page.
+
 Use `lumine explore` to list public open-source Build apps that can be used as
 examples or starting points. It supports `--search` and `--sort forks`,
 `--sort popular`, or `--sort recent`. Use `lumine reference <build-url-or-id>`

package/lib/api.js

@@ -189,6 +189,74 @@ export async function loadContributionDiff({
   });
 }
 
+export async function listBuildSuggestions({
+  options,
+  auth,
+  rootBuildId,
+  cursor,
+  suggestionId,
+}) {
+  const query = new URLSearchParams();
+  if (Number(cursor || 0) > 0) query.set("cursor", String(cursor));
+  if (Number(suggestionId || 0) > 0) {
+    query.set("suggestionId", String(suggestionId));
+  }
+  const queryString = query.toString();
+  return await requestJson({
+    url: `${options.apiUrl}/build/${rootBuildId}/suggestions${queryString ? `?${queryString}` : ""}`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function notifyBuildOwnerOfContribution({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+  note,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/notify-owner`,
+    authToken: auth.token,
+    body: { note },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function suggestBuildThumbnailToOwner({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/suggest-thumbnail`,
+    authToken: auth.token,
+    body: {},
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+export async function adoptBuildThumbnailSuggestion({
+  options,
+  auth,
+  rootBuildId,
+  contributionBuildId,
+  suggestionMessageId,
+  thumbnailUrl,
+}) {
+  return await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/build/${rootBuildId}/contributions/${contributionBuildId}/adopt-thumbnail`,
+    authToken: auth.token,
+    body: { suggestionMessageId, thumbnailUrl },
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function mergeContributionIntoMain({
   options,
   auth,

package/lib/commands.js

@@ -21,10 +21,12 @@ import {
   SDK_REFERENCE_FILE,
 } from "./constants.js";
 import {
+  adoptBuildThumbnailSuggestion,
   createBuild,
   fetchAllRuntimeAssets,
   forkBuild,
   listBuilds,
+  listBuildSuggestions,
   listOpenSourceBuilds,
   loadBuildFiles,
   loadBuildMetadata,
@@ -37,13 +39,19 @@ import {
   maybeCheckForLumineCliUpdate,
   mergeContributionIntoMain,
   mintBuildApiToken,
+  notifyBuildOwnerOfContribution,
   publishBuild,
   replaceMainWithContribution,
   resolveBranchBuild,
   saveProjectFiles,
+  suggestBuildThumbnailToOwner,
   updateBuildMetadata,
 } from "./api.js";
-import { assetsCommand, writeAssetsManifest } from "./assets.js";
+import {
+  assetsCommand,
+  confirmPrompt,
+  writeAssetsManifest,
+} from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
 import {
   assertAuthScope,
@@ -128,6 +136,10 @@ export async function main() {
     await renameBuild(options);
     return;
   }
+  if (options.command === "describe") {
+    await describeBuild(options);
+    return;
+  }
   if (options.command === "projects") {
     await projects(options);
     return;
@@ -136,6 +148,14 @@ export async function main() {
     await branches(options);
     return;
   }
+  if (options.command === "suggest") {
+    await sendSuggestion(options);
+    return;
+  }
+  if (options.command === "suggestions") {
+    await suggestions(options);
+    return;
+  }
   if (options.command === "explore") {
     await explore(options);
     return;
@@ -239,6 +259,36 @@ export async function renameBuild(options) {
       'Pass a title: `lumine rename "My New Build Title"` or `lumine rename --title "My New Build Title"`.',
     );
   }
+  const { buildId, updatedBuild } = await updateOwnedBuildDetails({
+    options,
+    patch: { title },
+    permissionError: (id) => `You cannot rename Build #${id}.`,
+    failureMessage: "Failed to rename the Build.",
+  });
+  console.log(`Renamed Build #${buildId} to "${updatedBuild.title}".`);
+}
+
+export async function describeBuild(options) {
+  const description = await resolveBuildDescriptionUpdate(options);
+  const { updatedBuild } = await updateOwnedBuildDetails({
+    options,
+    patch: { description },
+    permissionError: (id) => `You cannot update Build #${id}.`,
+    failureMessage: "Failed to update the Build description.",
+  });
+  console.log(
+    description
+      ? `Updated description for ${formatBuildTitle(updatedBuild)}.`
+      : `Cleared description for ${formatBuildTitle(updatedBuild)}.`,
+  );
+}
+
+async function updateOwnedBuildDetails({
+  options,
+  patch,
+  permissionError,
+  failureMessage,
+}) {
   const auth = await ensureAuth(options);
   await assertAuthScope({ options, auth, scope: "build:write" });
   const localProject = await findLocalProjectMetadata(
@@ -249,21 +299,21 @@ export async function renameBuild(options) {
   });
   const currentBuild = await loadBuildMetadata({ options, auth, buildId });
   if (currentBuild.canWrite === false) {
-    throw new Error(`You cannot rename Build #${buildId}.`);
+    throw new Error(permissionError(buildId));
   }
   if (Number(currentBuild.contributionRootBuildId || 0) > 0) {
     throw new Error(
-      "Contribution branches use the original Build title and cannot be renamed.",
+      "Contribution branches use the original Build details and cannot change them.",
     );
   }
   const result = await updateBuildMetadata({
     options,
     auth,
     buildId,
-    patch: { title },
+    patch,
   });
   if (result?.success !== true || !result?.build) {
-    throw new Error(result?.error || "Failed to rename the Build.");
+    throw new Error(result?.error || failureMessage);
   }
   const updatedBuild = { ...currentBuild, ...result.build };
   await saveSelectedBuild({ options, auth, build: updatedBuild });
@@ -282,7 +332,7 @@ export async function renameBuild(options) {
       filesHash: localProject.metadata.filesHash || null,
     });
   }
-  console.log(`Renamed Build #${buildId} to "${updatedBuild.title}".`);
+  return { buildId, updatedBuild };
 }
 
 export async function workspace(options) {
@@ -337,6 +387,262 @@ export async function branches(options) {
   printContributionBranches({ result, rootBuild, options });
 }
 
+export async function sendSuggestion(options) {
+  const suggestionType = String(options.suggestionAction || "").trim();
+  if (suggestionType !== "branch" && suggestionType !== "thumbnail") {
+    throw new Error(
+      "Usage: lumine suggest branch [--note <message>] | lumine suggest thumbnail",
+    );
+  }
+  const auth = await resolveAuth(options);
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const build = await loadTargetBuildMetadata({ options, auth });
+  const { rootBuildId, contributionBuildId } =
+    resolveContributionActionBuildIds(build);
+
+  if (suggestionType === "branch") {
+    await notifyBuildOwnerOfContribution({
+      options,
+      auth,
+      rootBuildId,
+      contributionBuildId,
+      note: options.note,
+    });
+    console.log(
+      `Sent branch #${contributionBuildId} to the owner of Build #${rootBuildId} for review.`,
+    );
+    return;
+  }
+
+  await suggestBuildThumbnailToOwner({
+    options,
+    auth,
+    rootBuildId,
+    contributionBuildId,
+  });
+  console.log(
+    `Suggested branch #${contributionBuildId}'s thumbnail to the owner of Build #${rootBuildId}.`,
+  );
+}
+
+export async function suggestions(options) {
+  const auth = await resolveAuth(options);
+  const rootBuildId = await resolveSuggestionRootBuildId(options, auth);
+  const action = String(options.suggestionAction || "list");
+  const requestedSuggestionId = Number(options.suggestionId || 0);
+  if (
+    action !== "list" &&
+    (!Number.isSafeInteger(requestedSuggestionId) || requestedSuggestionId <= 0)
+  ) {
+    throw new Error(
+      `Pass a suggestion ID: lumine suggestions ${action} <suggestion-id>`,
+    );
+  }
+  const result = await listBuildSuggestions({
+    options,
+    auth,
+    rootBuildId,
+    cursor: action === "list" ? options.cursor : 0,
+    suggestionId: action === "list" ? 0 : requestedSuggestionId,
+  });
+  const items = Array.isArray(result?.suggestions) ? result.suggestions : [];
+
+  if (action === "list") {
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          buildId: rootBuildId,
+          suggestions: items,
+          hasMore: Boolean(result?.hasMore),
+          nextCursor: Number(result?.nextCursor || 0) || null,
+        }),
+      );
+      return;
+    }
+    printBuildSuggestions({
+      rootBuildId,
+      suggestions: items,
+      hasMore: Boolean(result?.hasMore),
+      nextCursor: Number(result?.nextCursor || 0),
+    });
+    return;
+  }
+
+  const suggestionId = requestedSuggestionId;
+  const suggestion = items.find(
+    (item) => Number(item?.id || 0) === suggestionId,
+  );
+  if (!suggestion) {
+    throw new Error(
+      `Open suggestion #${suggestionId} was not found for Build #${rootBuildId}. Run \`lumine suggestions --build ${rootBuildId}\` to refresh the inbox.`,
+    );
+  }
+  await assertAuthScope({ options, auth, scope: "build:write" });
+  const contributionBuildId = Number(suggestion.branchBuildId || 0);
+  if (!contributionBuildId) {
+    throw new Error(`Suggestion #${suggestionId} has no active branch.`);
+  }
+
+  if (action === "merge") {
+    if (suggestion.type !== "branch") {
+      throw new Error(`Suggestion #${suggestionId} is not a branch suggestion.`);
+    }
+    const mergeResult = await mergeContributionIntoMain({
+      options,
+      auth,
+      rootBuildId,
+      contributionBuildId,
+    });
+    printContributionActionResult({
+      action: "Merged",
+      result: mergeResult,
+      rootBuildId,
+      contributionBuildId,
+    });
+    return;
+  }
+
+  if (action === "replace-main") {
+    if (suggestion.type !== "branch") {
+      throw new Error(`Suggestion #${suggestionId} is not a branch suggestion.`);
+    }
+    const replaceResult = await replaceMainWithContribution({
+      options,
+      auth,
+      rootBuildId,
+      contributionBuildId,
+    });
+    printContributionActionResult({
+      action: "Replaced main with",
+      result: replaceResult,
+      rootBuildId,
+      contributionBuildId,
+    });
+    return;
+  }
+
+  if (action === "adopt-thumbnail") {
+    if (suggestion.type !== "thumbnail") {
+      throw new Error(
+        `Suggestion #${suggestionId} is not a thumbnail suggestion.`,
+      );
+    }
+    if (suggestion.currentThumbnailUrl && !options.assumeYes) {
+      const confirmed = await confirmPrompt(
+        `Replace Build #${rootBuildId}'s thumbnail with suggestion #${suggestionId}? [y/N] `,
+      );
+      if (confirmed === null) {
+        console.log("Not a TTY — re-run with --yes to replace the thumbnail.");
+        return;
+      }
+      if (!confirmed) {
+        console.log("Aborted. Thumbnail unchanged.");
+        return;
+      }
+    }
+    const adoptResult = await adoptBuildThumbnailSuggestion({
+      options,
+      auth,
+      rootBuildId,
+      contributionBuildId,
+      suggestionMessageId: suggestionId,
+      thumbnailUrl: suggestion.suggestedThumbnailUrl,
+    });
+    const canonicalThumbnailUrl = String(
+      adoptResult?.build?.thumbnailUrl || "",
+    );
+    console.log(
+      `Applied thumbnail suggestion #${suggestionId} to Build #${rootBuildId}.`,
+    );
+    if (canonicalThumbnailUrl) console.log(`  ${canonicalThumbnailUrl}`);
+    return;
+  }
+
+  throw new Error(
+    "Usage: lumine suggestions [build] | lumine suggestions merge|replace-main|adopt-thumbnail <suggestion-id> [--build <id>]",
+  );
+}
+
+async function resolveSuggestionRootBuildId(options, auth) {
+  const requestedBuildId = options.buildIdFlag
+    ? resolveRequiredBuildId(options.buildIdFlag)
+    : await resolveRequiredBuildIdOrSelected(options, auth);
+  const build = await loadBuildMetadata({
+    options,
+    auth,
+    buildId: requestedBuildId,
+  });
+  return (
+    Number(build?.contributionRootBuildId || 0) || Number(build?.id || 0)
+  );
+}
+
+export function printBuildSuggestions({
+  rootBuildId,
+  suggestions,
+  hasMore = false,
+  nextCursor = 0,
+}) {
+  console.log(`Open suggestions for Build #${rootBuildId}:`);
+  if (!suggestions.length) {
+    console.log(
+      hasMore
+        ? "No open branch or thumbnail suggestions on this page."
+        : "No open branch or thumbnail suggestions.",
+    );
+    if (hasMore && nextCursor > 0) {
+      console.log(
+        `Next page: lumine suggestions --build ${rootBuildId} --cursor ${nextCursor}`,
+      );
+    }
+    return;
+  }
+  for (const suggestion of suggestions) {
+    const suggestionId = Number(suggestion.id || 0);
+    const branchNumber = Number(suggestion.branchNumber || 0);
+    const branchLabel = branchNumber
+      ? `branch ${branchNumber}`
+      : `branch #${suggestion.branchBuildId}`;
+    const contributor = suggestion.contributorUsername || "a contributor";
+    const createdAt = formatVersionTimestamp(suggestion.createdAt);
+    if (suggestion.type === "branch") {
+      console.log(
+        `[#${suggestionId}] ${contributor} submitted ${branchLabel} (${createdAt})`,
+      );
+      if (suggestion.note) console.log(`  ${suggestion.note}`);
+      const summary = suggestion.diffSummary || {};
+      console.log(
+        `  files: ${Number(summary.total || suggestion.changedFiles?.length || 0)} changed`,
+      );
+      if (suggestion.hasNewerWorkSinceSubmission) {
+        console.log("  note: the branch changed after this suggestion");
+      }
+      console.log(
+        `  merge: lumine suggestions merge ${suggestionId} --build ${rootBuildId}`,
+      );
+      console.log(
+        `  replace: lumine suggestions replace-main ${suggestionId} --build ${rootBuildId}`,
+      );
+      continue;
+    }
+    console.log(
+      `[#${suggestionId}] ${contributor} suggested a thumbnail from ${branchLabel} (${createdAt})`,
+    );
+    console.log(`  ${suggestion.suggestedThumbnailUrl}`);
+    if (suggestion.hasNewerThumbnailSinceSuggestion) {
+      console.log("  note: the branch has a newer thumbnail now");
+    }
+    console.log(
+      `  apply: lumine suggestions adopt-thumbnail ${suggestionId} --build ${rootBuildId}`,
+    );
+  }
+  if (hasMore && nextCursor > 0) {
+    console.log(
+      `Next page: lumine suggestions --build ${rootBuildId} --cursor ${nextCursor}`,
+    );
+  }
+}
+
 export async function explore(options) {
   const auth = await resolveAuth(options);
   const builds = await listOpenSourceBuilds({ options, auth });
@@ -1557,9 +1863,15 @@ export function printPullResult(result) {
   );
   console.log('Save after edits: lumine save --summary "Describe the change"');
   if (isContributionBranch(build) && build.canPublish === false) {
-    console.log("The project owner can merge or replace main from Twinkle.");
+    console.log(
+      'Notify the owner when ready: lumine suggest branch "Ready for review"',
+    );
+    console.log(
+      "Offer this branch's thumbnail: lumine suggest thumbnail",
+    );
   } else {
     console.log("Run `lumine check` or `lumine launch --save` when ready.");
+    console.log("Review team nudges: lumine suggestions");
   }
 }
 
@@ -1616,12 +1928,16 @@ export function printSaveResult({ result, build, dir, files }) {
   console.log(`Release status: ${releaseState}`);
   if (isContributionBranch(build) && build.canPublish === false) {
     console.log(
-      "Next: the project owner can merge or replace main from Twinkle.",
+      'Next: notify the project owner with `lumine suggest branch "Ready for review"`.',
+    );
+    console.log(
+      "To offer this branch's thumbnail, run `lumine suggest thumbnail`.",
     );
   } else {
     console.log(
       "Next: run `lumine launch` to publish, or `lumine save --publish` next time.",
     );
+    console.log("Team suggestions: run `lumine suggestions` to review them.");
   }
 }
 
@@ -1791,14 +2107,55 @@ export function parseArgs(args) {
     } else if (booleanFlags.has(camelKey)) {
       raw[camelKey] = true;
     } else {
-      raw[camelKey] = rest[i + 1] ?? "";
+      const nextValue = rest[i + 1];
+      if (
+        nextValue === undefined ||
+        nextValue === "-h" ||
+        nextValue.startsWith("--")
+      ) {
+        throw new Error(`Missing value for --${key}.`);
+      }
+      raw[camelKey] = nextValue;
       i += 1;
     }
   }
 
+  const suggestionInboxActions = new Set([
+    "list",
+    "merge",
+    "replace-main",
+    "adopt-thumbnail",
+  ]);
+  const suggestionAction =
+    command === "suggest"
+      ? String(positional[0] || "")
+      : command === "suggestions" &&
+          suggestionInboxActions.has(String(positional[0] || ""))
+        ? String(positional[0])
+        : "list";
+  const suggestionListTarget =
+    command === "suggestions" && suggestionAction === "list"
+      ? String(
+          positional[0] === "list" ? positional[1] || "" : positional[0] || "",
+        )
+      : "";
+
   return {
     command,
     positional,
+    suggestionAction,
+    suggestionId:
+      command === "suggestions" && suggestionAction !== "list"
+        ? String(positional[1] || "")
+        : "",
+    note:
+      String(
+        raw.note ||
+          (command === "suggest" && suggestionAction === "branch"
+            ? positional.slice(1).join(" ")
+            : ""),
+      ).trim() || "",
+    cursor: Math.max(0, Math.floor(Number(raw.cursor) || 0)),
     repeat: Math.min(Math.max(Math.floor(Number(raw.repeat) || 1), 1), 20),
     allowWrite: parseBoolean(raw.allowWrite, false),
     assumeYes: parseBoolean(raw.yes, false),
@@ -1815,7 +2172,13 @@ export function parseArgs(args) {
     target:
       raw.url ||
       raw.target ||
-      (command === "rename" ? "" : positional[0] || ""),
+      (command === "rename" ||
+        command === "describe" ||
+        command === "suggest"
+        ? ""
+        : command === "suggestions"
+          ? suggestionListTarget
+          : positional[0] || ""),
     title:
       String(
         raw.title ||
@@ -1825,11 +2188,12 @@ export function parseArgs(args) {
       ).trim() || "",
     description: Object.prototype.hasOwnProperty.call(raw, "description")
       ? String(raw.description || "").trim()
-      : null,
-    descriptionProvided: Object.prototype.hasOwnProperty.call(
-      raw,
-      "description",
-    ),
+      : command === "describe" && positional.length > 0
+        ? positional.join(" ").trim()
+        : null,
+    descriptionProvided:
+      Object.prototype.hasOwnProperty.call(raw, "description") ||
+      (command === "describe" && positional.length > 0),
     noDescription: parseBoolean(raw.noDescription, false),
     searchQuery:
       String(
@@ -2009,6 +2373,32 @@ export async function resolveNewBuildDescription(options) {
   }
 }
 
+export async function resolveBuildDescriptionUpdate(options) {
+  if (options.noDescription && options.descriptionProvided) {
+    throw new Error(
+      "Pass either a description or `--no-description`, not both.",
+    );
+  }
+  if (options.noDescription) return null;
+  if (options.descriptionProvided) {
+    return String(options.description || "").trim() || null;
+  }
+  if (!input.isTTY || !output.isTTY) {
+    throw new Error(
+      'Pass a description: `lumine describe "What this app does"`, or clear it with `lumine describe --no-description`.',
+    );
+  }
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question(
+      "Build description (leave blank to clear): ",
+    );
+    return String(answer || "").trim() || null;
+  } finally {
+    rl.close();
+  }
+}
+
 export async function resolveBuildReferenceBuildId({
   options,
   auth,
@@ -2042,8 +2432,15 @@ export function printHelp() {
   lumine logout
   lumine new [title]
   lumine rename [title] [--target <twinkle-build-url-or-id>]
+  lumine describe [description] [--target <twinkle-build-url-or-id>]
   lumine projects
   lumine branches [twinkle-build-url-or-id] [--limit <n>]
+  lumine suggest branch [message] [--target <twinkle-branch-url>]
+  lumine suggest thumbnail [--target <twinkle-branch-url>]
+  lumine suggestions [twinkle-build-url-or-id]
+  lumine suggestions merge <suggestion-id> [--build <id>]
+  lumine suggestions replace-main <suggestion-id> [--build <id>]
+  lumine suggestions adopt-thumbnail <suggestion-id> [--build <id>] [--yes]
   lumine explore [search terms]
   lumine select [twinkle-build-url]
   lumine pull [twinkle-build-url]
@@ -2078,8 +2475,15 @@ Examples:
   npx @stage5/lumine@latest new "Daily Reflection App"
   npx @stage5/lumine@latest rename "My New Build Title"
   npx @stage5/lumine@latest rename "New Title" --target 123
+  npx @stage5/lumine@latest describe "A welcoming place to build together"
+  npx @stage5/lumine@latest describe --no-description --target 123
   npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Private journal with streaks"
   npx @stage5/lumine@latest branches 884
+  npx @stage5/lumine@latest suggest branch "Ready for review"
+  npx @stage5/lumine@latest suggest thumbnail
+  npx @stage5/lumine@latest suggestions 884
+  npx @stage5/lumine@latest suggestions merge 12345 --build 884
+  npx @stage5/lumine@latest suggestions adopt-thumbnail 12346 --build 884 --yes
   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
@@ -2113,13 +2517,15 @@ Options:
   --auth-file <path>    Saved login path
   --auth-token <token>  Override saved login
   --dir <path>          Directory for pulled project files
-  --target <build>      Explicit Build URL or ID for rename (positionals are title-only)
+  --target <build>      Explicit Build URL or ID for rename/describe
   --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>        Build title for new/rename
-  --description <text>  Optional New Build description
-  --no-description      Skip the New Build description prompt
+  --description <text>  Build description for new/describe
+  --no-description      Skip New description or clear with describe
   --summary <text>      Save summary
+  --note <text>         Message attached to a branch suggestion
+  --cursor <id>         Continue an owner suggestion inbox listing
   --force               Overwrite server files even if this workspace is stale or missing filesHash
   --search <text>       Search public open-source Builds
   --sort <sort>         Sort open-source Builds: forks, popular, recent
@@ -2128,7 +2534,7 @@ 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/thumbnail calls outside a workspace
+  --build <id>          Build id for sdk/assets/thumbnail/suggestion 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

package/lib/constants.js

@@ -118,7 +118,7 @@ Use these current source-of-truth rules:
 - Use Twinkle.sharedDb for shared multi-user JSON data.
 - Use Twinkle.aiCards.list/search/get for existing public AI Card words, exampleText sentence material, and word levels.
 - Use Twinkle.aiStories.list/search/get for existing AI Story passage text, story media, and questions.
-- Use Twinkle.ai.chat with history entries shaped as { role, content }, not { text }.
+- Use Twinkle.ai.chat with history entries shaped as { role, content }, not { text }. Live web search is enabled by default; pass webSearch: false to disable it for the app.
 - Use Twinkle.preview for canvas, WebGL, Three.js, fullscreen, and game layout.
 - Prefer existing documented Twinkle.* methods over guessing names from old code.
 `;
@@ -170,6 +170,16 @@ lumine save --summary "Describe the change"
   need --allow-write and mutate real app data.
 - Owned canonical builds may be published only when the user explicitly asks.
 
+## Team Suggestions
+
+- After saving contribution-branch work, use \`lumine suggest branch "Ready for review"\`
+  when the user wants to notify the project owner. Use \`lumine suggest thumbnail\`
+  when the branch's current thumbnail should be offered to the owner.
+- On an owned canonical team project, \`lumine suggestions\` lists the owner's
+  currently open branch and thumbnail suggestions. Act on the exact suggestion
+  id it prints with \`lumine suggestions merge\`, \`replace-main\`, or
+  \`adopt-thumbnail\`; do not infer an action from stale local branch state.
+
 ## Assets (Runtime Media)
 
 - Binary files are NOT project files. Never place bundled media in this
@@ -326,8 +336,11 @@ export const COMMANDS = new Set([
   "whoami",
   "new",
   "rename",
+  "describe",
   "projects",
   "branches",
+  "suggest",
+  "suggestions",
   "explore",
   "select",
   "pull",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "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.27.0
-Updated: 2026-07-21
-Generated: 2026-07-23T05:57:27.486Z
+Version: 1.32.0
+Updated: 2026-08-02
+Generated: 2026-08-02T03:03:30.002Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -12,6 +12,7 @@ Generated: 2026-07-23T05:57:27.486Z
 - Match storage to update frequency: privateDb and sharedDb are for LOW-frequency durable state that changes on a user action. NEVER write per-frame/per-tick state to them (camera or cursor position, animation, live movement, presence, autosave every frame/tick). Keep live state in client memory, broadcast realtime/presence via Twinkle.world, and flush only occasional durable snapshots (on an interval or on exit, never per frame). The server enforces per-key write rate limits and returns 429 on excess; never retry-loop a 429.
 - Use Twinkle.userDb only for advanced private SQLite needs such as tables, indexes, many rows, filtered queries, or aggregates.
 - Use Twinkle.leaderboards for public Build scoreboards. Signed-in viewers are ranked by Twinkle username; guests can submit with a display name.
+- Use Twinkle.news to read the globally shared Twinkle Daily edition, browse canonical daily archives and preserved successful press runs, or let a signed-in viewer queue today's edition. The server permits only one canonical edition per Twinkle day for ordinary viewers. In the canonical Twinkle Newspaper app, its current owner may explicitly refresh today's ready edition, appending a revision while keeping the newest successful press run canonical. A model-backed edition consumes AI Energy from the signed-in viewer whose request creates, retries, or refreshes that job; deduplicated observers and quiet editions with no editorial model call do not consume Energy.
 - Use Twinkle.sharedDb for LOW-frequency durable shared multi-user state such as guestbooks, votes, room settings, submitted records, and append-only run history. It is NOT for high-frequency or per-frame/per-tick writes; keep live/realtime state in Twinkle.world or client memory. The server rate-limits writes and returns 429.
 - Use Twinkle.subjects.search for in-app subject pickers. Twinkle.mount remains an optional host-provided preselection/context shortcut, not a data API.
 - Use Twinkle.aiCards for read-only existing public AI Card words and example texts, including word levels for typing games.
@@ -21,6 +22,7 @@ Generated: 2026-07-23T05:57:27.486Z
 - Use Twinkle.world for realtime multiplayer rooms, avatar presence, movement, emotes, and lightweight actions; world sessions are disposable and durable MMO state belongs in sharedDb/privateDb.
 - Use Twinkle.characters.chat for real Zero/Ciel NPC dialogue with shared room context and AI Energy-aware thinking modes.
 - Twinkle.ai.chat history entries must use { role, content }; map local message.text fields to content before passing history.
+- Live web search is enabled by default for Twinkle.ai.chat and for Medium/High Twinkle.ai.generateObject and Twinkle.characters.chat requests. App authors can pass webSearch: false to disable it for their app. Search uses the provider's live web-search tool and is included in AI Energy usage; structured and character Lite Mode remains tool-free.
 - Interface text must not be selectable on touch devices: apply user-select: none plus -webkit-user-select: none and -webkit-touch-callout: none to interface text (HUD, buttons, labels, menus, scores, game controls) so mobile long-press does not highlight UI. Keep text inputs and genuinely user-copyable content selectable.
 - Build app tab mute is enforced by the host runtime automatically for standard media elements and Web Audio connections to AudioContext.destination. Apps with custom audio engines can also observe Twinkle.onAudioMuteChange and check Twinkle.isAudioMuted.
 
@@ -281,31 +283,34 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
 - async listPrompts() | scopes: none
   - Returns: Array<{ id, title, description }>
   - Legacy helper. Twinkle.ai.chat does not require promptId for default runtime text generation.
-- async chat({ promptId, message, history, systemPrompt, requestId, onText, onStatus } = {}) | scopes: none
-  - Returns: { text, response, model, aiUsagePolicy }
-  - Generate text with the default Lumine text model, optionally streaming text updates through onText.
+- async chat({ promptId, message, history, systemPrompt, webSearch, requestId, onText, onStatus } = {}) | scopes: none
+  - Returns: { text, response, model, webSearch, aiUsagePolicy }
+  - Generate text with the default Lumine text model, optionally using live web search and streaming text updates through onText.
   - Signed-in viewers only.
   - Uses Grok 4.5 by default.
   - Each successful text generation consumes AI Energy from the signed-in viewer.
   - history must be an array of { role: 'user' | 'assistant', content: string }. Twinkle.ai.chat does not read a text field.
   - The server keeps the latest 12 valid history entries.
   - Pass systemPrompt to define the app AI's personality, tone, role, or response rules.
+  - Live web search is enabled by default, and the model decides whether searching is useful. Pass webSearch: false to disable it for the app.
+  - When streaming, onStatus may receive searching_web while the provider is searching.
   - Pass onText to receive streaming accumulated text before the final result resolves.
-  - AI Energy is recorded after provider success when final token usage is available.
+  - AI Energy is recorded after provider success when final token and web-search tool usage are available.
   - Use this for in-app AI replies instead of creating or fetching app-local endpoints such as /api/chat.
   - Example: const chatHistory = conversation.slice(-12).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text }));
 const result = await Twinkle.ai.chat({ message, history: chatHistory, systemPrompt: 'You are a cheerful pirate helper who answers in one sentence.', onText: (text, meta) => renderReply(text), onStatus: (status) => setThinking(status === 'thinking') });
-- async generateObject({ prompt, expectedStructure, thinkingMode, mode, instructions, systemPrompt } = {}) | scopes: none
-  - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, aiUsagePolicy }
-  - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic.
+- async generateObject({ prompt, expectedStructure, thinkingMode, mode, instructions, systemPrompt, webSearch } = {}) | scopes: none
+  - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, webSearch, aiUsagePolicy }
+  - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic, optionally using live web search.
   - Signed-in viewers only.
   - Use this instead of asking Twinkle.ai.chat to return JSON.
   - expectedStructure must be a JSON object that describes the exact returned object shape.
   - mode is accepted as an alias for thinkingMode, and mid is accepted as an alias for medium.
-  - thinkingMode low uses GPT-5.6 Luna and records free low-energy usage.
-  - thinkingMode medium uses GPT-5.6 Luna and normal AI Energy while AI Energy remains.
-  - thinkingMode high uses Grok 4.5 with high reasoning and high AI Energy while AI Energy remains.
-  - If medium or high is requested after AI Energy is empty, the server falls back to low and returns thinkingMode: low.
+  - thinkingMode low uses GPT-5.6 Luna and consumes the viewer's AI Energy from confirmed provider usage; its smaller model is usually cheaper than Medium or High.
+  - thinkingMode medium uses Grok 4.5 with medium reasoning and consumes normal AI Energy.
+  - thinkingMode high uses GPT-5.6 Sol with high reasoning and consumes high AI Energy.
+  - When AI Energy is empty, Low, Medium, and High all reject before new provider work; there is no free fallback mode.
+  - Live web search is enabled by default in Medium and High modes. Pass webSearch: false to disable it for the app. Low/Lite Mode remains tool-free; explicitly forcing webSearch: true in Low Mode returns an error.
   - The SDK validates shape and retries malformed JSON, but app code should still validate business-specific enum values.
   - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'medium', prompt: 'Classify the player intent from: ' + playerText, expectedStructure: { action: 'string', targetCharacter: 'string', confidence: 0, shouldAskFollowUp: false } });
 - onChatStatus(listener) | scopes: none
@@ -337,21 +342,24 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Example: const unsubscribe = Twinkle.ai.onImageGenerationStatus((status) => console.log(status.stage));
 
 ### Twinkle.characters
-- async chat({ character, thinkingMode, message, history, roomContext, scene, systemPrompt, instructions, includeWebsiteContext, requestId, onText, onStatus } = {}) | scopes: none
-  - Returns: { text, response, character, aiUsername, thinkingMode, requestedThinkingMode, includeWebsiteContext, model, provider, aiUsagePolicy }
-  - Talk to Zero or Ciel from a Build app, either as a final-response call or streaming RPG-style dialogue text with onText/onStatus.
+- async chat({ character, thinkingMode, message, history, roomContext, scene, systemPrompt, instructions, includeWebsiteContext, webSearch, requestId, onText, onStatus } = {}) | scopes: none
+  - Returns: { text, response, character, aiUsername, thinkingMode, requestedThinkingMode, includeWebsiteContext, webSearch, model, provider, aiUsagePolicy }
+  - Talk to Zero or Ciel from a Build app, optionally using live web search and streaming RPG-style dialogue text with onText/onStatus.
   - Signed-in viewers only.
   - character must be zero or ciel.
   - Recommended history shape is { role: 'user' | 'assistant', content: string, speaker?: string }; content is the canonical text field.
   - The character route also accepts text or message fields for compatibility, but generated apps should use content.
   - The server keeps the latest 16 valid character history entries.
   - Pass onText/onStatus for streaming dialogue. Omit callbacks for non-streaming dialogue where the promise resolves with the final response.
-  - thinkingMode low uses Lite Mode: Zero uses Grok 4.5 with low reasoning and Ciel uses Claude Haiku 4.5; usage is recorded as free low-energy usage.
-  - thinkingMode medium uses normal AI Energy: Zero uses Grok 4.5 with medium reasoning and Ciel uses Claude Sonnet 5 while AI Energy remains.
-  - thinkingMode high uses high AI Energy: Zero uses Grok 4.5 with high reasoning and Ciel uses Claude Opus 4.8 with extended thinking while AI Energy remains.
-  - If medium or high is requested after AI Energy is empty, the server falls back to low and returns thinkingMode: low.
+  - thinkingMode low uses Lite Mode: Zero uses Grok 4.5 with low reasoning and Ciel uses Claude Haiku 4.5; confirmed provider usage consumes the viewer's AI Energy and is usually cheaper than Medium or High.
+  - thinkingMode medium consumes normal AI Energy: Zero uses Grok 4.5 with medium reasoning and Ciel uses Claude Sonnet 5.
+  - thinkingMode high consumes high AI Energy: Zero uses Grok 4.5 with high reasoning and Ciel uses Claude Opus 5 with extended thinking.
+  - When AI Energy is empty, Low, Medium, and High all reject before new provider work; there is no free fallback mode.
   - Pass roomContext as a short shared scene transcript so Zero and Ciel can know what happened in the same room.
   - includeWebsiteContext defaults to true. Set includeWebsiteContext: false for in-world NPC dialogue that should only use Zero/Ciel's basic character identity plus your scene/instructions.
+  - Live web search is enabled by default in Medium and High modes. Pass webSearch: false to disable it for the app. Low/Lite Mode remains tool-free; explicitly forcing webSearch: true in Low Mode returns an error.
+  - includeWebsiteContext controls Twinkle persona context and is unrelated to webSearch.
+  - When streaming, onStatus may receive searching_web while the provider is searching.
   - Use this for real Zero/Ciel NPCs instead of pretending with Twinkle.ai.chat systemPrompt.
   - Example: const dialogueHistory = recentTurns.slice(-16).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text, speaker: entry.speaker }));
 const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode: thinkHard ? 'high' : 'medium', message: playerText, history: dialogueHistory, roomContext, scene: { location: 'classroom', nearbyCharacters: ['zero', 'ciel'] }, includeWebsiteContext: false, onText: (text) => renderDialogue(text) });
@@ -519,6 +527,38 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Atomic step 3: fetches likes/replies aggregates for provided IDs.
   - Accepts either an array of IDs or an object like { ids: [...] }.
 
+### Twinkle.news
+- async getCurrentEdition() | scopes: none
+  - Returns: { dayIndex, nextEditionAt, generationStatus, edition: { id, dayIndex, status, coverageStartedAt, coverageEndedAt, sourceEventCount, edition, model, provider, generatedAt, revisionNumber, revisionCount } | null, pendingEdition }
+  - Read today's shared Twinkle newspaper, or the latest ready edition while today's is being generated.
+  - Works for signed-in viewers and public-build guests.
+  - generationStatus is available, pending, generating, ready, or failed.
+  - While today's first edition is pending, edition remains the latest ready shared edition. During an owner refresh, edition remains the earlier same-day edition. pendingEdition describes the canonical queued work in both cases.
+  - Poll gently while generation is pending; once every 5-10 seconds is sufficient.
+- async listEditions({ limit = 12, cursor } = {}) | scopes: none
+  - Returns: { editions: [{ id, dayIndex, dateKey, headline, deck, coverageStartedAt, coverageEndedAt, sourceEventCount, generatedAt, revisionNumber, revisionCount }], cursor, hasMore }
+  - List the canonical daily newspaper archive newest-first.
+  - Works for signed-in viewers and public-build guests.
+  - Returns compact publication summaries rather than full newspaper JSON.
+  - limit defaults to 12 and is capped at 30. Pass cursor from the previous response to load older editions.
+  - Each item describes the latest canonical revision for that Twinkle day.
+- async getEdition({ dayIndex, revisionNumber } = {}) | scopes: none
+  - Returns: { edition: { id, revisionId?, dayIndex, status, coverageStartedAt, coverageEndedAt, sourceEventCount, edition, model, provider, generatedAt, revisionNumber, revisionCount }, revisions: [{ revisionId, revisionNumber, coverageStartedAt, coverageEndedAt, sourceEventCount, model, provider, generatedAt, createdAt }], selectedRevisionNumber, canonicalRevisionNumber }
+  - Read one canonical daily edition or an exact preserved successful press run.
+  - Works for signed-in viewers and public-build guests.
+  - dayIndex is required. Omit revisionNumber to read that day's latest canonical edition.
+  - Pass a revisionNumber returned in revisions to read that exact successful press run.
+  - Historical revisions remain subject to canonical privacy and deletion redactions.
+- async generateCurrentEdition({ refresh = false } = {}) | scopes: none
+  - Returns: { dayIndex, nextEditionAt, generationStatus, edition, pendingEdition }
+  - Atomically queue the current Twinkle day's globally shared edition.
+  - Requires a signed-in viewer.
+  - The first request for a Twinkle day creates the canonical pending edition; concurrent and later ordinary requests return that same server state.
+  - In the canonical Twinkle Newspaper app, its current owner may pass { refresh: true } to revise an already-ready same-day edition using the latest canonical events. Every successful refresh is appended as a preserved press run and becomes that day's canonical revision. Ownership is checked by the server at request time and therefore follows an app transfer.
+  - When this request creates, retries, or refreshes a model-backed edition, confirmed provider usage consumes AI Energy from this requesting viewer. Concurrent or later callers that deduplicate onto the same pending or ready edition are not charged.
+  - A quiet edition with no editorial events does not call an AI provider and does not consume AI Energy.
+  - A failed attempt may be queued again on the same day. A ready edition is immutable for ordinary viewers.
+
 ### Twinkle.leaderboards
 - async get({ boardKey = 'default', limit, cursor } = {}) | scopes: none
   - Returns: { entries: [{ rank, id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt }], scores, cursor, hasMore, personalBest: { id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt } | null }