@stage5/lumine 0.2.24 → 0.2.26

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

@@ -4,6 +4,36 @@ import { assertAuthScope, resolveAuth } from "./auth.js";
 import { requestJson } from "./http.js";
 
 const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
+const MAX_COMPOSED_COMMENT_FILE_BYTES = 64 * 1024;
+const MAX_COMPOSED_COMMENT_LENGTH = 10_000;
+
+// Operator-composed persona comment text (plain UTF-8, not JSON). The agent
+// writes the comment in the bot's persona itself; the server never invokes
+// its model and no AI Energy is spent.
+function readComposedCommentFile(filePath) {
+  const normalizedPath = String(filePath || "").trim();
+  let contents;
+  try {
+    contents = readFileSync(normalizedPath, "utf8");
+  } catch {
+    throw cliValidationError(`Could not read ${normalizedPath}.`);
+  }
+  if (Buffer.byteLength(contents, "utf8") > MAX_COMPOSED_COMMENT_FILE_BYTES) {
+    throw cliValidationError("The composed comment file must be under 64KB.");
+  }
+  const normalized = contents.trim();
+  if (!normalized) {
+    throw cliValidationError(
+      `${normalizedPath} is empty; a composed comment needs text.`,
+    );
+  }
+  if (normalized.length > MAX_COMPOSED_COMMENT_LENGTH) {
+    throw cliValidationError(
+      `A composed comment must be at most ${MAX_COMPOSED_COMMENT_LENGTH} characters.`,
+    );
+  }
+  return normalized;
+}
 
 function readEditorialFile(filePath) {
   const normalizedPath = String(filePath || "").trim();
@@ -126,6 +156,15 @@ export async function adminCommand(options) {
     }
     throw error;
   }
+  if (
+    operation.name === "comment.draft" &&
+    typeof operation.body?.content === "string"
+  ) {
+    assertComposedCommentDraftResult({
+      result,
+      expectedContent: operation.body.content,
+    });
+  }
   if (options.json) {
     console.log(JSON.stringify(result));
     return result;
@@ -134,6 +173,35 @@ export async function adminCommand(options) {
   return result;
 }
 
+export function assertComposedCommentDraftResult({
+  result,
+  expectedContent,
+}) {
+  const draft = result?.data?.draft;
+  if (
+    draft?.decision === "draft" &&
+    draft?.reason === "operator-composed" &&
+    draft?.content === expectedContent &&
+    draft?.status === "ready"
+  ) {
+    return;
+  }
+  const error = new Error(
+    "The API did not confirm the operator-composed draft. Stop without publishing it and deploy an API that supports composed drafts.",
+  );
+  error.code = "LUMINE_ADMIN_COMPOSED_COMMENT_UNSUPPORTED";
+  error.data = {
+    ok: false,
+    status: "validation_error",
+    error: {
+      code: error.code,
+      message: error.message,
+      details: null,
+    },
+  };
+  throw error;
+}
+
 const RECOMMENDATION_CONTENT_TYPES = new Map([
   ["comment", "comment"],
   ["aistory", "aiStory"],
@@ -512,6 +580,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)) {
@@ -551,6 +632,9 @@ export function parseAdminOperation(options) {
           identity: options.adminIdentity
             ? parseIdentity(options.adminIdentity)
             : undefined,
+          ...(options.adminFile
+            ? { content: readComposedCommentFile(options.adminFile) }
+            : {}),
         },
       );
     }
@@ -570,7 +654,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,7 @@ 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 brief [--days <1..30>] [--json]
   lumine admin audit [list] [--run current|last|<run-id>] [--target <target>] [--actions <a,b>] [--full] [--cursor <cursor>] [--json]
 
 Examples:

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -103,6 +103,15 @@ posts that most need Zero or Ciel are the ones nobody else answered.
   it pairs well with a warm comment.
 - **Featured still selects for quality**, but when two candidates are close,
   prefer the child who has never been featured over the one who has.
