@stage5/lumine 0.3.9 → 0.3.11

package/lib/admin-daily.js

@@ -71,6 +71,7 @@ export function runAdmin(
     "media-costs": ["monthly"],
     "reward-activity": [null],
     "reward-review": ["list"],
+    approvals: ["list"],
     todo: ["list"],
     escalation: ["list"],
     featured: ["list", "history"],
@@ -187,6 +188,9 @@ export async function dailyRunGather(options) {
     "reward-activity.json",
   );
   step("reward-review-pending", ["reward-review", "list"], "rr-pending.json");
+  // management approvals (birthdates, teacher signups, meetups) with their
+  // flags: a required report section (agent-guides/lumine-admin.md)
+  step("approvals-pending", ["approvals", "list", "--status", "pending"], "approvals-pending.json");
   step("todos", ["todo", "list"], "todos.json");
   step("escalations", ["escalation", "list"], "escalations.json");
   step("featured-list", ["featured", "list"], "featured-start.json");

package/lib/admin.js

@@ -226,6 +226,91 @@ function parseReviewRequestRef(target, { type: fixedType, typeOption } = {}) {
   return { type, id: parseRequiredInteger(raw, "Request ID", 1) };
 }
 
+// Management approvals (dob/mentor/meetup) and the teacher audit.
+const APPROVAL_USAGE =
+  "Use: lumine admin approvals list [--status pending|approved|rejected|all] [--type dob|mentor|meetup] | show <id> | approve <id> [--reason <text>] | reject <id> [--reason <text>]";
+const TEACHER_USAGE =
+  "Use: lumine admin teachers audit [--limit <1-100>] | revoke <userId> --reason <text>";
+
+function parseApprovalId(target) {
+  const raw = String(target || "").replace(/^approval:/, "");
+  if (!/^\d+$/.test(raw)) throw cliValidationError(APPROVAL_USAGE);
+  return Number(raw);
+}
+
+function buildApprovalOperation({ action, target, options }) {
+  const reason = String(options.adminReason || "").trim();
+  if (!action || action === "list") {
+    return readOperation(
+      "approvals.list",
+      withQuery("/cli/admin/approvals", {
+        status: parseChoice(options.adminStatus || "pending", "--status", [
+          "pending",
+          "approved",
+          "rejected",
+          "all",
+        ]),
+        type: options.adminType
+          ? parseChoice(String(options.adminType), "--type", [
+              "dob",
+              "mentor",
+              "meetup",
+            ])
+          : "",
+      }),
+      { requiresRun: false },
+    );
+  }
+  const id = parseApprovalId(target);
+  if (action === "show" || action === "get") {
+    return readOperation("approvals.show", `/cli/admin/approvals/${id}`, {
+      requiresRun: false,
+    });
+  }
+  if (action === "approve" || action === "reject") {
+    return writeOperation(
+      "approvals.decide",
+      "POST",
+      `/cli/admin/approvals/${id}`,
+      { decision: action, reason },
+      { requiresRun: false },
+    );
+  }
+  throw cliValidationError(APPROVAL_USAGE);
+}
+
+function buildTeacherOperation({ action, target, options }) {
+  if (!action || action === "audit") {
+    return readOperation(
+      "teachers.audit",
+      withQuery("/cli/admin/teachers/audit", {
+        limit: options.limit
+          ? parseRequiredInteger(options.limit, "--limit", 1, 200)
+          : "",
+      }),
+      { requiresRun: false },
+    );
+  }
+  if (action === "revoke" || action === "remove") {
+    const userId = String(target || "");
+    if (!/^\d+$/.test(userId)) throw cliValidationError(TEACHER_USAGE);
+    const reason = String(options.adminReason || "").trim();
+    if (!reason) {
+      throw cliValidationError(
+        "lumine admin teachers revoke <userId> needs --reason <text> (kept on the request's record).",
+      );
+    }
+    return writeOperation(
+      "teachers.revoke",
+      "POST",
+      `/cli/admin/teachers/${userId}/revoke`,
+      { reason },
+      { requiresRun: false },
+    );
+  }
+  throw cliValidationError(TEACHER_USAGE);
+}
+
 // Builds the operation for list/show/approve/reject/revoke. `fixedType` is set
 // by the per-type aliases; `listStatuses` keeps their own --status choices.
 function buildReviewRequestOperation({
@@ -718,7 +803,12 @@ export async function adminCommand(options) {
       throw noActiveRunError();
     }
     runId = Number(selectedRun?.id || 0);
-    if (!runId && !correctionSessionId && !commentSessionId) {
+    if (
+      !runId &&
+      !correctionSessionId &&
+      !commentSessionId &&
+      !operation.runOptional
+    ) {
       if (operation.correctionEligible) {
         const error = new Error(
           `Start a correction session first: lumine admin correction start ${operation.correctionCommentId}.`,
@@ -2042,6 +2132,16 @@ export function parseAdminOperation(options) {
     }
   }
 
+  if (namespace === "approvals" || namespace === "approval") {
+    // Management approvals: birthdates, teacher signups (mentor), meetups.
+    // Mikey's decisions, any time; each comes with its evidence (approvals.ts).
+    return buildApprovalOperation({ action, target, options });
+  }
+  if (namespace === "teachers" || namespace === "teacher") {
+    // Approved teachers: an audit any time, and a clean removal of the status.
+    return buildTeacherOperation({ action, target, options });
+  }
+
   if (namespace === "review" || namespace === "reviews") {
     // Every Build unlock in one queue. Mikey's own decisions: any time, never
     // part of a delegated Zero/Ciel daily run.
@@ -2578,7 +2678,7 @@ export function parseAdminOperation(options) {
     // long as two GPT-6.1 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] | report <buildId> [--days 1].";
+      "Usage: lumine admin reward-bank coverage <buildId> [--max-step 3] | seed <buildId> [--max-step 3] [--identity zero|ciel|auto] | report <buildId> [--days 1].";
     const buildId = parseRequiredInteger(
       target || options.adminBuild,
       "Build ID",
@@ -2613,12 +2713,21 @@ export function parseAdminOperation(options) {
       );
     }
     if (action === "seed") {
+      // Inside a daily run it seeds as that run's identity. Without one the
+      // owner can seed whenever they like (Mikey, 2026-10-04): the server
+      // checks the account and acts as --identity zero|ciel (default: today's
+      // scheduled identity), billed to that identity's AI Energy as before.
+      const identity = options.adminIdentity
+        ? String(options.adminIdentity).toLowerCase()
+        : "";
+      if (identity && !["zero", "ciel", "auto"].includes(identity))
+        throw cliValidationError("--identity must be zero, ciel or auto.");
       return writeOperation(
         "reward-bank.seed",
         "POST",
         "/cli/admin/reward-bank/seed",
-        { buildId, maxStep },
-        { timeoutMs: 240000 },
+        { buildId, maxStep, ...(identity ? { identity } : {}) },
+        { timeoutMs: 240000, runOptional: true },
       );
     }
     throw cliValidationError(usage);
@@ -5264,7 +5373,7 @@ function printMeetupCrew(crew) {
   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}` : ""}`,
+      `  Plan (${plan.status}): ${plan.date}${plan.time ? ` at ${plan.time}` : ""} in ${plan.area}: ${plan.activity}${plan.note ? ` · note: ${plan.note}` : ""}`,
     );
   }
   if (crew.planApprovedBy?.username) {
@@ -5390,7 +5499,7 @@ function printMeetupResult({ operation, data, result }) {
     }
     if (crews.some((crew) => crew.waitingFor)) {
       console.log(
-        "Review: lumine admin meetup show <crewId>, then approve-plan | send-back --note | approve --attended <ids>.",
+        "Review: lumine admin meetup show <crewId>, then approve-crew | approve-plan | approve-grownup | send-back --note | approve --attended <ids> (classroom plans: approve at the headmaster desk with a room and times).",
       );
     }
     return;
@@ -5548,6 +5657,86 @@ function printReviewEvents(events) {
     );
 }
 
+const APPROVAL_LABELS = { dob: "birthdate", mentor: "teacher", meetup: "meetup" };
+const approvalDate = (seconds) =>
+  seconds ? new Date(Number(seconds) * 1000).toISOString().slice(0, 10) : "?";
+
+function printEvidence(evidence) {
+  if (!evidence) return;
+  const a = evidence.account || {};
+  console.log(
+    `Account: ${a.username} (#${a.userId}) · real name ${a.realName || "-"} · joined ${approvalDate(a.joinedAt)} · last active ${approvalDate(a.lastActive)} · age ${a.age ?? "not given"} · email ${a.verifiedEmail || "-"}`,
+  );
+  if (evidence.request) {
+    const r = evidence.request;
+    console.log(
+      `Request: ${[r.branchName && `branch ${r.branchName}`, r.className && `class ${r.className}`, r.realName && `name ${r.realName}`, r.email && `email ${r.email}`, r.dob && `birthdate ${r.dob}`].filter(Boolean).join(" · ") || "-"} · sent ${approvalDate(r.requestedAt)}`,
+    );
+  }
+  console.log(
+    `Invited by: ${evidence.invitedBy ? `${evidence.invitedBy.username || "#" + evidence.invitedBy.userId} (${evidence.invitedBy.source || "invite"})` : "nobody (passphrase or other)"}`,
+  );
+  const act = evidence.activity || {};
+  console.log(
+    `Activity: ${act.comments || 0} comments (${act.commentsLast30Days || 0} in 30 days) · ${act.chatMessages || 0} chat messages`,
+  );
+  const linked = evidence.linkedAccounts || [];
+  console.log(
+    `Linked accounts: ${linked.length}${evidence.linkedEvidenceTruncated ? " (evidence truncated)" : ""}`,
+  );
+  for (const l of linked.slice(0, 15)) {
+    console.log(
+      `  - ${l.username} (#${l.userId}) via ${(l.linkedBy || []).join("+")}${l.sharedDeviceCount ? ` (${l.sharedDeviceCount} device)` : ""} · age ${l.age ?? "?"} · ${l.isTeacherOrStaff ? "teacher/staff" : "member"} · joined ${approvalDate(l.joinedAt)}${l.banned ? " · BANNED" : ""}`,
+    );
+  }
+  console.log(
+    `Flags: ${(evidence.flags || []).length ? evidence.flags.join(", ") : "none"}`,
+  );
+  if (evidence.note) console.log(evidence.note);
+}
+
+function printApprovalResult({ operation, data }) {
+  if (operation.name === "approvals.list") {
+    const items = data.items || [];
+    if (!items.length) return console.log("No approval requests.");
+    for (const item of items) {
+      console.log(
+        `${item.ref} · ${APPROVAL_LABELS[item.type] || item.type} · ${item.status} · ${item.requesterUsername} (#${item.requesterId}) · ${approvalDate(item.requestedAt)}${item.flags ? ` · flags: ${item.flags.length ? item.flags.join(", ") : "none"}` : ""}`,
+      );
+    }
+    return;
+  }
+  if (operation.name === "approvals.show") {
+    const item = data.item || {};
+    console.log(
+      `${item.ref} · ${APPROVAL_LABELS[item.type] || item.type} · ${item.status} · ${item.requesterUsername} (#${item.requesterId})`,
+    );
+    printEvidence(data.evidence);
+    return;
+  }
+  if (operation.name === "approvals.decide") {
+    console.log(
+      `${data.ref} ${data.status}: ${APPROVAL_LABELS[data.type] || data.type} request from ${data.requesterUsername} (#${data.requesterId}).`,
+    );
+    return;
+  }
+  if (operation.name === "teachers.audit") {
+    console.log(
+      `Audited ${data.audited || 0} approved teachers · ${data.flagged || 0} with flags (riskiest first).`,
+    );
+    for (const teacher of data.teachers || []) {
+      console.log("");
+      printEvidence(teacher);
+    }
+    return;
+  }
+  if (operation.name === "teachers.revoke") {
+    console.log(
+      `Teacher status removed from #${data.userId} (achievements ${(data.removedAchievementIds || []).join(", ")}; request #${data.approvalItemId ?? "-"} marked rejected). Reason kept: ${data.reason}`,
+    );
+  }
+}
+
 function printReviewRequestResult({ operation, data, result }) {
   if (operation.name === "review.list") {
     const items = Array.isArray(data.items) ? data.items : [];
@@ -5718,6 +5907,10 @@ function printAdminResult({ operation, result }) {
     }
     return;
   }
+  if (operation.name.startsWith("approvals.") || operation.name.startsWith("teachers.")) {
+    printApprovalResult({ operation, data });
+    return;
+  }
   if (operation.name.startsWith("review.")) {
     printReviewRequestResult({ operation, data, result });
     return;

package/lib/commands.js

@@ -3013,6 +3013,8 @@ export function printHelp() {
   lumine admin sponsor integrity get <case-id> [--json]
   lumine admin sponsor integrity review <case-id> --decision clear|hold|flag|disqualify [--note <evidence>] [--json]
   lumine admin review list [--type rewards|project|storage|cardcraft] [--status queue|pending|approved|rejected|all] [--cursor <c>] | show <type:id> [--dir <path>] | approve <type:id> [--config <rules.json>] [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject|revoke <type:id> [--reason <text>] | propose rewards:<id> --dir <edited-snapshot> --config <rules.json>
+  lumine admin approvals list [--status pending|approved|rejected|all] [--type dob|mentor|meetup] | show <id> | approve <id> [--reason <text>] | reject <id> [--reason <text>]   (management approvals with evidence: birthdates, teacher signups, meetups)
+  lumine admin teachers audit [--limit <1-100>] | revoke <userId> --reason <text>   (approved teachers, riskiest first; revoke removes the status cleanly)
   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>]
@@ -3062,7 +3064,7 @@ export function printHelp() {
   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 reward-bank seed <buildId> [--max-step 3] [--identity zero|ciel|auto] [--json]   (writes ONE missing seed question, lowest step first, billed to Zero/Ciel's AI Energy; inside a daily run or on its own, owner only)
   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]

package/lib/rewards.js

@@ -71,6 +71,8 @@ function printDeclaration(result, { prefix = "" } = {}) {
           ? `completion · at least ${rule.minSeconds || 0}s`
           : rule.verifier === "generated-quiz"
             ? "question bank · server-written, double-checked questions on a step ladder"
+            : rule.verifier === "archive-rematch"
+              ? "daily rematch · one retired puzzle a day for players who never met it"
             : `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}`,
@@ -241,11 +243,13 @@ 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" | "generated-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" | "archive-rematch",
                 "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.
+archive-rematch (at most one) needs no sheet either: each day the server picks one retired
+until-earned puzzle for players who never met it and checks the answer against its frozen sheet.
 generated-quiz rules need no sheet: the server writes each question for a topic at the learner's step
 (GPT-6.1 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/lib/sdk.js

@@ -227,8 +227,76 @@ export const SDK_CLI_METHODS = {
   "rewards.getArchivedProblem": {
     path: "api/rewards/archived-problem", special: "rewards", operation: "archived-problem",
     scopes: ["rewards:claim"], readOnly: true,
+    writeWhen: (args) => args.withGuide === true,
+    // withGuide marks the puzzle as studied for this viewer (unrated practice,
+    // no paid rematch of it later).
+    mapArgs: (args) => ({
+      receiptId: args.receiptId,
+      ...(args.withGuide === true ? { withGuide: true } : {}),
+    }),
+  },
+  // Puzzle vault (retired until-earned puzzles): practice for a practice
+  // rating and solver explanations. Pays nothing; the server checks answers
+  // against the frozen sheet and never returns them.
+  "rewards.practiceCheck": {
+    path: "api/rewards/practice-check", special: "rewards", operation: "practice-check",
+    scopes: ["rewards:claim"], write: true,
+    mapArgs: (args) => ({
+      receiptId: args.receiptId,
+      ...(args.answer !== undefined ? { answer: args.answer } : {}),
+      ...(args.answers !== undefined ? { answers: args.answers } : {}),
+      ...(args.text !== undefined ? { text: args.text } : {}),
+    }),
+  },
+  "rewards.getPracticeBoard": {
+    path: "api/rewards/practice-board", special: "rewards", operation: "practice-board",
+    scopes: ["rewards:claim"], readOnly: true,
+    mapArgs: () => ({}),
+  },
+  "rewards.getRelatedArchive": {
+    path: "api/rewards/related-archive", special: "rewards", operation: "related-archive",
+    scopes: ["rewards:claim"], readOnly: true,
+    mapArgs: (args) =>
+      args.receiptId !== undefined ? { receiptId: args.receiptId } : { ruleId: args.ruleId },
+  },
+  "rewards.listExplanations": {
+    path: "api/rewards/explanations", special: "rewards", operation: "explanations",
+    // Reading explanations marks the puzzle as studied for this account.
+    scopes: ["rewards:claim"], write: true,
     mapArgs: (args) => ({ receiptId: args.receiptId }),
   },
+  "rewards.postExplanation": {
+    path: "api/rewards/explanation-post", special: "rewards", operation: "explanation-post",
+    scopes: ["rewards:claim"], write: true,
+    mapArgs: (args) => ({ receiptId: args.receiptId, text: args.text }),
+  },
+  "rewards.voteExplanation": {
+    path: "api/rewards/explanation-vote", special: "rewards", operation: "explanation-vote",
+    scopes: ["rewards:claim"], write: true,
+    mapArgs: (args) => ({ id: args.id, vote: args.vote }),
+  },
+  "rewards.deleteExplanation": {
+    path: "api/rewards/explanation-delete", special: "rewards", operation: "explanation-delete",
+    scopes: ["rewards:claim"], write: true,
+    mapArgs: (args) => ({ id: args.id }),
+  },
+  // Daily rematch: both calls write (the day's pick, a paid answer), so both
+  // stay behind --allow-write.
+  "rewards.getRematch": {
+    // Not read-only: the day's first call stores the day's pick.
+    path: "api/rewards/rematch", special: "rewards", operation: "rematch",
+    scopes: ["rewards:claim"], write: true,
+    mapArgs: () => ({}),
+  },
+  "rewards.claimRematch": {
+    path: "api/rewards/rematch-claim", special: "rewards", operation: "rematch-claim",
+    scopes: ["rewards:claim"], write: true,
+    mapArgs: (args) => ({
+      ...(args.answer !== undefined ? { answer: args.answer } : {}),
+      ...(args.answers !== undefined ? { answers: args.answers } : {}),
+      ...(args.text !== undefined ? { text: args.text } : {}),
+    }),
+  },
   "rewards.start": {
     path: "api/rewards/start",
     special: "rewards",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "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-10-03T09:02:05.836Z
+Generated: 2026-10-04T06:59:28.249Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -34,7 +34,7 @@ Generated: 2026-10-03T09:02:05.836Z
 - 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' | '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.1 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.
+- 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.1 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. 'archive-rematch' is the daily rematch: one retired until-earned puzzle of the app a day, chosen by the server (celebrated, high-rated solves first; never repeated within 60 days) and answered from its frozen approved sheet. Declare at most one, with no questions, sets, progression, series, minSeconds or completionProof, e.g. { "id": "rematch-daily", "title": "Daily rematch", "xp": 20000, "coins": 1000, "verifier": "archive-rematch", "retry": { "xpPercent": 50, "coinsPercent": 0, "paidAttempts": 3 }, "maxAttempts": null }. Only players who never met that puzzle (no official receipt, wrong answer or challenge while it was live, no Vault practice) may answer it; its receipt does not use userDailyClaims but counts toward userDailyXP/userDailyCoins. Use getRematch and claimRematch; start and claim refuse it.
 - 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.
 
@@ -1534,16 +1534,66 @@ world.updatePresence({ x, y, z, facing });
   - tier on a recent solve says how loudly to celebrate: 'legendary' (first solve of a long-undefeated puzzle), 'hard-won', 'first-solve', or plain 'solved'. It is fixed at solve time, so it never changes later.
   - No questions, answers, guides or private work are ever returned. Names are the same public names the XP leaderboard shows; other players who missed a puzzle are counted, never named. Drafts and previews return mode 'preview' with empty lists.
 - await Twinkle.rewards.getTimeline({ ruleId?, cursor?, limit? } = {}) | scopes: rewards:claim
-  - Returns: { mode: "live", dayKey, entries: [{ receiptId, ruleId, ruleTitle, setKey, title, promptPreview, dayKey, closedAt, solvedAt, solver: { userId, username }, firstSolver, xp, coins, attempt }], nextCursor } | { mode: "preview", entries: [], nextCursor: null, message }
+  - Returns: { mode: "live", dayKey, entries: [{ receiptId, ruleId, ruleTitle, setKey, title, promptPreview, dayKey, closedAt, solvedAt, solver: { userId, username }, firstSolver, xp, coins, attempt, story: { tier, attempt, failersBefore, failuresBefore, daysStanding } | null, puzzle: { rating, solvers, failers, failures } | null, vault: { rating, solvers, failers, failures } | null, rematchOpen }], nextCursor } | { mode: "preview", entries: [], nextCursor: null, message }
   - Browse confirmed solves of retired until-earned quiz bounties, newest first.
   - A solve appears only after the next site reset (UTC midnight, 9 AM Korea). Today’s solves, unsolved sets, standing quizzes and dated quizzes are excluded. The server decides retirement; client dates cannot unlock content. Zero-reward correct solves are included.
   - One entry per solve receipt, with firstSolver identifying the first receipt for that rule and set across approved versions. limit defaults to 20, max 50; pass nextCursor unchanged for older solves and omit it when changing ruleId. Pages may have fewer entries when old question sheets cannot be recovered; continue while nextCursor is present.
   - No daily-claim limit applies to reading. Requires the current approved published runtime grant; previews return an empty timeline. Never awards or changes balances. Open a receipt with getArchivedProblem to load the original question and guide.
-- await Twinkle.rewards.getArchivedProblem({ receiptId }) | scopes: rewards:claim
-  - Returns: { mode: "live", entry: <same solve entry as getTimeline>, questions: [{ prompt, hint?, guide? }] } | { mode: "preview", entry: null, questions: [], message }
+  - Museum fields: story is how THAT solve went, fixed at solve time (tier 'solved' | 'first-solve' | 'hard-won' | 'legendary', the solver's attempt, how many other players had missed it and how often, days it stood); null for receipts older than solve logging. puzzle is the official challenge rating and counts now; vault is the puzzle's living practice stats (its own rating, practice solvers, players whose first practice answer missed, all wrong practice answers), or null before anyone practised it. Counts only: players who missed are never named.
+  - rematchOpen is true on the entry that is today's daily rematch while the viewer can still answer it for pay: label it and open it as the rematch, not as a lesson. Daily-rematch receipts are never timeline entries.
+- await Twinkle.rewards.getArchivedProblem({ receiptId, withGuide?: true }) | scopes: rewards:claim
+  - Returns: { mode: "live", entry: <same solve entry as getTimeline, with rematchOpen>, questions: [{ prompt, hint?, guide? }], rematchOpen } | { mode: "preview", entry: null, questions: [], message }
   - 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.
+  - entry carries the same story, puzzle and vault museum fields as getTimeline.
+  - Guides are returned only with withGuide: true. Asking for the guide counts as having studied the puzzle: the viewer's Vault practice of it is unrated and it can never be their paid daily rematch. Offer the guide behind an explicit Reveal step and say so. withGuide on today's rematch puzzle is refused (build_reward_rematch_open, 409) while the viewer can still answer it for pay.
+- await Twinkle.rewards.practiceCheck({ receiptId, answer?: number, answers?: [number], text?: string }) | scopes: rewards:claim
+  - Returns: { mode: "live", correct, counted: true, firstAttempt, attempts, solvedAt: number | null, rated, read?: { understood: true, value }, practice: { rating, solves, rank: number | null }, vault: { rating, solvers, failers, failures } } | { mode: "live", correct: false, counted: false, read: { understood: false, value: null } } | { mode: "preview", correct: false, counted: false, practice: null, vault: null, message }
+  - Try a retired puzzle again (the Vault): checks an answer against the frozen sheet for a practice rating, never XP or Coins.
+  - receiptId is any receipt of a retired set (from getTimeline). The answer is compared with the same tolerance as claims; the answer key is never returned. Send answer for a one-question set, answers (in order) for several, or the learner's raw text for a one-question set: text goes through the same answer reader as interpretAnswer (puzzle text for format only, same rate bucket). Unreadable text returns counted: false and uses no attempt; ask the learner to type just the number.
+  - Practice rating: the first answer a player gives on a puzzle is rated once (correct = win, wrong = loss) against the puzzle's Vault rating, and both ratings move. Later answers only count attempts; a later correct answer still marks the puzzle solved (solvedAt) and opens postExplanation. Players who earned or missed the set officially, had a challenge on its rule while it was live, or studied it (opened its guide or explanations) may practise it but are not rated (rated: false). The official challenge rating is never changed by practice.
+  - Pays nothing. Rate limited per learner (build_reward_throttled, 429). Errors: build_reward_archive_unavailable (404) for a receipt that is not a retired puzzle, build_reward_practice_answers_invalid (400).
+  - Today's daily rematch puzzle cannot be practised by a viewer who may still answer it as the rematch (build_reward_rematch_open, 409); practising any puzzle in the Vault makes the viewer ineligible for it as a future rematch.
+- await Twinkle.rewards.getPracticeBoard() | scopes: rewards:claim
+  - Returns: { mode: "live", top: [{ rank, userId, username, profilePicUrl, rating, solves }], me: { rating, solves, rank: number | null } | null, hardest: [{ receiptId, ruleId, setKey, title, vault: { rating, solvers, failers, failures } }], solved: ["ruleId:setKey"] } | { mode: "preview", top: [], me: null, hardest: [], solved: [], message }
+  - Vault practice standings: top practice-rated players, the viewer's own standing, the toughest retired puzzles and which ones the viewer solved in practice.
+  - top lists the 10 highest practice ratings among players with at least one rated answer; profilePicUrl is an absolute https URL or null. me.rank is null until the viewer has a rated answer. hardest is up to 5 retired puzzles with the highest Vault rating that three or more players missed on their first practice answer. solved lists the viewer's practice solves only; official solves are in getTimeline.
+- await Twinkle.rewards.getRelatedArchive({ ruleId } | { receiptId }) | scopes: rewards:claim
+  - Returns: { mode: "live", entries: [<getTimeline entry>] } | { mode: "preview", entries: [], message }
+  - Up to 3 retired puzzles that share an idea with today's puzzle (after answering it) or with a retired puzzle.
+  - Idea tags come from each set's questions[0].guide.ideaTags (1-3 kebab-case slugs). The current release's copy of a set wins, else the frozen sheet. Ordered by shared tags, then newest; one entry per retired set (its earliest receipt).
+  - With ruleId: today's set of that until-earned rule. It would be a hint, so it opens only once the viewer has a receipt for today's set or a challenge on it with a wrong attempt; otherwise build_reward_related_locked (409). With receiptId: no gate; the source puzzle is excluded.
+  - Rate limited (build_reward_throttled, 429). Daily-rematch receipts are never related entries.
+- await Twinkle.rewards.listExplanations({ receiptId }) | scopes: rewards:claim
+  - Returns: { mode: "live", entries: [{ id, userId, username, profilePicUrl, text, votes, myVote: 0 | 1, createdAt, updatedAt, mine, pinned }], canModerate } | { mode: "preview", entries: [], message }
+  - Solvers' explanations of a retired puzzle, most helpful first.
+  - Up to 50, ordered by votes then age. pinned marks the top entry when it has two or more votes. text is user content: escape it when rendering (never innerHTML). Only retired puzzles have explanations (build_reward_archive_unavailable, 404 otherwise).
+  - Refused with build_reward_rematch_open (409) for today's rematch puzzle while the viewer may still answer it for pay.
+  - Reading explanations counts as having studied the puzzle (unrated practice, never that viewer's paid rematch). canModerate is true for the app's owner and Twinkle admins, who may delete any explanation. Rate limited (build_reward_throttled, 429).
+- await Twinkle.rewards.postExplanation({ receiptId, text }) | scopes: rewards:claim
+  - Returns: { mode: "live", entry: <listExplanations entry> } | { mode: "preview", entry: null, message }
+  - Post or edit the viewer's explanation of a retired puzzle they solved.
+  - Only players who solved that set officially (any receipt) or in practice may post (build_reward_explanation_not_solver, 403). 20-1200 characters after trimming (build_reward_explanation_invalid, 400). One per player per puzzle: posting again replaces the text and keeps its votes. Pays nothing; rate limited.
+- await Twinkle.rewards.voteExplanation({ id, vote: 1 | 0 }) | scopes: rewards:claim
+  - Returns: { mode: "live", id, votes, myVote } | { mode: "preview", id: null, votes: 0, myVote: 0, message }
+  - Mark another player's explanation helpful (1) or take that back (0).
+  - One vote per player per explanation; repeating a vote changes nothing. Voting for your own explanation is refused (build_reward_explanation_own_vote, 403).
+- await Twinkle.rewards.deleteExplanation({ id }) | scopes: rewards:claim
+  - Returns: { mode: "live", id, deleted: true } | { mode: "preview", id: null, deleted: false, message }
+  - Delete the viewer's own explanation, or any explanation as the app's owner or a Twinkle admin.
+  - Own explanations, or any explanation for the app's owner and Twinkle admins (listExplanations.canModerate); otherwise build_reward_explanation_not_owner (403). Its votes are removed with it.
+- await Twinkle.rewards.getRematch() | scopes: rewards:claim
+  - Returns: { mode: "live", dayKey, ruleId, entry: <getTimeline entry with story, puzzle, vault>, prompt, hint?, questionCount, eligible, reason?: "already-attempted" | "already-practised" | "already-studied" | "already-earned", attempts, earned: { id, challengeId, ruleId, setKey, dayKey, xp, coins, attempt, createdAt } | null, reward: { xp, coins }, retryReward: { xp, coins }, paidAttempts } | { mode: "live", entry: null, prompt: null, eligible: false, reason: "no-puzzle", ... } | { mode: "preview", entry: null, prompt: null, eligible: false, attempts: 0, earned: null, message }
+  - Today's daily rematch: one retired puzzle, whether the viewer may answer it for XP/Coins, and what it pays.
+  - Needs an approved archive-rematch rule (build_reward_rematch_unavailable, 404). The server picks one retired until-earned puzzle per site day for everyone. Only the prompt and hint are returned (never the answer or guide). eligible is false with a reason for players who met the puzzle officially, practised it in the Vault, or already earned today's rematch (earned holds that receipt). Ineligible players may practise it in the Vault (no pay) once they cannot answer it for pay.
+  - attempts counts today's wrong rematch answers; reward is the first-try amount and retryReward the amount for paid retries (up to paidAttempts); later correct answers count as solved but pay nothing.
+  - reason 'already-studied' means the viewer opened that puzzle's guide or explanations before. reason 'no-puzzle' (entry null) when no retired puzzle qualifies today or today's stored pick can no longer be read. The day's first call stores the day's pick, chosen among the strongest candidates with a server-only seed so it cannot be predicted.
+- await Twinkle.rewards.claimRematch({ answer?: number, answers?: [number], text?: string }) | scopes: rewards:claim
+  - Returns: { mode: "live", awarded: false, correct: false, counted: true, challengeId, attempts, attemptsRemaining, nextReward: { xp, coins }, read?, practice, vault } | { mode: "live", awarded: true, duplicate: false, correct: true, counted: true, read?, receipt: { id, challengeId, ruleId, xp, coins, attempt, firstTry, createdAt }, balances: { xp, coins }, practice, vault } | { mode: "live", awarded: true, duplicate: true, receipt, balances } | { mode: "live", awarded: false, correct: false, counted: false, read: { understood: false, value: null } } | { mode: "preview", awarded: false, counted: false, message }
+  - Answer today's daily rematch. A correct answer writes a real receipt (ledger, budgets, Home feed story, leaderboard).
+  - Same answer check and tolerance as claim; text is read by the same answer reader as interpretAnswer (unreadable text uses no try). First try pays the rule's full amounts, paid retries the retry share, later correct answers pay nothing. One rematch receipt per player per site day; a repeat call after it returns the same receipt (duplicate: true).
+  - Does not use the daily bounty count (userDailyClaims) but counts toward userDailyXP/userDailyCoins (build_reward_budget errors as for claim). Each answer also counts as the player's Vault answer for that puzzle (practice rating, Vault stats). Errors: build_reward_rematch_ineligible (409), build_reward_rematch_unavailable (404/409), build_reward_rematch_day_changed (409, reload getRematch), build_reward_throttled (429; wait between wrong answers).
 - 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.

package/sdk/LUMINE_ADMIN.md

@@ -1160,6 +1160,27 @@ lumine admin review approve rewards:70 --config rules.json --json
 lumine admin review propose rewards:70 --dir /private/tmp/reward-review-70 --config rules.json --json
 ```
 
+### Management approvals and the teacher audit (any time; also a full-daily-review duty; added 2026-10-04)
+
+Birthdate, teacher-signup (`mentor`) and meetup-achievement requests, each with its evidence: the account, the request, who invited them, accounts linked by verified email, exact device or a manual identity bucket (with each one's age and role), activity, and flags. These are Mikey-only and need no daily run.
+
+```bash
+lumine admin approvals list [--status pending|approved|rejected|all] [--type dob|mentor|meetup]
+lumine admin approvals show <id>
+lumine admin approvals approve|reject <id> [--reason <text>]
+lumine admin teachers audit [--limit 1-100]
+lumine admin teachers revoke <userId> --reason <text>
+```
+
+- Flags are pointers, not verdicts: a school device can link strangers. Judge each case, recommend, and act only on Mikey's decision.
+- `teachers audit` lists approved teachers, riskiest first.
+- `teachers revoke` removes a teacher status cleanly:
+  - the mentor achievement, plus the teenager/adult achievements the teacher approval gave unless a separately approved birthdate supports them;
+  - the teacher title and the public "unlocked" posts;
+  - the moderation powers that came with the level, by recounting points.
+- Revoke marks the request rejected, keeps who, when and why, and refuses sage/founder holders.
+- The daily-run procedure is in `agent-guides/lumine-admin.md`.
+
 ### Build XP/Coin reward approvals (any time; also a full-daily-review duty)
 
 The creator's Lumine designs the rewards and writes them into the app. The