@stage5/lumine 0.2.25 → 0.2.27

package/README.md

@@ -180,6 +180,7 @@ 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 brief --days 3 --json
 lumine admin post recommend comment:456 --anyone-can-reward --reward-twinkles 3 --json
 lumine admin post reward comment:456 --twinkles 3 --json
 lumine admin daily-run complete --json

package/lib/admin.js

@@ -12,6 +12,11 @@ const MAX_COMPOSED_COMMENT_LENGTH = 10_000;
 // its model and no AI Energy is spent.
 function readComposedCommentFile(filePath) {
   const normalizedPath = String(filePath || "").trim();
+  if (!normalizedPath) {
+    throw cliValidationError(
+      "Pass composed comment text with --file <comment.md>.",
+    );
+  }
   let contents;
   try {
     contents = readFileSync(normalizedPath, "utf8");
@@ -580,6 +585,19 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "brief" && !action) {
+    if (options.adminDays) {
+      const days = Number(options.adminDays);
+      if (!Number.isInteger(days) || days < 1 || days > 30) {
+        throw cliValidationError("--days must be an integer between 1 and 30.");
+      }
+    }
+    return readOperation(
+      "insights.brief",
+      withQuery("/cli/admin/insights/brief", { days: options.adminDays }),
+    );
+  }
+
   if (namespace === "audit" && (!action || action === "list")) {
     const runFilter = String(options.adminRun || "").trim();
     if (runFilter && !["current", "last"].includes(runFilter)) {
@@ -625,6 +643,30 @@ export function parseAdminOperation(options) {
         },
       );
     }
+    if (action === "edit") {
+      const rawTarget = String(target || "").trim();
+      let commentId;
+      if (/^\d+$/.test(rawTarget)) {
+        commentId = parseRequiredInteger(rawTarget, "comment id", 1);
+      } else {
+        const parsedTarget = parseRecommendationTarget({
+          target,
+          explicitType: options.adminType,
+        });
+        if (parsedTarget.type !== "comment") {
+          throw cliValidationError(
+            "comment edit targets a comment: lumine admin comment edit <commentId> --file <comment.md>.",
+          );
+        }
+        commentId = parsedTarget.id;
+      }
+      return writeOperation(
+        "comment.edit",
+        "PUT",
+        `/cli/admin/comments/${commentId}`,
+        { content: readComposedCommentFile(options.adminFile) },
+      );
+    }
     if (action === "post") {
       const draftId = parseRequiredInteger(
         options.draftId || target,
@@ -641,7 +683,7 @@ export function parseAdminOperation(options) {
   }
 
   throw cliValidationError(
-    "Usage: lumine admin identity|daily-run|recommendations|post|subjects|subject|featured|comment|news|audit ...",
+    "Usage: lumine admin identity|daily-run|recommendations|post|subjects|subject|featured|comment|news|audit|brief ...",
   );
 }
 

package/lib/commands.js

@@ -2188,6 +2188,7 @@ export function parseArgs(args) {
     adminTarget: raw.target ? String(raw.target) : "",
     adminActions: raw.actions ? String(raw.actions) : "",
     adminDate: raw.date ? String(raw.date) : "",
+    adminDays: raw.days ? String(raw.days) : "",
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
     adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
     adminFile: raw.file ? String(raw.file) : "",
@@ -2525,6 +2526,8 @@ export function printHelp() {
   lumine admin comment draft <target> [--type subject|comment|aiStory|dailyReflection] [--identity zero|ciel|auto] [--json]
   lumine admin comment reply comment:<id> [--identity zero|ciel|auto] [--json]
   lumine admin comment post --draft-id <id> [--json]
+  lumine admin comment edit <comment-id> --file <comment.md> [--json]
+  lumine admin brief [--days <1..30>] [--json]
   lumine admin audit [list] [--run current|last|<run-id>] [--target <target>] [--actions <a,b>] [--full] [--cursor <cursor>] [--json]
 
 Examples:
@@ -2605,6 +2608,7 @@ Options:
   --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
+  --file <path>         Editorial JSON or composed comment text file
   --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

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -1036,6 +1036,137 @@ type NewsClaim = Success<{
 type NewsSubmit = NewsStatus; // "success"; newspaper includes revisionNumber
 ```
 
+## Daily brief (management insights)
+
+```bash
+lumine admin brief --json
+lumine admin brief --days 3 --json
+```
+
+Read-only management insights for the delegated workflow, windowed since the
+operator's last completed run by default (`--days 1..30` overrides; capped at
+30 days). Call it early in every run — right after the newspaper check — and
+end every run report with an **"Insights for Mikey"** section carrying only
+the deltas and anomalies worth his time, next to the escalation list. Never
+dump raw sections at him.
+
+Four sections (Mikey's chosen cut, 2026-08-10):
+
+- `economy` — `topGainers` (coin-ledger aggregation over the window: gained,
+  spent, net, current balance per user, Zero/Ciel excluded) and `topBalances`
+  (current top-ten holders, also excluding Zero/Ciel). This is where
+  alt-account farming, sudden windfalls, and "someone got a million coins in a
+  week" surface with real numbers instead of secondhand kid gossip;
+  cross-check outliers against the
+  economy-manipulation escalation category.
+- `aiSpending` — a compact projection of the management AI-cost report:
+  `summary`, top spending accounts, top risk groups. Unlike the other sections'
+  exact `window.sinceTs`, this existing report is bucketed into whole UTC days;
+  `aiSpending.startDayIndex` and `endDayIndex` are its canonical bounds. The
+  report period can begin up to one day before or after the exact brief window,
+  so use those bounds when describing it. Flag accounts that jumped tiers or
+  dominate that report period. May be `{ unavailable: true }` if the cost
+  report fails; say so rather than guessing.
+- `notableCandidates` — kids (never bots, staff `userType`s, or users already
+  on the Notable Users list) ranked by authored activity in the window, with
+  `isNewUser` marking window-new signups. Use it to find the overlooked and
+  rising users the editorial priorities exist for, and propose additions to
+  Mikey's Notable Users list in the report — the run never edits that list
+  itself.
+- `teachers` — every `userType='supermod'` account with per-window
+  `subjectsPosted`, `commentsPosted`, `recommendationsGiven`, `rewardsGiven`,
+  `rewardTwinklesGiven`, `lastActive`/`daysSinceActive`, ordered by an
+  engagement score. Mikey's standing question here: which teachers genuinely
+  use the website to its fullest and which only work through it. Authored
+  posts and comments signal personal engagement; recommendations and rewards
+  are the "work" verbs — report the contrast, not just the totals, and treat
+  it as notable-users-but-for-teachers.
+
+The command needs only an active run's `content:read` scope and mutates
+nothing; reading the brief is not audited content action. Window boundaries
+on the big append-only ledgers are found by binary-searching the PRIMARY key
+(several tables have no timeStamp index), avoiding lifetime scans; aggregation
+is still bounded to the selected 1–30 day window.
+
+```ts
+type InsightsBrief = Success<{
+  window: {
+    sinceTs: number;
+    days: number;
+    source: 'requested' | 'since-last-completed-run' | 'default';
+    generatedAt: number;
+  };
+  economy: {
+    topGainers: Array<{
+      userId: number;
+      username: string | null;
+      userType: string | null;
+      gained: number;
+      spent: number;
+      net: number;
+      currentCoins: number;
+      joinedAt: number | null;
+    }>;
+    topBalances: Array<{
+      userId: number;
+      username: string | null;
+      userType: string | null;
+      coins: number;
+    }>;
+  };
+  notableCandidates: Array<{
+    userId: number;
+    username: string | null;
+    subjectsPosted: number;
+    commentsPosted: number;
+    activityScore: number;
+    joinedAt: number | null;
+    isNewUser: boolean;
+    lastActive: number | null;
+  }>;
+  teachers: Array<{
+    userId: number;
+    username: string | null;
+    lastActive: number | null;
+    daysSinceActive: number | null;
+    subjectsPosted: number;
+    commentsPosted: number;
+    recommendationsGiven: number;
+    rewardsGiven: number;
+    rewardTwinklesGiven: number;
+    engagementScore: number;
+  }>;
+  aiSpending:
+    | {
+        days: number;
+        startDayIndex: number;
+        endDayIndex: number;
+        summary: unknown;
+        topAccounts: unknown[];
+        topRiskGroups: unknown[];
+      }
+    | { unavailable: true; error: string };
+}>;
+```
+
+**Editing the bot's own comments.** `comment edit <commentId> --file
+<comment.md>` replaces the text of a comment the ACTING bot itself authored —
+for correcting a factual error, an unfulfillable claim, or outdated guidance
+in Zero/Ciel's own words. It is deliberately not a moderation verb: comments
+by the other bot, by any human, and hidden notification records are all
+rejected (`CLI_ADMIN_EDIT_NOT_OWN_COMMENT`,
+`CLI_ADMIN_EDIT_NOTIFICATION_COMMENT`). The replacement text follows the
+composed-comment rules (plain UTF-8, 10,000-character limit, truth about what
+the session actually did) and publishes through the website's canonical
+comment-edit pipeline — mentions are reprocessed (a newly added `@mikey`
+notifies him), and Earn-candidate projections resync. Submitting identical
+text returns `already_done`. Requires the `comment:post` scope of a
+comment-mode `post` run, and is audited as `comment.edit` with the previous
+content in `beforeState` and `data.edit.previousContent`. Edit sparingly:
+kids may have already read the original, so a comment that changed meaning
+(not just wording) usually deserves a follow-up reply instead of a silent
+rewrite.
+
 ## Audit history
 
 ```bash
@@ -1106,6 +1237,9 @@ lumine admin comment reply comment:456 --json
 
 lumine admin comment post --draft-id 77 \
   --idempotency-key comment-123-post-v1 --json
+
+# Correct the acting bot's OWN published comment.
+lumine admin comment edit 342752 --file corrected.md --json
 ```
 
 **Compose in persona by default (Mikey's standing direction, 2026-08-10).**
@@ -1127,6 +1261,24 @@ from memory:
   decisions are yours to make and record with `post skip` or in the run
   report).
 
+**Lumine Build app posts are composed-only, and only after actually looking
+(Mikey's direction, 2026-08-10).** When a post is about a Build app — the
+author shares their app, announces an update, or asks for feedback on their
+build — never use the server-generated draft path: the API persona cannot
+open an app, so its drafts either stay generic or fabricate first-hand
+experience (a real Ciel draft claimed "I clicked over to check it out" on an
+app nobody had opened). The day's management agent comments instead, and
+looks first: pull the project with lumine-cli when it is open source (or
+yours to pull) and read the code, or open the app and actually try it; then
+compose a comment whose specifics come from what you genuinely saw — a
+mechanic you liked, a nice touch in their code, a concrete suggestion. Be
+truthful about what you did: "I read through your code" and "I played a few
+rounds" are different claims, and a comment must only make the one that
+happened. If you could not access the app at all, say nothing about having
+tried it — ask the author about it instead. This is the standing rule for
+every composed comment, applied to apps: never claim an experience the
+session did not actually have.
+
 A composed draft (`--file`, plain UTF-8 text, at most the website's 10,000
 character comment limit) flows through the identical draft lifecycle —
 reservation, idempotency, context-revision CAS, publish fencing, audit