+- **The live Featured board is Mikey's word.** Do not remove a currently
+  Featured subject without first showing Mikey the planned removals and
+  replacements and getting his go-ahead. In the other direction, if a subject
+  that was Featured or pinned during an earlier run is no longer on
+  `featured list`, treat that as Mikey having removed it deliberately — never
+  re-feature it to "restore" the board, and never treat any subject as a
+  permanent fixture from memory or old run notes. Derive the board fresh from
+  `featured list` at the start of every run; the only pins that exist are the
+  ones currently on it.
 
 Sensitive disclosures, active disputes, and anything needing crisis or medical
 judgment remain out of scope for a bot comment no matter how neglected the post
@@ -1027,6 +1036,116 @@ 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.days` includes today and may begin up to one day before the exact
+  brief window. 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;
+        summary: unknown;
+        topAccounts: unknown[];
+        topRiskGroups: unknown[];
+      }
+    | { unavailable: true; error: string };
+}>;
+```
+
 ## Audit history
 
 ```bash
@@ -1082,19 +1201,57 @@ type AuditList = Success<{
 ## Persona-backed comments and replies
 
 ```bash
-lumine admin daily-run start --identity auto --comment-mode draft --json
-lumine admin comment draft 123 --identity auto --json
-
 lumine admin daily-run start --identity ciel --comment-mode post \
   --run-key daily:2026-08-06:comments --json
+
+# Default: the agent composes the comment in the bot's persona itself.
+lumine admin comment draft 123 --file comment.md --json
+lumine admin comment draft dailyReflection:99 --file comment.md --json
+lumine admin comment reply comment:456 --file reply.md --json
+
+# Fallback (only when Mikey asks for it): server-generated persona drafts.
 lumine admin comment draft 123 --identity ciel \
   --idempotency-key comment-123-draft-v1 --json
-lumine admin comment draft dailyReflection:99 --json
 lumine admin comment reply comment:456 --json
+
 lumine admin comment post --draft-id 77 \
   --idempotency-key comment-123-post-v1 --json
 ```
 
+**Compose in persona by default (Mikey's standing direction, 2026-08-10).**
+A delegated agent writing Zero/Ciel comments should assume the bot's persona
+and write the comment text itself, submitting it with `--file` — exactly like
+the newspaper's claim/submit path, this spends no provider credits and no AI
+Energy (server-generated drafts bill the **operator's own** AI Energy
+battery). Use the no-`--file` server-generated path only when Mikey
+explicitly asks for it. Before composing, read the canonical persona sources
+so the voice and judgment match the real bots — do not improvise the persona
+from memory:
+
+- `twinkle-api/constants/index.ts` — `SYS_PROMPT_FOR_CIEL` /
+  `SYS_PROMPT_FOR_ZERO` (the exact persona system prompts) and
+  `TWINKLE_FEATURES_EXPLANATION` (what the bots know about the site);
+- `twinkle-api/helpers/ai/comment-assistant/index.ts` —
+  `ADMIN_COMMENT_DECISION_POLICY` / `ADMIN_REPLY_DECISION_POLICY` (the
+  draft-vs-skip judgment rules, which still govern composed comments: skip
+  decisions are yours to make and record with `post skip` or in the run
+  report).
+
+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
+(`metadata.composed: true`) — and is published with the same
+`comment post --draft-id`. It never invokes the server's model and records
+no AI Energy usage. Deployment guard: an API deployed before this capability
+silently ignores `content` and generates with the server's model instead. The
+CLI therefore requires the ready draft response to echo the exact submitted
+text with `reason: "operator-composed"`; otherwise it stops with
+`LUMINE_ADMIN_COMPOSED_COMMENT_UNSUPPORTED`. Never publish that rejected draft.
+Placement stays on the requested target: compose replies via `comment:<id>`
+targets (the generated path's model-chosen
+`replyTargetCommentId` does not apply). Everything below about targets,
+containers, and publication applies to both kinds of draft.
+
 A draft targets one of:
 
 - `subject:<id>` (or a bare numeric ID) — a top-level comment on the subject;