@stage5/lumine 0.2.95 → 0.2.97

package/README.md

@@ -61,6 +61,15 @@ Mikey reviews with `lumine admin storage list`, `show <user>`,
 or grants directly with `lumine admin storage grant <user> --size <size>`.
 Approvals are capped at 2 GB and never lower a creator below the default.
 
+Bridge Builder meetup quest crews (the website's /achievements/bridge-builder
+page) are reviewed with `lumine admin meetup list [--status review|active|completed|all]`,
+`show <crewId>` (includes a one-hour link to the proof video),
+`approve-plan <crewId> [--note <text>]`, `send-back <crewId> --note <text>`
+(sends back whatever is waiting: the video, else the plan) and
+`approve <crewId> --attended <userId,userId,...>`, which unlocks the
+achievement for every member ticked. At least 3 attendees from 3 different
+branches are required.
+
 For team projects, Lumine mirrors the website workspace flow: choosing or
 pulling the owner's main project creates or reuses your contribution branch and
 checks out that branch locally. Saves go to your branch, so the project owner

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) =>
@@ -1924,6 +1925,148 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (MEETUP_NAMESPACES.has(namespace)) {
+    // Bridge Builder meetup quest crews (achievement type 'meetup'): the same
+    // reviews as the admin controls on the website quest page. Mikey's own
+    // decision, any time, never in a daily run.
+    const usage =
+      "Usage: lumine admin meetup list [--status review|active|completed|all] | show <crewId> | approve-plan <crewId> [--note <text>] | send-back <crewId> --note <text> | approve <crewId> --attended <userId,userId,...> [--note <text>] | slot <crewId> --confirm <slotIndex> | resend-email <crewId>.";
+    const note = String(options.note || "").trim();
+    if (note.length > 1000) {
+      throw cliValidationError("--note must be at most 1000 characters.");
+    }
+    if (action === "story" || action === "stories") {
+      // A crew's Bridge Builder story page: Mikey's final approval (the
+      // admin bar on the story page does the same). Publishing copies only
+      // the photos/clips every tagged member's parent allowed.
+      const storyUsage =
+        "Usage: lumine admin meetup story list | show <crewId> | approve <crewId> [--note <text>] [--no-announce] | send-back <crewId> --note <text> | unpublish <crewId> --note <text>.";
+      const storyAction = target || "list";
+      if (storyAction === "list") {
+        return readOperation("meetup.story.list", "/cli/admin/meetup-quest/stories", {
+          requiresRun: false,
+        });
+      }
+      if (!["show", "approve", "send-back", "unpublish"].includes(storyAction)) {
+        throw cliValidationError(storyUsage);
+      }
+      const crewId = parseRequiredInteger(extra, "Crew ID", 1);
+      if (storyAction === "show") {
+        return readOperation(
+          "meetup.story.show",
+          `/cli/admin/meetup-quest/stories/by-crew/${crewId}`,
+          { requiresRun: false },
+        );
+      }
+      if (storyAction !== "approve" && !note) {
+        throw cliValidationError(
+          `lumine admin meetup story ${storyAction} <crewId> needs --note <text> (the crew sees it).`,
+        );
+      }
+      return writeOperation(
+        `meetup.story.${storyAction}`,
+        "POST",
+        `/cli/admin/meetup-quest/stories/by-crew/${crewId}/${storyAction}`,
+        storyAction === "approve"
+          ? { note, announce: !options.adminNoAnnounce }
+          : { note },
+        { requiresRun: false },
+      );
+    }
+    if (!action || action === "list") {
+      return readOperation(
+        "meetup.list",
+        withQuery("/cli/admin/meetup-quest/crews", {
+          status: parseChoice(
+            options.adminStatus || "review",
+            "--status",
+            ["review", "active", "completed", "all"],
+          ),
+        }),
+        { requiresRun: false },
+      );
+    }
+    if (action === "show" || action === "get") {
+      const crewId = parseRequiredInteger(target, "Crew ID", 1);
+      return readOperation(
+        "meetup.show",
+        `/cli/admin/meetup-quest/crews/${crewId}`,
+        { requiresRun: false },
+      );
+    }
+    if (action === "approve-plan") {
+      const crewId = parseRequiredInteger(target, "Crew ID", 1);
+      return writeOperation(
+        "meetup.approve-plan",
+        "POST",
+        `/cli/admin/meetup-quest/crews/${crewId}/approve-plan`,
+        { note },
+        { requiresRun: false },
+      );
+    }
+    if (action === "send-back") {
+      const crewId = parseRequiredInteger(target, "Crew ID", 1);
+      if (!note) {
+        throw cliValidationError(
+          "lumine admin meetup send-back <crewId> needs --note <what to change> (the crew sees it).",
+        );
+      }
+      return writeOperation(
+        "meetup.send-back",
+        "POST",
+        `/cli/admin/meetup-quest/crews/${crewId}/send-back`,
+        { note },
+        { requiresRun: false },
+      );
+    }
+    if (action === "approve") {
+      const crewId = parseRequiredInteger(target, "Crew ID", 1);
+      const attendedUserIds = String(options.adminAttended || "")
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .map((part) => parseRequiredInteger(part, "--attended user ID", 1));
+      if (!attendedUserIds.length) {
+        throw cliValidationError(
+          "lumine admin meetup approve <crewId> needs --attended <userId,userId,...> (the members who showed up in the video).",
+        );
+      }
+      return writeOperation(
+        "meetup.approve",
+        "POST",
+        `/cli/admin/meetup-quest/crews/${crewId}/approve`,
+        { attendedUserIds: [...new Set(attendedUserIds)], note },
+        { requiresRun: false },
+      );
+    }
+    if (action === "slot") {
+      const crewId = parseRequiredInteger(target, "Crew ID", 1);
+      if (options.adminConfirm === "") {
+        throw cliValidationError(
+          "lumine admin meetup slot <crewId> needs --confirm <slotIndex> (0 is the first offered slot; see `show`).",
+        );
+      }
+      return writeOperation(
+        "meetup.slot",
+        "POST",
+        `/cli/admin/meetup-quest/crews/${crewId}/slot`,
+        { slotIndex: parseRequiredInteger(options.adminConfirm, "--confirm", 0, 9) },
+        { requiresRun: false },
+      );
+    }
+    if (action === "resend-email") {
+      const crewId = parseRequiredInteger(target, "Crew ID", 1);
+      return writeOperation(
+        "meetup.resend-email",
+        "POST",
+        `/cli/admin/meetup-quest/crews/${crewId}/resend-email`,
+        {},
+        { requiresRun: false },
+      );
+    }
+    throw cliValidationError(usage);
+  }
+
   if (STORAGE_LIMIT_NAMESPACES.has(namespace)) {
     // Lumine file storage (Twinkle.files) unlocks: per-creator approvals past
     // the default quota. Mikey's own decision, any time, never in a daily run.
@@ -2133,6 +2276,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
@@ -4684,6 +4866,167 @@ function printCardCraftReviewResult({ operation, data }) {
     );
 }
 
