@stage5/lumine 0.2.63 → 0.2.64

package/README.md

@@ -381,6 +381,8 @@ lumine admin featured list --json
 lumine admin subject feature 123 --json
 lumine admin subject unfeature 123 --json
 lumine admin featured reorder --subject-ids 30,20,10 --json
+lumine admin featured rotate --remove-subject-ids 30,20 \
+  --add-subject-ids 50,40 --json
 lumine admin brief --days 3 --json
 lumine admin notable add Minecrarft_guy --note "Created 8 thoughtful subjects and helped peers in 23 comments this window." --json
 lumine admin post recommend comment:456 --anyone-can-reward --reward-twinkles 3 --json

package/lib/admin.js

@@ -1333,6 +1333,9 @@ export function parseAdminOperation(options) {
     if (action === "reorder") {
       return featuredReorderOperation(options);
     }
+    if (action === "rotate") {
+      return featuredRotateOperation(options);
+    }
   }
 
   if (namespace === "comments" && action === "get") {
@@ -1862,6 +1865,7 @@ function legacySubjectsOperation({ action, target, options }) {
     );
   }
   if (action === "reorder") return featuredReorderOperation(options);
+  if (action === "rotate") return featuredRotateOperation(options);
   throw cliValidationError(
     `Unknown subjects action: ${action || "(missing)"}.`,
   );
@@ -1886,6 +1890,37 @@ function featuredReorderOperation(options) {
   );
 }
 
