@stage5/lumine 0.2.17 → 0.2.19

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,
@@ -57,6 +65,7 @@ import {
 import { probeUrl, requestJson } from "./http.js";
 import { sdkCommand } from "./sdk.js";
 import { doctorCommand, normalizePreviewUrl } from "./doctor.js";
+import { adminCommand } from "./admin.js";
 import {
   defaultMainCheckoutDir,
   defaultReferenceDir,
@@ -100,10 +109,15 @@ export async function main() {
     printHelp();
     return;
   }
-  if (options.updateCheck) {
+  if (options.updateCheck && !(options.command === "admin" && options.json)) {
     await maybeCheckForLumineCliUpdate({ options });
   }
 
+  if (options.command === "admin") {
+    await adminCommand(options);
+    return;
+  }
+
   if (options.command === "workspace") {
     await workspace(options);
     return;
@@ -128,6 +142,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 +154,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 +265,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 +305,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 +338,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 +393,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 +1869,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 +1934,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.");
   }
 }
 
@@ -1772,6 +2094,8 @@ export function parseArgs(args) {
     "json",
     "keepAssets",
     "noBrowser",
+    "includeComments",
+    "anyoneCanReward",
   ]);
 
   for (let i = 0; i < rest.length; i += 1) {
@@ -1791,14 +2115,76 @@ 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)),
+    adminCursor: raw.cursor ? String(raw.cursor) : "",
+    adminAfter: raw.after ? String(raw.after) : "",
+    adminEffort: raw.effort ? String(raw.effort) : "",
+    adminLevel: raw.level ? String(raw.level) : "",
+    adminIds: raw.subjectIds
+      ? String(raw.subjectIds)
+      : raw.ids
+        ? String(raw.ids)
+        : "",
+    adminType: raw.type ? String(raw.type) : "",
+    adminKind: raw.kind ? String(raw.kind) : "",
+    adminIdentity: raw.identity ? String(raw.identity) : "",
+    commentMode: raw.commentMode ? String(raw.commentMode) : "",
+    runKey: raw.runKey ? String(raw.runKey) : "",
+    idempotencyKey: raw.idempotencyKey ? String(raw.idempotencyKey) : "",
+    draftId: raw.draftId ? String(raw.draftId) : "",
+    twinkles: raw.twinkles ? String(raw.twinkles) : "",
+    adminReason: raw.reason ? String(raw.reason) : "",
+    rewardTwinkles: raw.rewardTwinkles ? String(raw.rewardTwinkles) : "",
+    includeComments: parseBoolean(raw.includeComments, false),
+    anyoneCanReward: parseBoolean(raw.anyoneCanReward, false),
     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 +2201,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 +2217,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 +2402,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 +2461,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]
@@ -2071,6 +2497,21 @@ export function printHelp() {
   lumine thumbnail capture [--out <file>]
   lumine thumbnail generate ["<prompt>"] --model <gpt-image-2|nano-banana>
   lumine doctor runtime-assets
+  lumine admin identity list|status|use <zero|ciel|auto> [--json]
+  lumine admin daily-run start [--identity zero|ciel|auto] [--comment-mode off|draft|post] [--run-key <key>] [--json]
+  lumine admin daily-run status|complete|fail [--reason <text>] [--json]
+  lumine admin recommendations list [--cursor <cursor>] [--json]
+  lumine admin subjects candidates [--after <date>] [--effort unassigned] [--cursor <cursor>] [--json]
+  lumine admin subject get|comments|reveal <subject-url-or-id> [--cursor <cursor>] [--json]
+  lumine admin subject effort set <subject-id> --level <1|2|3> [--json]
+  lumine admin subject creator set-made-by-poster <subject-id> [--json]
+  lumine admin subject feature|unfeature <subject-id> [--json]
+  lumine admin featured list|reorder --subject-ids <id,id,...> [--json]
+  lumine admin post get|comments <target> [--type subject|comment|aiStory|dailyReflection] [--cursor <cursor>] [--json]
+  lumine admin post recommend <target> [--type subject|comment|aiStory|dailyReflection] [--anyone-can-reward] [--reward-twinkles 3] [--json]
+  lumine admin post reward <target> [--type subject|comment|aiStory|dailyReflection] --twinkles 3 [--json]
+  lumine admin comment draft <subject-id> [--identity zero|ciel|auto] [--json]
+  lumine admin comment post --draft-id <id> [--json]
 
 Examples:
   npx @stage5/lumine@latest
@@ -2078,8 +2519,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
@@ -2105,6 +2553,11 @@ Examples:
   npx @stage5/lumine@latest thumbnail capture --out capture.png
   npx @stage5/lumine@latest thumbnail generate --model gpt-image-2 --yes
   npx @stage5/lumine@latest doctor runtime-assets --build 917 --json
+  npx @stage5/lumine@latest admin daily-run start --identity auto --comment-mode off --json
+  npx @stage5/lumine@latest admin recommendations list --json
+  npx @stage5/lumine@latest admin subjects candidates --effort unassigned --json
+  npx @stage5/lumine@latest admin subject get 123 --include-comments --json
+  npx @stage5/lumine@latest admin post recommend comment:456 --anyone-can-reward --reward-twinkles 3 --json
 
 Options:
   --api-url <url>       Twinkle API origin
@@ -2113,13 +2566,30 @@ 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
+  --after <date>        Admin subjects: inclusive Unix/ISO creation boundary
+  --effort unassigned  Admin subjects: show only unassigned effort
+  --identity <mode>     Admin identity: zero, ciel, or auto
+  --comment-mode <mode> Admin run comments: off, draft, or post
+  --run-key <key>       Idempotency key for an admin daily run
+  --idempotency-key <k> Stable retry key for one admin mutation
+  --level <1|2|3>       Admin subject effort level
+  --subject-ids <ids>   Complete ordered Featured subject IDs
+  --type <type>         Admin target: subject, comment, aiStory, or dailyReflection
+  --kind recommend      Admin recommendation queue kind
+  --anyone-can-reward   Enable canonical reward eligibility
+  --reward-twinkles 3   Pair a recommendation with exactly 3 Twinkles
+  --twinkles 3          Give exactly 3 Twinkles through the normal economy
+  --draft-id <id>       Canonical delegated comment draft ID
+  --reason <text>       Reason when marking an admin run failed
   --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,12 +2598,12 @@ 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
   --scopes <a,b>        Override requested build API token scopes
-  --json                Print machine-readable output for doctor commands
+  --json                Print machine-readable output where supported
   --keep-assets         Keep doctor probe assets instead of deleting them
   --no-browser          Skip doctor browser probes
   --model <model>       Image model for generate: gpt-image-2 or nano-banana (required, no default)