+const MEETUP_NAMESPACES = new Set([
+  "meetup",
+  "meetups",
+  "meetup-quest",
+  "bridge-builder",
+]);
+
+function formatMeetupMembers(members) {
+  return (members || [])
+    .map(
+      (member) =>
+        `${member.username || `user ${member.userId}`} (${member.userId}, ${member.branch || "no branch"}${member.parentOk === undefined ? "" : member.parentOk ? ", parent OK" : ", parent not yet"}${member.attended ? ", attended" : ""})`,
+    )
+    .join("; ");
+}
+
+function printMeetupCrew(crew) {
+  const progress = crew.progress || {};
+  console.log(
+    `Crew #${crew.crewId}${crew.name ? ` "${crew.name}"` : ""} · ${crew.status}${crew.isOpen === false ? " · invite only" : ""} · step: ${progress.currentStep || "done"}${progress.blocking ? ` · ${progress.blocking}` : ""}`,
+  );
+  if (crew.about) console.log(`  About: ${crew.about}`);
+  for (const step of progress.steps || []) {
+    console.log(`  ${step.number}. ${step.label} [${step.state}] ${step.detail}`);
+  }
+  console.log(`  Members: ${formatMeetupMembers(crew.members)}`);
+  if (Array.isArray(crew.invites) && crew.invites.length) {
+    console.log(
+      `  Pending invites: ${crew.invites.map((invite) => `${invite.username} (${invite.userId}, invite ${invite.inviteId})`).join("; ")}`,
+    );
+  }
+  if (crew.adult?.kind) {
+    console.log(
+      `  Adult coming: ${crew.adult.kind === "teacher" ? "Twinkle teacher" : "parent"}: ${crew.adult.name}`,
+    );
+  }
+  const plan = crew.plan || {};
+  if (plan.status && plan.status !== "none") {
+    console.log(
+      `  Plan (${plan.status}): ${plan.date} in ${plan.area}: ${plan.activity}${plan.note ? ` · note: ${plan.note}` : ""}`,
+    );
+  }
+  if (crew.planApprovedBy?.username) {
+    console.log(`  Plan approved by ${crew.planApprovedBy.username}`);
+  }
+  const venue = crew.venue || {};
+  if (venue.status && venue.status !== "none") {
+    const slots = (venue.slots || []).map(
+      (slot, index) => `[${index}] ${slot.date} ${slot.start}-${slot.end}`,
+    );
+    console.log(
+      `  Venue (${venue.status}): ${venue.room ? `${venue.branch} · ${venue.room}` : "no classroom (meets elsewhere with the grown-up)"}${slots.length ? ` · slots ${slots.join(", ")}` : ""}${venue.confirmedSlot ? ` · SET: ${venue.confirmedSlot.date} ${venue.confirmedSlot.start}-${venue.confirmedSlot.end}` : ""}`,
+    );
+  }
+  const video = crew.video || {};
+  if (video.status && video.status !== "none") {
+    console.log(
+      `  Video (${video.status}): ${video.fileName}${video.note ? ` · note: ${video.note}` : ""}`,
+    );
+    if (video.url) console.log(`  Watch (link expires in 1 hour): ${video.url}`);
+  }
+}
+
+function printMeetupResult({ operation, data, result }) {
+  if (operation.name === "meetup.story.list") {
+    const stories = Array.isArray(data.stories) ? data.stories : [];
+    console.log(`${stories.length} Bridge Builder stor${stories.length === 1 ? "y" : "ies"} waiting for approval:`);
+    for (const story of stories) {
+      console.log(
+        `  crew #${story.crewId} · "${story.title}" · ${story.crewName} (${(story.people || []).join(", ")}) · ${story.itemsPublic} public / ${story.itemsPrivate} private`,
+      );
+    }
+    if (stories.length) console.log("Approve: lumine admin meetup story approve <crewId> (or send-back <crewId> --note).");
+    return;
+  }
+  if (operation.name === "meetup.story.show") {
+    const story = data.story || {};
+    const items = [...(story.photos || []), ...(story.clips || [])];
+    console.log(`Story #${story.storyId} (crew #${story.crewId}) · ${story.status} · "${story.title}"`);
+    console.log(`  People: ${(story.people || []).map((p) => `${p.username} (${p.branch})`).join(", ")}`);
+    for (const consent of story.review?.consents || []) {
+      const person = (story.people || []).find((p) => p.userId === consent.userId);
+      console.log(`  Parent of ${person?.username || consent.userId}: ${consent.state}`);
+    }
+    for (const item of items) {
+      const gate = item.gate || {};
+      console.log(
+        `  ${item.kind} #${item.id}: ${gate.publishable ? "PUBLIC" : `private (${gate.reason || "live"})`}${item.caption ? ` · ${item.caption}` : ""}${item.url ? ` · ${item.url}` : ""}`,
+      );
+    }
+    if ((story.review?.nameWarnings || []).length) {
+      console.log(`  Possible real names: ${story.review.nameWarnings.join(", ")}`);
+    }
+    if (story.body) console.log(`\n${story.body}\n`);
+    return;
+  }
+  if (operation.name.startsWith("meetup.story.")) {
+    const r = data.result || {};
+    if (operation.name === "meetup.story.approve") {
+      console.log(
+        `Published story #${r.storyId} (crew #${r.crewId}): ${(r.publicMediaIds || []).length} public, ${(r.privateMediaIds || []).length} private.${r.announcementSubjectId ? ` Announcement: subject #${r.announcementSubjectId}.` : ""}${(r.failed || []).length ? ` FAILED to process: ${r.failed.map((f) => `#${f.mediaId} ${f.error}`).join("; ")}.` : ""}`,
+      );
+    } else {
+      console.log(`${operation.name === "meetup.story.unpublish" ? "Unpublished" : "Sent back"} story #${r.storyId} (crew #${r.crewId}).`);
+    }
+    return;
+  }
+  if (operation.name === "meetup.list") {
+    const crews = Array.isArray(data.crews) ? data.crews : [];
+    console.log(`${crews.length} meetup crew(s) (${data.filter || "review"}):`);
+    for (const crew of crews) {
+      console.log(
+        `  #${crew.crewId} · ${crew.status}${crew.waitingFor ? ` · waiting: ${crew.waitingFor}` : ""} · founder ${crew.founderUsername || "?"} · ${formatMeetupMembers(crew.members)}${crew.blocking ? ` · ${crew.blocking}` : ""}`,
+      );
+    }
+    if (crews.some((crew) => crew.waitingFor)) {
+      console.log(
+        "Review: lumine admin meetup show <crewId>, then approve-plan | send-back --note | approve --attended <ids>.",
+      );
+    }
+    return;
+  }
+  if (operation.name === "meetup.show") {
+    printMeetupCrew(data.crew || {});
+    return;
+  }
+  if (operation.name === "meetup.slot") {
+    console.log(
+      `Slot set for crew #${data.crew?.crewId}: ${data.slot?.date} ${data.slot?.start}-${data.slot?.end}.`,
+    );
+    if (data.crew) printMeetupCrew(data.crew);
+    return;
+  }
+  if (operation.name === "meetup.resend-email") {
+    const email = data.email || {};
+    console.log(
+      email.sent
+        ? `Coordinator ${email.kind} email ${email.mode === "sent" ? "sent" : `built (${email.mode})`} to ${email.to}.`
+        : `No email sent: ${email.reason || "unknown"}.`,
+    );
+    return;
+  }
+  const stage = data.result?.stage === "video" ? "video" : "plan";
+  if (operation.name === "meetup.approve-plan") {
+    console.log(
+      result?.changed === false
+        ? `Crew #${data.result?.crewId}'s plan was already approved.`
+        : `Approved crew #${data.result?.crewId}'s plan. They can meet up and film it now.`,
+    );
+  } else if (operation.name === "meetup.send-back") {
+    console.log(`Sent crew #${data.result?.crewId}'s ${stage} back with your note.`);
+  } else if (operation.name === "meetup.approve") {
+    const unlocked = data.unlocks?.unlockedUserIds || [];
+    const failed = data.unlocks?.failed || [];
+    console.log(
+      `${result?.changed === false ? "Already approved" : "Approved"} crew #${data.result?.crewId}: unlocked for user(s) ${unlocked.join(", ") || "none"}.${failed.length ? ` Unlock FAILED for ${failed.join(", ")}; run the same command again.` : ""}`,
+    );
+  }
+  if (data.crew) printMeetupCrew(data.crew);
+}
+
 const STORAGE_LIMIT_NAMESPACES = new Set([
   "storage",
   "storage-limit",
@@ -4875,6 +5218,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;
@@ -4891,6 +5255,10 @@ function printAdminResult({ operation, result }) {
     printStorageLimitResult({ operation, data, result });
     return;
   }
+  if (operation.name.startsWith("meetup.")) {
+    printMeetupResult({ operation, data, result });
+    return;
+  }
   if (operation.name === "runtime.evidence") {
     const evidence = data.evidence || {};
     console.log(

package/lib/commands.js

@@ -2355,6 +2355,7 @@ export function parseArgs(args) {
   const raw = {};
   const positional = [];
   const booleanFlags = new Set([
+    "noAnnounce",
     "noLeaseKeeper",
     "noOpen",
     "open",
@@ -2604,12 +2605,16 @@ export function parseArgs(args) {
     twinkles: raw.twinkles ? String(raw.twinkles) : "",
     adminReason: raw.reason ? String(raw.reason) : "",
     storageSize: raw.size ? String(raw.size) : "",
+    adminAttended: raw.attended ? String(raw.attended) : "",
+    adminConfirm: raw.confirm === undefined ? "" : String(raw.confirm),
+    adminNoAnnounce: Boolean(raw.noAnnounce),
     adminContextLimit: raw.limit === undefined ? 20 : Number(raw.limit),
     adminRun: raw.run ? String(raw.run) : "",
     adminTarget: raw.target ? String(raw.target) : "",
     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) : "",
@@ -3008,6 +3013,8 @@ export function printHelp() {
   lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] [--json]
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
   lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]
+  lumine admin meetup list [--status review|active|completed|all] | show <crewId> | approve-plan <crewId> [--note <text>] | send-back <crewId> --note <text> | approve <crewId> --attended <userId,userId,...> [--note <text>] | slot <crewId> --confirm <slotIndex> | resend-email <crewId>   (Bridge Builder meetup quest)
+  lumine admin meetup story list | show <crewId> | approve <crewId> [--note <text>] [--no-announce] | send-back <crewId> --note <text> | unpublish <crewId> --note <text>   (Bridge Builder story pages: publishes only what every tagged member's parent allowed)
   lumine admin reward-activity [--date YYYY-MM-DD] [--days <1..31>] [--build <id>] [--json]
   lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] [--json]
   lumine admin chat-reports show <report-id> [--json]   (reported message snapshot + surrounding context)
@@ -3050,6 +3057,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

@@ -48,6 +48,8 @@ export const BUILD_VENDOR_THREE_MODULE_IMPORT = `${BUILD_VENDOR_THREE_PREFIX}thr
 export const BUILD_VENDOR_THREE_WEBGPU_MODULE_IMPORT = `${BUILD_VENDOR_THREE_PREFIX}three.webgpu.min.js`;
 export const BUILD_VENDOR_THREE_TSL_MODULE_IMPORT = `${BUILD_VENDOR_THREE_PREFIX}three.tsl.min.js`;
 export const BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX = `${BUILD_VENDOR_THREE_PREFIX}addons/`;
+export const BUILD_VENDOR_KATEX_VERSION = "0.18.9";
+export const BUILD_VENDOR_KATEX_PREFIX = `/build/vendor/katex/${BUILD_VENDOR_KATEX_VERSION}/`;
 export const PROJECT_METADATA_DIR = ".twinkle";
 export const PROJECT_METADATA_FILE = "lumine-project.json";
 export const ASSETS_METADATA_FILE = "assets.json";
@@ -157,6 +159,8 @@ export const LUMINE_THREE_VENDOR_GUIDANCE = `- For Three.js, use the first-party
 - Keep one Three.js version throughout a project. If a project using ${BUILD_VENDOR_THREE_LEGACY_VERSION} needs current addons, migrate every Three.js import to ${BUILD_VENDOR_THREE_VERSION} in one coherent change; never mix the legacy core with current addons.
 - This vendor surface covers supported official Three.js modules, not arbitrary third-party Three.js packages. Do not paste library source into project files or use npm/CDN copies. Loader runtime assets are served too: point decoder/transcoder paths at the addon prefix (example: dracoLoader.setDecoderPath('${BUILD_VENDOR_THREE_ADDONS_IMPORT_PREFIX}libs/draco/');).
 - Size both WebGLRenderer and EffectComposer from Twinkle.preview layout dimensions, coalesce resize work, and render with composer.render() when a composer owns the pass chain.`;
+export const LUMINE_MATH_VENDOR_GUIDANCE = `- For math formulas, Twinkle serves KaTeX ${BUILD_VENDOR_KATEX_VERSION}: link <link rel="stylesheet" href="${BUILD_VENDOR_KATEX_PREFIX}katex.min.css"> (its fonts load from the same place), then import katex from '${BUILD_VENDOR_KATEX_PREFIX}katex.js' and call katex.render(tex, element, { displayMode, throwOnError: false }), or import renderMathInElement from '${BUILD_VENDOR_KATEX_PREFIX}contrib/auto-render.js' to typeset $...$ and $$...$$ inside existing text.
+- Use it when an app shows fractions, roots, exponents, integrals, matrices or other formulas that plain text renders poorly; keep plain text for simple arithmetic. Do not paste KaTeX source into project files or use npm/CDN copies.`;
 export const LUMINE_AGENT_INSTRUCTIONS = `${LUMINE_AGENT_INSTRUCTIONS_MARKER}
 # Lumine Project Agent Guide
 
@@ -177,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.
@@ -333,6 +340,7 @@ ${LUMINE_MOBILE_SELECTION_GUIDANCE}
 - CAUTION: the preview runtime AUTO-DETECTS "game apps" — any <canvas> in the body (even a decorative background canvas) or game-y words in visible text switch the app to viewport-app mode: html/body get overflow:hidden !important and body becomes a centering flexbox, so tall document-flow pages clip and stop scrolling. Document-style apps that use a canvas must call Twinkle.preview.subscribe (or getLayout/reserveInsets) early at boot — any of those opts out of auto game mode — then pad by layout.safeInsets and scroll within layout.viewport.height.
 - For canvas, WebGL, Three.js, fullscreen, or game builds, use Twinkle.preview for layout. Do not size roots from 100vh, 100vw, 100dvh, 100dvw, window.innerWidth, window.innerHeight, visualViewport, or document viewport dimensions.
 ${LUMINE_THREE_VENDOR_GUIDANCE}
+${LUMINE_MATH_VENDOR_GUIDANCE}
 - Do not invent or guess Twinkle.* SDK method names. Use ${SDK_REFERENCE_FILE} as the local SDK reference and prefer Twinkle.capabilities checks for gated features.
 - Match storage to update frequency. Twinkle.privateDb and Twinkle.sharedDb are for LOW-frequency durable state only — things that change on a user action (settings, inventory checkpoints, completed quests, saved progress; comments, votes, room settings, submitted records). NEVER write high-frequency or per-frame/per-tick state to them (camera or cursor position, animation state, live movement, presence, autosave every frame/tick). Keep live state in client memory, broadcast realtime/presence via Twinkle.world, and for durable per-user state flush an occasional snapshot on an interval or on exit (never per frame) — e.g. the viewer/user DB or a single latest-snapshot key. The server rate-limits these writes per key and returns 429 on excess; never retry-loop a 429.
 ${LUMINE_WORLD_UPDATE_GUIDANCE}
@@ -350,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/lib/rewards.js

@@ -69,7 +69,9 @@ function printDeclaration(result, { prefix = "" } = {}) {
       const what =
         rule.verifier === "completion"
           ? `completion · at least ${rule.minSeconds || 0}s`
-          : `quiz · ${rule.questionSets} set(s)${rule.progression ? ` · ${rule.progression}` : ""}${rule.standingQuestions ? ` · ${rule.standingQuestions} standing` : ""}`;
+          : rule.verifier === "generated-quiz"
+            ? "question bank · server-written, double-checked questions on a step ladder"
+            : `quiz · ${rule.questionSets} set(s)${rule.progression ? ` · ${rule.progression}` : ""}${rule.standingQuestions ? ` · ${rule.standingQuestions} standing` : ""}`;
       console.log(
         `${prefix}  ${rule.id}: ${rule.title} · ${rule.xp} XP + ${rule.coins} Coins · ${what}`,
       );
@@ -239,8 +241,12 @@ function printRewardsHelp() {
 rewards.json (project root) declares the economy the reviewer approves:
   { "userDailyXP", "userDailyCoins", "userDailyClaims"?,
     "rules": [{ "id", "title", "howTo"? (how to earn it, in the player's words), "category"? (section header, up to 40 characters, e.g. "Bring friends"),
-                "series"? (lowercase key for repeat rules like friend-1/2/3; they must share category, verifier and amounts), "xp", "coins", "verifier": "numeric-quiz" | "completion",
-                "maxAttempts"?, "retry"?: { "xpPercent", "coinsPercent", "paidAttempts"? }, "minSeconds"? (completion), "progression"?: "dated" | "until-earned" (quiz) }] }
+                "series"? (lowercase key for repeat rules like friend-1/2/3; they must share category, verifier and amounts), "xp", "coins", "verifier": "numeric-quiz" | "completion" | "generated-quiz",
+                "maxAttempts"?, "retry"?: { "xpPercent", "coinsPercent", "paidAttempts"? }, "minSeconds"? (completion), "progression"?: "dated" | "until-earned" (quiz),
+                "bank"? (generated-quiz): { "steps": [percent, ...] rising to 100, "startStep"?, "instructions", "topics": [{ "key", "title", "description" }] } }] }
 The Earn page shows rules under their category headers and each series as one row ("up to 3 a day").
-Questions and answer keys never go in project files; they belong in the sheet.`);
+Questions and answer keys never go in project files; they belong in the sheet.
+generated-quiz rules need no sheet: the server writes each question for a topic at the learner's step
+(GPT-6 Sol, billed to that learner's AI Energy), checks it with a second independent solve, and pays
+the step's percent of xp/coins. The reviewer approves the ladder, topics and instructions.`);
 }

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.61.0
+Version: 1.63.0
 Updated: 2026-09-28
-Generated: 2026-09-27T17:21:08.257Z
+Generated: 2026-09-28T08:22:20.133Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -33,13 +33,13 @@ Generated: 2026-09-27T17:21:08.257Z
 - Use Twinkle.live for one-way app livestreams and Twinkle.chat for the accompanying thread. Free livestreams require a verified host, end after at most 15 minutes, and issue at most 10 private viewer grants. Twinkle keeps platform-owned live-status/end controls above active hosts, so app code cannot hide or replace the broadcaster's Stop path.
 - Media Energy is separate from AI Energy. Replace Media Energy UI only from canonical mediaEnergy/getUsage responses; never decrement, reserve, or synthesize it in app code.
 - Twinkle.rewards awards real XP and Coins only in the current approved published release. Drafts, local previews, private apps and superseded releases cannot earn. The server supplies a published-runtime grant; app code cannot choose a recipient or award amount.
-- The creator's agent designs the rewards. Declare the economy in a project file `rewards.json` at the root: budgets (userDailyXP, userDailyCoins, optional userDailyClaims; there is no app-wide daily or lifetime budget, only what one learner can earn per day) and rules [{ id, title, howTo?, category? (section header, up to 40 characters), series? (key for repeat rules that share category and amounts), xp, coins, verifier: 'numeric-quiz' | 'completion', maxAttempts?, retry?: { xpPercent, coinsPercent, paidAttempts? }, minSeconds? (completion), progression?: 'dated' | 'until-earned' (quiz) }]. Wire the matching Twinkle.rewards calls with those literal rule ids. Questions and answer keys NEVER go in project files (published source is readable by every player): quiz rules get them from the private question sheet uploaded with `lumine rewards sheet <file.json>` ({ rules: { <ruleId>: { questions?, sets? } } }); `lumine rewards check` validates both together. A review request freezes the code and proposes rewards.json merged with the sheet; the administrator reads the code, checks the amounts and whether the app is exploitable, may change any amount, and approves. Creators are kids and teens: show approval status and one Send for review action; do not ask them to fill in technical forms. Every code update that retains rewards needs a new approval before publishing. Removing the SDK automatically clears its gate. Apps read amounts, tries and sets from getStatus, never from their own file.
-- Verifiers: 'numeric-quiz' pays for server-checked numeric answers (retry share, attempt limits, dated sets or until-earned sets that stay up until somebody earns them, after-answer guides). 'completion' pays when the app reports an activity finished — a cleared stage, a finished round — at least minSeconds after start({ ruleId }); the server checks only the elapsed time, once per learner per site day (UTC midnight), and the budgets. Call start when the activity begins and claim({ challengeId }) with no answers when it ends; keep completion amounts and userDailyXP small enough that a player scripting the calls would not matter, because nothing else is verified.
+- The creator's agent designs the rewards. Declare the economy in a project file `rewards.json` at the root: budgets (userDailyXP, userDailyCoins, optional userDailyClaims; there is no app-wide daily or lifetime budget, only what one learner can earn per day) and rules [{ id, title, howTo?, category? (section header, up to 40 characters), series? (key for repeat rules that share category and amounts), xp, coins, verifier: 'numeric-quiz' | 'completion' | 'generated-quiz', maxAttempts?, retry?: { xpPercent, coinsPercent, paidAttempts? }, minSeconds? (completion), progression?: 'dated' | 'until-earned' (quiz), bank? (generated-quiz): { steps: [percent, ...] rising to 100, startStep?, instructions, topics: [{ key, title, description }] } }]. generated-quiz rules need no question sheet. Wire the matching Twinkle.rewards calls with those literal rule ids. Questions and answer keys NEVER go in project files (published source is readable by every player): quiz rules get them from the private question sheet uploaded with `lumine rewards sheet <file.json>` ({ rules: { <ruleId>: { questions?, sets? } } }); `lumine rewards check` validates both together. A review request freezes the code and proposes rewards.json merged with the sheet; the administrator reads the code, checks the amounts and whether the app is exploitable, may change any amount, and approves. Creators are kids and teens: show approval status and one Send for review action; do not ask them to fill in technical forms. Every code update that retains rewards needs a new approval before publishing. Removing the SDK automatically clears its gate. Apps read amounts, tries and sets from getStatus, never from their own file.
+- Verifiers: 'numeric-quiz' pays for server-checked numeric answers (retry share, attempt limits, dated sets or until-earned sets that stay up until somebody earns them, after-answer guides). 'completion' pays when the app reports an activity finished — a cleared stage, a finished round — at least minSeconds after start({ ruleId }); the server checks only the elapsed time, once per learner per site day (UTC midnight), and the budgets. Call start when the activity begins and claim({ challengeId }) with no answers when it ends; keep completion amounts and userDailyXP small enough that a player scripting the calls would not matter, because nothing else is verified. 'generated-quiz' pays from a question bank the server fills itself: for one declared topic at the learner's step of the ladder, the server writes a question with GPT-6 Sol (billed to that learner's AI Energy), solves it again independently and keeps it only when both answers agree; every learner who has not seen a question gets it before anything new is written. `xp`/`coins` are the top step's amounts and each step pays its `steps` percent of them (then the usual retry share). Two first-try answers in a row climb a step; two misses in a row step down. Learners may earn many bank questions a day, bounded by userDailyXP/userDailyCoins. The reviewer approves the ladder, amounts, topics and instructions, not each question; learner reports and solve rates hide bad questions. Use the rewards bank methods (getBankStatus, startBankQuestion, generateBankQuestion, claimBankQuestion, reportBankQuestion); start and claim refuse bank rules.
 - Numeric quiz answers are verified on the server; client scores, privateDb state, timers and completion booleans are not verified reward evidence. Limits reset at UTC midnight. Rules are earned once per viewer per UTC day; attempt limits and retry payouts come from the approved rule. Challenges expire at the UTC day boundary. Budgets apply across release changes.
 - 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.
@@ -1064,6 +1064,122 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Others get 403 minecraft_news_forbidden.
   - Example: await Twinkle.minecraft.deleteNews({ id: post.id });
 
+### Twinkle.town
+- async getTown() | scopes: sharedDb:read
+  - Returns: { town, clock: { now, townMinute, day, weekday, kstTime }, places: [{ id, name, kind, district, door: [x, z], y, built, spots }], housing: { homes, waitingList }, residents: [publicCharacter], gazette: [{ id, townMinute, text }], goods, myCharacterId, cursor }
+  - Load Starhaven Life's shared town: places (Minecraft coordinates), the homes board, every resident's public state and the Town Gazette.
+  - Every resident is a real member's character living on its own every 15 minutes on the real KST clock (school mornings, work afternoons, rent on Mondays).
+  - publicCharacter = { characterId, name, look, pet, home, place, spot, move: { points, depart, arrive } | null, activity: { id, label, icon, place, start, until, with, withName } | null, mood: { emotion, icon, label }, title, job, knownFor, guided }. start/until/depart/arrive are town minutes (clock.townMinute is now).
+  - Pass cursor to getChanges.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+  - Example: const town = await Twinkle.town.getTown(); let cursor = town.cursor; setInterval(async () => { const ch = await Twinkle.town.getChanges({ since: cursor }); cursor = ch.cursor; /* move ch.residents */ }, 25000);
+- async getChanges({ since }) | scopes: sharedDb:read
+  - Returns: { clock, events: [{ id, townMinute, type, salience, characterId, withCharacterId, text, mine }], residents: [publicCharacter], newDiaryLines, hasMore, cursor }
+  - Poll what changed since a cursor: public town events, events about your own character, and residents whose state changed.
+  - Poll every 20-30 seconds; always continue from the returned cursor. hasMore: true means call again right away.
+  - Also marks the viewer as online (their character earns full pay while its guardian is around).
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async getMyCharacter() | scopes: sharedDb:read
+  - Returns: { character: { characterId, name, status, profile, petName, public, life, movingIn } | null, guardian: { priorities, direction, focus, civicCard, optIns, aspiration }, home, waitingListPosition, control, guidedActions, clock } | { character: null, create: { suggestedNames, suggestedPetNames, petSpecies, likeTags, axes, nameCheck } }
+  - The guardian's view of the viewer's own character (needs, feelings, wishes, worries, skills, job, plan, money, friends, proposals waiting for an answer), or the options for creating one.
+  - life is the server's canonical state; never compute needs, money or relationships in the app.
+  - life.proposals are big life changes the character asks its guardian first (for example asking someone to be best friends): answer with answerProposal; silence for 24 hours lets the character decide.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async createCharacter({ name, petName, petSpecies, personality: { neat, outgoing, active, playful, kind }, likes, dislike, look: { skin, hair, shirt, pants, hood }, homeId }) | scopes: sharedDb:write
+  - Returns: { characterId, name, petName, welcomeBucks, housing: { homeId, weeklyRent, rentDueMinute } | { waitingListPosition, error? } }
+  - Create the viewer's one character in Starhaven (safety-checked names, 200 welcome Bucks) and optionally claim a vacant home.
+  - Names are 2-16 letters. Suggested names (getMyCharacter().create) always pass; any other name needs a clear safety check and may be refused (400 town_name_not_allowed) or be unavailable (503: offer the suggestions).
+  - personality values are -2..2; likes: 3 different interest tags; dislike: 1 other tag; look colours are 0xRRGGBB numbers.
+  - Without a free home the character lodges in the Fivefold guest rooms and joins the waiting list.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async setPriorities({ priorities }) | scopes: sharedDb:write
+  - Returns: { priorities }
+  - Set the guardian's 8 priority sliders (-2..2): saving, pets, work, social, learning, fun, tidy, civic.
+  - Priorities tilt what the character chooses; they never force it (characters have free will).
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async setDirections({ text }) | scopes: sharedDb:write
+  - Returns: { ok: true, text, understoodAs, weights, neighbour } | { ok: false, reason }
+  - Give the character plain-words guidance (up to 200 characters, English). JEV checks it is safe and kind, then shows back how it was understood.
+  - Show understoodAs to the guardian. ok: false keeps the old guidance (unsafe wording, too many changes today (3 a day), or guidance reading paused).
+  - Directions can only raise time with a neighbour, never avoid or target anyone. They are private to the owner.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async setOptIns({ dontVoteForMe, voteForMe, spendLimit, savingsFloor, visitors, workOffline, tendPets }) | scopes: sharedDb:write
+  - Returns: { optIns }
+  - Guardian opt-ins: JEV votes for the character by default (dontVoteForMe: true opts out), daily spend limit (0-500 Bucks, default 50), savings floor, visitors (friends | residents | nobody).
+  - visitors: nobody also stops the character hosting a moved-out friend.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async setFocus({ skills }) | scopes: sharedDb:write
+  - Returns: { focus }
+  - Pick up to 2 Focus skills; the character spends more time on them and grows them faster.
+  - Scholarship grows only from the owner's real learning on Twinkle and cannot be a Focus.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async setCivicCard({ focus, tax, change }) | scopes: sharedDb:write
+  - Returns: { civicCard }
+  - The 3-question civic card the autopilot vote reads (focus: fun | learning | pets | saving | civic; tax: lower | keep | higher; change: new | keep).
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async confirmAspiration({ aspirationId }) | scopes: sharedDb:write
+  - Returns: { aspiration: { id, label, confirmed } }
+  - Confirm the life goal the character proposed (life.aspirationProposed) or choose another; milestones give titles only.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async takeControl({ leaseId, immediate }) | scopes: sharedDb:write
+  - Returns: { leaseId, expiresAt, heartbeatMs, renewed }
+  - Guide the character directly. Returns a lease; call takeControl({ leaseId }) about every 60 s to keep it.
+  - The lease lapses after 3 missed heartbeats (stop renewing when the tab is hidden) and the character goes back to living on its own. immediate: true stops the current activity now instead of at its end.
+  - 409 town_control_elsewhere: another window is guiding this character.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async releaseControl({ leaseId }) | scopes: sharedDb:write
+  - Returns: { released, livingOnAutopilot }
+  - "Let them live": hand the character back to its own free will.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async act({ leaseId, operationId, activity } | { leaseId, operationId, outing, withCharacterId }) | scopes: sharedDb:write
+  - Returns: { operationId, status: queued | applied | rejected, result }
+  - While guiding, tell the character what to do next: an activity (from getMyCharacter().guidedActions.activities) or an outing with another resident.
+  - The server checks it is possible (hours, weather, money, the other resident being free) and applies it within a few seconds; watch getChanges/getMyCharacter for the result. Reuse the same operationId when retrying.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async answerProposal({ proposalId, answer, operationId }) | scopes: sharedDb:write
+  - Returns: { status, result }
+  - Answer a big-life-change question the character asked its guardian: yes, no, or decide (let them decide).
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async getDiary({ since, limit }) | scopes: sharedDb:read
+  - Returns: { since, moments, decisions: [{ text, by: jev | code, at }], lines, numbers: { earned, shifts, meals, sleptHours, friendsSeen, skillUps } }
+  - "While you were away": the top moments, the decisions made for you (and whether JEV or the code made them), and the numbers since a time (ms).
+  - Text comes from fixed English templates; "(quiet stretch)" marks time the town caught up after a pause.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async getElections() | scopes: sharedDb:read
+  - Returns: { offices, elections: [{ id, office, officeLabel, status, votingOpensAt, closesAt, candidates, result, myBallot }], pledges, mottos, minEligibleVoters }
+  - Town offices and elections (Town Chief, Headmaster, Market Warden, Pet Warden; 14-day terms).
+  - Results show counts only (secret ballot), including how many were autopilot votes.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async vote({ electionId, approve }) | scopes: sharedDb:write
+  - Returns: { electionId, approve, abstain }
+  - Approval vote: approve any number of candidates (characterIds). One ballot per account; voting again replaces it until the close.
+  - Voters: account 30+ days old, living in Starhaven 7+ days, active 3 of the last 14 days (403 town_not_eligible otherwise).
+  - Without a manual vote, JEV votes for the character at the close unless the guardian opted out (setOptIns({ dontVoteForMe: true })).
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async declareCandidacy({ electionId, pledges, motto }) | scopes: sharedDb:write
+  - Returns: { electionId, pledges, motto }
+  - Stand for office during the candidacy days: exactly 3 pledges from the list and an optional templated motto id (no free text).
+  - Only the owner can declare, never the character.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async getHousing() | scopes: sharedDb:read
+  - Returns: { homes: [{ homeId, plot, district, name, type, readyMade, weeklyRent, vacant, residentName }], waitingList: [{ position, name, since, movedOut }], mine: { home, rentJar, bucks, waitingListPosition, inStorage } | null, rentDay, graceDays }
+  - The homes board (10 Harbor Row + 10 Lantern Hill plots), the public waiting list and the viewer's rent status.
+  - Rent is weekly in Bucks, due Monday 00:00 KST, with 3 days of grace; a character that can't pay moves out gently (belongings to storage) and gets the next home it can cover from the waiting list.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async claimHome({ homeId }) | scopes: sharedDb:write
+  - Returns: { homeId, weeklyRent, rentDueMinute, rentDueAt }
+  - Claim a vacant home, first come first served. The first rent is due on a Monday at least 3 days away.
+  - 409 town_home_taken when someone else got there first.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async joinWaitingList() | scopes: sharedDb:write
+  - Returns: { waitingListPosition }
+  - Join the public housing waiting list.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+- async leaveWaitingList() | scopes: sharedDb:write
+  - Returns: { waitingListPosition: null }
+  - Leave the housing waiting list.
+  - Limited rollout: app 2610 (Twinkle Minecraft Live) only; other apps get 403 with code town_sdk_not_enabled.
+
 ### Twinkle.leaderboards
 - async get({ boardKey = 'default', limit, cursor } = {}) | scopes: none
   - Returns: { entries: [{ rank, id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt }], scores, cursor, hasMore, personalBest: { id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt } | null }
@@ -1388,6 +1504,33 @@ world.updatePresence({ x, y, z, facing });
   - Read a retired bounty’s original questions and guides from the approval attached to its solve receipt.
   - Use a receiptId returned by getTimeline. Both reads independently check retirement and app ownership; guessing an active or other app’s receipt cannot reveal its questions or guides. Returns build_reward_archive_unavailable (404) if unavailable.
   - Uses that receipt’s frozen approved sheet, never today’s edited question or the mutable draft. Answer keys and tolerances are never returned. Render the question first and offer Reveal guide for learning, without a reward-claim button.
+- await Twinkle.rewards.getBankStatus({ ruleId }) | scopes: rewards:claim
+  - Returns: { mode, ruleId, dayKey, startStep, steps: [{ step, reward: { xp, coins } }], topics: [{ key, title, step, questionsAtStep }], today: { xp, coins, claims }, budgets: { userDailyXP, userDailyCoins } }
+  - Read a generated-quiz rule's ladder: what each step pays, the learner's step on every topic, and today's earnings.
+  - Read on load and after each claim; never compute amounts or steps in the app. Drafts return mode 'preview' from the owner's own rewards.json.
+- await Twinkle.rewards.startBankQuestion({ ruleId, topicKey, skip? }) | scopes: rewards:claim
+  - Returns: { needsQuestion: true, step, reward } | { challengeId, step, question: { id, topicKey, step, prompt, hint?, guide?, answer? }, attempts, maxAttempts, attemptsRemaining, firstTryAvailable, solved, reward, retryReward, stats: { learners, solved, firstSolver: { id, username, solvedAt } | null } }
+  - Serve the learner's open question on a topic, else the next question at their step that they have not seen.
+  - needsQuestion: true means no unseen question exists at the learner's step: offer to write one with generateBankQuestion, saying it uses their AI Energy.
+  - The prompt and guide use LaTeX between $...$ / $$...$$; render them with the Twinkle-served KaTeX (see the vendor guidance). The answer appears only after the learner solves it or runs out of tries; the guide after their first answer.
+  - skip: true gives up on the open question (it counts as a miss on the ladder) and serves the next one.
+- await Twinkle.rewards.generateBankQuestion({ ruleId, topicKey, onProgress?: ({ stage, phase, percent, round? }) => void }) | scopes: rewards:claim
+  - Returns: Same as startBankQuestion with the new question, or { needsQuestion: false } when an unseen question already exists (call startBankQuestion).
+  - Have the server write, double-check and serve a new question at the learner's step. Uses the learner's AI Energy.
+  - Show a progress bar from onProgress: stage is 'pending', 'writing', 'checking' (the independent solve), 'saving' or 'done'; percent follows the server's real phases and the model's streamed output, never goes backwards, and reaches 100 only when the question is served. Silent model thinking inside a phase cannot be measured, so the bar eases forward there rather than guessing.
+  - Takes as long as two GPT-6 Sol calls (tens of seconds): show progress and keep one request in flight. Both calls are billed to the signed-in learner's AI Energy; an empty battery rejects before any work.
+  - build_reward_bank_unverified (503) means two tries did not produce a question whose answers agreed; nothing is stored. build_reward_bank_generation_limit (429) caps questions one learner writes per day.
+  - The question joins the shared bank: every other learner at that step gets it before anything new is written.
+- await Twinkle.rewards.claimBankQuestion({ challengeId, answer: number }) | scopes: rewards:claim
+  - Returns: { correct, awarded, duplicate?, budgetReached?, receipt: { id, questionId, step, xp, coins, attempt, firstTry } | null, balances?, ladder?: { step, previousStep }, question: { ..., guide?, answer? }, attempts, attemptsRemaining, stats }
+  - Answer a bank question. The first answer moves the ladder; a correct answer pays the question's step share.
+  - Send one number (convert a typed fraction yourself). A wrong answer within two seconds of the previous one is refused with build_reward_throttled (429).
+  - ladder appears on the learner's first answer to a question and gives their new step on that topic. Retrying a solved challengeId returns duplicate: true with the original receipt.
+  - budgetReached: true means the solve counted but today's userDailyXP/userDailyCoins is used up. In preview mode nothing is paid and previewReward shows what the live app would pay.
+- await Twinkle.rewards.reportBankQuestion({ questionId, reason }) | scopes: rewards:claim
+  - Returns: { reported: true, duplicate, hidden }
+  - Report a wrong or unclear bank question the learner has seen.
+  - One report per learner per question; three reports hide it from everyone. Show a small 'report this problem' action next to the question.
 
 ### Twinkle.cardCraft
 - await Twinkle.cardCraft.getStatus() | scopes: cardCraft:read

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