+function featuredRotateOperation(options) {
+  const removeIds = parseFeaturedSubjectIds(
+    options.adminRemoveIds,
+    "--remove-subject-ids",
+  );
+  const addIds = parseFeaturedSubjectIds(
+    options.adminAddIds,
+    "--add-subject-ids",
+  );
+  if (removeIds.length !== addIds.length) {
+    throw cliValidationError(
+      "Featured rotation requires the same number of removal and addition IDs.",
+    );
+  }
+  const removeSet = new Set(removeIds);
+  if (addIds.some((id) => removeSet.has(id))) {
+    throw cliValidationError(
+      "Featured rotation removal and addition IDs must not overlap.",
+    );
+  }
+  return writeOperation(
+    "featured.rotate",
+    "PUT",
+    "/cli/admin/subjects/featured/rotation",
+    {
+      removeIds,
+      addIds,
+    },
+  );
+}
+
 function recommendOperation(target, options) {
   const recommendationTarget = parseRecommendationTarget({
     target,
@@ -2259,18 +2294,24 @@ function parseTodoListStatus(value) {
 }
 
 function parseOrderedIds(value) {
+  return parseFeaturedSubjectIds(value, "--subject-ids", true);
+}
+
+function parseFeaturedSubjectIds(value, flag, completeList = false) {
   const ids = String(value || "")
     .split(",")
     .map((part) => part.trim())
     .filter(Boolean)
     .map((part) => parseRequiredInteger(part, "Featured subject ID", 1));
-  if (!String(value || "").trim()) {
+  if (!String(value || "").trim() || ids.length === 0) {
     throw cliValidationError(
-      "Pass the complete ordered list with --subject-ids <id,id,...>.",
+      completeList
+        ? "Pass the complete ordered list with --subject-ids <id,id,...>."
+        : `Pass at least one subject with ${flag} <id,id,...>.`,
     );
   }
   if (new Set(ids).size !== ids.length) {
-    throw cliValidationError("Featured subject IDs must be unique.");
+    throw cliValidationError(`${flag} subject IDs must be unique.`);
   }
   return ids;
 }

package/lib/commands.js

@@ -2436,6 +2436,16 @@ export function parseArgs(args) {
       : raw.ids
         ? String(raw.ids)
         : "",
+    adminRemoveIds: raw.removeSubjectIds
+      ? String(raw.removeSubjectIds)
+      : raw.removeIds
+        ? String(raw.removeIds)
+        : "",
+    adminAddIds: raw.addSubjectIds
+      ? String(raw.addSubjectIds)
+      : raw.addIds
+        ? String(raw.addIds)
+        : "",
     adminBucketId: raw.bucketId ? String(raw.bucketId) : "",
     adminLabel: raw.label ? String(raw.label) : "",
     adminUserIds: raw.userIds ? String(raw.userIds) : "",
@@ -2834,6 +2844,7 @@ export function printHelp() {
   lumine admin subject feature|unfeature <subject-id> [--json]
   lumine admin featured list [--unviewed|--viewed] [--json]
   lumine admin featured reorder --subject-ids <id,id,...> [--json]
+  lumine admin featured rotate --remove-subject-ids <id,id,...> --add-subject-ids <id,id,...> [--json]
   lumine admin post get <target> [--type subject|comment|aiStory|dailyReflection] [--json]
   lumine admin post comments <target> [--type subject|aiStory|dailyReflection] [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin post recommend <target> [--type subject|comment|aiStory|dailyReflection] [--anyone-can-reward] [--reward-twinkles 3] [--json]
@@ -2954,6 +2965,8 @@ Options:
   --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
+  --remove-subject-ids <ids> Featured subjects approved for rotation removal
+  --add-subject-ids <ids> Ordered replacement subjects for Featured rotation
   --bucket-id <id>      Unbanned AI identity bucket for account consolidation
   --label <name>        Name for a new unbanned AI identity bucket
   --user-ids <ids>      Explicit user IDs for an AI bucket batch (up to 500)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.63",
+  "version": "0.2.64",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/LUMINE_ADMIN.md

@@ -1202,6 +1202,8 @@ lumine admin subject feature 123 --json
 lumine admin subject unfeature 123 --json
 lumine admin featured list --json
 lumine admin featured reorder --subject-ids 30,20,10 --json
+lumine admin featured rotate --remove-subject-ids 30,20 \
+  --add-subject-ids 50,40 --json
 ```
 
 Schemas:
@@ -1238,6 +1240,17 @@ type SubjectFeature = FeaturedList & {
 
 type SubjectUnfeature = SubjectFeature;
 type FeaturedReorder = SubjectFeature;
+type FeaturedRotate = FeaturedList & {
+  status: "success" | "already_done";
+  changed: boolean;
+  data: FeaturedList["data"] & {
+    rotation: {
+      removeSubjectIds: number[];
+      addSubjectIds: number[];
+      finalSubjectIds: number[];
+    };
+  };
+};
 ```
 
 `reveal` publishes the existing hidden “viewed without responding” notification
@@ -1254,6 +1267,29 @@ unknown/deleted IDs, missing current members, non-subject rows, and more than
 20 subjects. Permanent pins and editorial ordering policy are deliberately not
 hardcoded.
 
+Featured rotate is the direct, atomic replacement verb for an approved
+rotation. `--remove-subject-ids` names the exact current members Mikey approved
+for removal; `--add-subject-ids` names the same number of replacements in
+descending editorial relevance. The API locks the canonical board, requires
+every removal to still be present and every addition to still be absent,
+validates every subject, then commits one complete-set replacement. Additions
+become the front of the board in the supplied order and all surviving members
+keep their relative order. A stale or partly mismatched plan fails without
+changing anything; an exact retry returns the canonical completed response.
+The response includes the canonical final board and the confirmed rotation
+IDs, so callers never synthesize Featured state locally.
+
+The two lists must have the same nonzero length, so rotation never changes the
+board's count. That also lets an approved swap proceed when the website has
+left a pre-existing board above the delegated maximum without growing it;
+repair the inherited overflow separately with an approved `subject unfeature`.
+
+This mutation deliberately does not choose candidates or override the
+editorial gates above. Before invoking it, the management agent must have
+freshly reviewed the board, shown Mikey the removals and replacements, received
+his go-ahead, and verified that every proposed new addition is recent and has
+never previously been Featured from canonical evidence.
+
 ## Recommendation, Karma approval, and Twinkle rewards
 
 ```bash
@@ -3004,6 +3040,9 @@ and indexes;
 there are no runtime schema checks. The comment-targets migration backfills
 existing subject drafts into the generalized target columns. The local CLI changes
 are not available to users until a separately authorized npm publication.
+Deploy and verify the API's `/cli/admin/subjects/featured/rotation` route before
+publishing a CLI release that exposes `featured rotate`; an older API rejects
+the command without changing Featured state.
 
 Legacy aliases such as `subjects list`, `subjects get`, `subjects featured`,
 `comments get`, and `recommend` remain accepted, but the singular command forms