@stage5/lumine 0.3.0 → 0.3.1

package/lib/admin.js

@@ -2417,7 +2417,7 @@ export function parseAdminOperation(options) {
     // long as two GPT-6 Sol calls, so it gets its own timeout. The daily
     // website management run calls it in a bounded loop (Mikey, 2026-09-28).
     const usage =
-      "Usage: lumine admin reward-bank coverage <buildId> [--max-step 3] | seed <buildId> [--max-step 3].";
+      "Usage: lumine admin reward-bank coverage <buildId> [--max-step 3] | seed <buildId> [--max-step 3] | report <buildId> [--days 1].";
     const buildId = parseRequiredInteger(
       target || options.adminBuild,
       "Build ID",
@@ -2427,6 +2427,20 @@ export function parseAdminOperation(options) {
       ? parseRequiredInteger(options.adminMaxStep, "--max-step", 1)
       : 3;
     if (maxStep > 10) throw cliValidationError("--max-step must be at most 10.");
+    if (action === "report") {
+      const days = options.adminDays
+        ? parseRequiredInteger(options.adminDays, "--days", 1)
+        : 1;
+      if (days > 31) throw cliValidationError("--days must be at most 31.");
+      return readOperation(
+        "reward-bank.report",
+        withQuery("/cli/admin/reward-bank/report", {
+          buildId: String(buildId),
+          days: String(days),
+        }),
+        { requiresRun: false },
+      );
+    }
     if (action === "coverage" || action === "status") {
       return readOperation(
         "reward-bank.coverage",
@@ -5390,6 +5404,70 @@ function printReviewRequestResult({ operation, data, result }) {
   printReviewEvents(data.events);
 }
 
+// Human view of `lumine admin reward-bank report`; --json has everything.
+function printRewardBankReport(data) {
+  const pct = (value) =>
+    value === null || value === undefined ? "–" : `${Math.round(value * 100)}%`;
+  console.log(`Question bank report · build #${data.buildId} · last ${data.days} day(s)`);
+  if (data.coverage) {
+    console.log(
+      `Seeding coverage (steps 1-3): ${data.coverage.filled} / ${data.coverage.total}`,
+    );
+  }
+  if (!data.generation) {
+    console.log("Generation: no telemetry table yet.");
+  } else {
+    for (const row of data.generation.bySource) {
+      if (!row.rounds) continue;
+      console.log(
+        `Generation (${row.source}): ${row.rounds} rounds · ${row.accepted} accepted (${pct(row.acceptRate)}) · off-brief ${row.offBrief} · answer mismatch ${row.answerMismatch} · malformed ${row.malformed} · errors ${row.errors} · $${row.costUsd} · avg ${row.avgSeconds ?? "–"}s (max ${row.maxSeconds ?? "–"}s)`,
+      );
+    }
+    for (const row of data.generation.recentRejections.slice(0, 5)) {
+      console.log(
+        `  rejected ${row.outcome} ${row.ruleId}/${row.topicKey} step ${row.step}: ${row.problems || "(no reason given)"}`,
+      );
+    }
+  }
+  console.log(`Learners: ${data.learners.total}`);
+  for (const row of data.learners.byRuleStep) {
+    console.log(
+      `  ${row.ruleId} step ${row.step}: served ${row.served} · answered ${row.answered} · first-try ${pct(row.firstTryRate)} · solved ${row.solved} · skipped ${row.skipped}`,
+    );
+  }
+  const paid = data.payouts.reduce(
+    (sum, row) => ({ xp: sum.xp + row.xp, coins: sum.coins + row.coins, receipts: sum.receipts + row.receipts }),
+    { xp: 0, coins: 0, receipts: 0 },
+  );
+  console.log(
+    `Payouts: ${paid.receipts} receipts · ${paid.xp.toLocaleString()} XP · ${paid.coins.toLocaleString()} Coins`,
+  );
+  for (const row of data.payouts) {
+    console.log(
+      `  ${row.ruleId} step ${row.step}: ${row.receipts} (${row.firstTry} first try) · ${row.earners} earners · ${row.xp.toLocaleString()} XP · ${row.coins.toLocaleString()} Coins`,
+    );
+  }
+  if (data.ladder.length) {
+    console.log(
+      `Ladder now: ${data.ladder.map((row) => `${row.ruleId} s${row.step}:${row.topicLadders}`).join(", ")}`,
+    );
+  }
+  const hidden = data.bank.filter((row) => row.status === "hidden");
+  console.log(
+    `Bank: ${data.bank.filter((row) => row.status === "active").reduce((n, row) => n + row.questions, 0)} active · ${hidden.reduce((n, row) => n + row.questions, 0)} hidden${hidden.length ? ` (${hidden.map((row) => `${row.hiddenReason}: ${row.questions}`).join(", ")})` : ""} · ${data.bank.reduce((n, row) => n + row.createdInWindow, 0)} new in window`,
+  );
+  for (const row of data.questionsToReview.reported) {
+    console.log(
+      `  reported #${row.id} (${row.reports}, ${row.status}) ${row.ruleId}/${row.topicKey} s${row.step}: ${row.reasons}`,
+    );
+  }
+  for (const row of data.questionsToReview.hardest) {
+    console.log(
+      `  hardest #${row.id} ${row.ruleId}/${row.topicKey} s${row.step}: solved ${pct(row.solveRate)} of ${row.learners}`,
+    );
+  }
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
   if (printChatSafetyResult({ operation, data })) return;
@@ -5397,6 +5475,10 @@ function printAdminResult({ operation, result }) {
     printRewardActivity(data);
     return;
   }
+  if (operation.name === "reward-bank.report") {
+    printRewardBankReport(data);
+    return;
+  }
   if (operation.name.startsWith("reward-bank.")) {
     if (operation.name === "reward-bank.seed") {
       console.log(

package/lib/commands.js

@@ -3060,6 +3060,7 @@ export function printHelp() {
   lumine admin post reward <target> [--type subject|comment|aiStory|dailyReflection] --twinkles 3 [--json]
   lumine admin reward-bank coverage <buildId> [--max-step 3] [--json]
   lumine admin reward-bank seed <buildId> [--max-step 3] [--json]   (daily run: writes ONE missing seed question, lowest step first, billed to Zero/Ciel's AI Energy)
+  lumine admin reward-bank report <buildId> [--days 1] [--json]   (question-bank telemetry: generation outcomes, learners, payouts, ladder, questions to review)
   lumine admin comment draft <target> [--type subject|comment|build|aiStory|dailyReflection] [--file <comment.md>] [--review-receipt <review.json>|--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment reply comment:<id> [--file <reply.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--identity zero|ciel|auto] [--json]
   lumine admin comment post --draft-id <id> [--json]

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -1304,8 +1304,18 @@ them so the first learner on a unit never waits or pays.
 ```bash
 lumine admin reward-bank coverage <buildId> [--max-step 3] [--json]   # read-only, no run
 lumine admin reward-bank seed <buildId> [--max-step 3] [--json]       # delegated full run
+lumine admin reward-bank report <buildId> [--days 1] [--json]         # read-only telemetry
 ```
 
+`report` covers the last `--days` (1-31): generation rounds by source
+(learner or seed) with outcomes (`accepted`, `off_brief`: the checker judged
+the question outside the brief's language, level or LaTeX rule;
+`answer_mismatch`; `malformed`; `error`), cost and time, and recent rejection
+reasons; learners served/answered/first-try/solved/skipped per rule and step;
+payouts; the current ladder distribution; active/hidden questions; the
+hardest questions (3+ learners) and every reported question with reasons;
+and seeding coverage for steps 1-3 once the app is approved.
+
 - `seed` writes ONE question per call into the first missing slot, lowest
   step first across every topic of every generated-quiz rule, up to
   `--max-step` (default 3, at most 10). A slot is a (rule, topic, step) with