@stage5/lumine 0.2.96 → 0.2.98

package/lib/admin.js

@@ -724,7 +724,8 @@ export async function adminCommand(options) {
             : {}),
           ...(requestId ? { "x-lumine-idempotency-key": requestId } : {}),
         },
-        timeoutMs: options.timeoutMs,
+        // Long operations (reward-bank seed) carry their own timeout.
+        timeoutMs: operation.timeoutMs || options.timeoutMs,
         signal,
       });
     const transformResult = (rawResult) =>
@@ -2237,6 +2238,45 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "reward-bank" || namespace === "reward-banks") {
+    // Seed questions for an approved app's reward question bank (generated-quiz
+    // rules). coverage is read-only; seed writes ONE missing question per call
+    // (lowest step first) as the daily run's Zero/Ciel identity and takes as
+    // 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].";
+    const buildId = parseRequiredInteger(
+      target || options.adminBuild,
+      "Build ID",
+      1,
+    );
+    const maxStep = options.adminMaxStep
+      ? parseRequiredInteger(options.adminMaxStep, "--max-step", 1)
+      : 3;
+    if (maxStep > 10) throw cliValidationError("--max-step must be at most 10.");
+    if (action === "coverage" || action === "status") {
+      return readOperation(
+        "reward-bank.coverage",
+        withQuery("/cli/admin/reward-bank/coverage", {
+          buildId: String(buildId),
+          maxStep: String(maxStep),
+        }),
+        { requiresRun: false },
+      );
+    }
+    if (action === "seed") {
+      return writeOperation(
+        "reward-bank.seed",
+        "POST",
+        "/cli/admin/reward-bank/seed",
+        { buildId, maxStep },
+        { timeoutMs: 240000 },
+      );
+    }
+    throw cliValidationError(usage);
+  }
+
   if (namespace === "reward-activity" || namespace === "reward-telemetry") {
     // Read-only claim telemetry for the daily run: no run lease, no mutation.
     const date = options.adminDate
@@ -5097,6 +5137,27 @@ function printAdminResult({ operation, result }) {
     printRewardActivity(data);
     return;
   }
+  if (operation.name.startsWith("reward-bank.")) {
+    if (operation.name === "reward-bank.seed") {
+      console.log(
+        data.seeded
+          ? `Seeded question #${data.seeded.questionId}: ${data.seeded.ruleId} · ${data.seeded.topicKey} · step ${data.seeded.step}.`
+          : "Every slot is already seeded.",
+      );
+    }
+    const coverage = data.coverage || data;
+    console.log(
+      `Coverage: ${Number(coverage.filled || 0)} / ${Number(coverage.total || 0)} topic-step slots have a question${data.maxStep ? ` (steps 1-${data.maxStep})` : ""}.`,
+    );
+    if (data.missingByStep && Object.keys(data.missingByStep).length) {
+      console.log(
+        `Missing by step: ${Object.entries(data.missingByStep)
+          .map(([step, count]) => `step ${step}: ${count}`)
+          .join(", ")}.`,
+      );
+    }
+    return;
+  }
   if (operation.name.startsWith("review.")) {
     printReviewRequestResult({ operation, data, result });
     return;

package/lib/commands.js

@@ -2612,6 +2612,7 @@ export function parseArgs(args) {
     adminActions: raw.actions ? String(raw.actions) : "",
     adminDate: raw.date ? String(raw.date) : "",
     adminDays: raw.days ? String(raw.days) : "",
+    adminMaxStep: raw.maxStep ? String(raw.maxStep) : "",
     adminBuild: raw.build ? String(raw.build) : "",
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
     adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
@@ -3053,6 +3054,8 @@ export function printHelp() {
   lumine admin post skip <target> [--type comment|aiStory|dailyReflection] [--reason <text>] [--json]
   lumine admin post skip-batch --target-file <json-or-lines> [--reason <text>] [--checkpoint <file> [--resume]] [--json]
   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 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/lib/constants.js

@@ -181,9 +181,12 @@ Lumine CLI as the source of truth for saving this workspace back to Twinkle.
 ## Workflow
 
 - When planning a new app or a substantial improvement, read the AI decision design
-  guidance in ${SDK_REFERENCE_FILE}. Consider whether JEV through Twinkle.ai.decide
-  would improve the requested experience, and choose ordinary code or a text model
-  when those fit better. Make this judgment from the app's needs; do not wait for
+  guidance in ${SDK_REFERENCE_FILE} and decide explicitly whether JEV through
+  Twinkle.ai.decide improves the requested experience. JEV is free for viewers (it
+  never uses their AI Energy). Strong fits: an AI opponent or boss that reads the
+  player's habits and picks a counter-plan, NPCs that understand typed requests,
+  classifying submissions, and adaptive difficulty. Choose ordinary code or a text
+  model when those fit better. Make this judgment from the app's needs; do not wait for
   the creator to know the technology or add it automatically to every app.
 - Edit only project files in this workspace.
 - Keep /index.html or /index.htm as the entry file.
@@ -355,6 +358,8 @@ ${LUMINE_WORLD_UPDATE_GUIDANCE}
 
 Report the changed files, any SDK methods used, the lumine save result, the
 build or branch id, and whether the result is published or unpublished changes.
+Include one line on JEV: "JEV: used for <decision>" or "JEV: not used because
+<reason>".
 `;
 export const LUMINE_REFERENCE_INSTRUCTIONS = `${LUMINE_REFERENCE_INSTRUCTIONS_MARKER}
 # Lumine Reference Guide

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -2,7 +2,7 @@
 
 Version: 1.63.0
 Updated: 2026-09-28
-Generated: 2026-09-28T07:33:56.595Z
+Generated: 2026-09-28T08:22:20.133Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -39,7 +39,7 @@ Generated: 2026-09-28T07:33:56.595Z
 - Optional reward rule controls: maxLifetimeClaims caps one learner’s receipts for that rule across every day and release; completionProof: classic-tower-v1 requires a server-simulated Classic Tower finish in addition to minSeconds. These are server-enforced controls. Existing completion rules without completionProof still verify elapsed time only. Registered proof profiles also include breadface-v1, breadface-v2 and breadface-v3 (server-simulated Breadface inputs; each is one reviewed release's exact physics, chosen by the reviewer) study-record-v1 (a private study record reviewed by JEV, billed to the learner’s AI Energy), and Groove Lab's groove-lab-song-v1 (a song the learner published today, checked on the server for length, notes and originality) and groove-lab-heard-v1 (three established accounts finished the learner's songs today), Ashen Vigil's vigil-guest-coplay-v1 (a new guest spent 10 minutes with the learner in a private world room, measured by the world relay; each guest pays once) and minecraft-first-link-v1 (the learner is the first Twinkle account ever linked to that Minecraft player; each player pays once). Profiles are platform-owned; an app cannot invent a verifier or authorize its own reward.
 
 ## AI decision design
-- When planning a new app or an improvement, consider whether model-based judgments would materially improve the requested experience. Twinkle.ai.decide runs JEV, a model for narrow decisions over supplied text or structured state. Potential uses include interpreting a player's request to an NPC, choosing among legal game actions, classifying user content, ranking supplied candidates, and adapting an activity to evidence about the learner. These are examples to reason from, not a keyword checklist or a requirement to add AI to every app.
+- Twinkle.ai.decide runs JEV, a model for narrow decisions over supplied text or structured state, and it is free for viewers: decisions are covered by Twinkle and never use their AI Energy. Whenever an app makes a judgment that ordinary code can only approximate, consider JEV first. Proven patterns: an opponent or boss coach that reads the player's habits (favourite lane, repeated trick, cheese move) and picks a counter-plan from a fixed list, as in Red Square's boss and Open Football's opponent coach; NPCs that understand what a player types and choose an action; classifying or scoring user submissions; ranking supplied candidates; and picking the next exercise or difficulty from evidence about the learner. Any app with an AI opponent, NPC, or adaptive difficulty should decide explicitly whether JEV improves it. These are examples to reason from, not a keyword checklist or a requirement to add AI to every app.
 - Choose the mechanism by the work: use ordinary code for known rules, arithmetic, physics, legal moves, storage, and permissions; use ai.decide for contextual choices, yes/no probabilities, and scores; use ai.chat or ai.generateObject for generated dialogue, explanations, open-ended content, and multi-step reasoning. JEV does not generate text, browse the web, inspect images, or supply missing app data. Combine these tools when it benefits the actual request, without silently turning every decision into a more expensive text-model call.
 - Before adopting JEV, identify the concrete decision, the context available at that moment, the allowed outcomes, and why the added latency is worthwhile. Use your model judgment to make that choice. Do not substitute regex or keyword matching for understanding human-language intent. Explain the user-visible benefit simply; the creator does not need to select a provider, enter an API key, or design question schemas.
 - Send related independent questions about the same state together in one ai.decide request (up to 32). Write complete instructions and distinct option or level descriptions. Include an other/uncertain option when the choices might not cover the input. A second call is useful only when it needs newly obtained context or choices that depend on the first result; answers in one batch do not see each other.

package/sdk/LUMINE_ADMIN.md

@@ -1293,6 +1293,39 @@ those exact files and does not depend on keeping the review copy. Re-offers
 reuse the media; a failed transaction cleans up its copied objects. Declining
 leaves the offered media as unused uploads in the creator's library.
 
+### Reward question-bank seeding (every full daily review; added 2026-09-28)
+
+`generated-quiz` rules fill a question bank on the server: a question is
+written for one declared topic at one ladder step (GPT-6 Sol) and kept only
+when an independent second solve agrees. Learners write missing questions
+themselves on their own AI Energy; seeding writes the gentlest steps ahead of
+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
+```
+
+- `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
+  no active live question. The call takes as long as two model calls
+  (about 20–40 s; the CLI allows 4 minutes) and returns `seeded`
+  (`questionId`, `ruleId`, `topicKey`, `step`) or `complete: true`, plus
+  `coverage` (`filled` / `total`).
+- It needs the `reward:bank-seed` scope, which only full delegated runs carry.
+  The question is written as the run identity (Zero or Ciel) and billed to
+  that account's own AI Energy. It never pays anyone and opens no challenge.
+- It refuses unless the app's rewards are approved and published
+  (`CLI_ADMIN_BUILD_REWARD_BANK_NOT_LIVE`), and refuses to store a question
+  if the approval changed while it was being written
+  (`CLI_ADMIN_BUILD_REWARD_BANK_REVIEW_CHANGED`: run it again).
+  `CLI_ADMIN_BUILD_REWARD_BANK_UNVERIFIED` means the two solves disagreed
+  twice; nothing was stored.
+- Which apps to seed, how many steps and how many per run are Mikey's
+  decisions, recorded in the agent guide (Math Studio #2655: steps 1–3, at
+  most 20 per run).
+
 ### Reward activity report (standing duty, every full daily review; added 2026-09-12)
 
 Completion rewards (Arcade Typing's stage clears) prove nothing but elapsed