@stage5/lumine 0.2.90 → 0.2.91

package/lib/admin.js

@@ -138,6 +138,8 @@ function readBuildReviewContextFile(filePath) {
 
 const MAX_REWARD_CONFIG_FILE_BYTES = 256 * 1024;
 const REWARD_REVIEW_STATUSES = ["pending", "approved", "all"];
+const CHAT_REPORT_STATUSES = ["open", "reviewing", "resolved", "dismissed"];
+const CHAT_REPORT_LIST_STATUSES = ["pending", ...CHAT_REPORT_STATUSES, "all"];
 const REWARD_REVIEW_DECISIONS = ["approve", "reject", "revoke"];
 const REWARD_PROPOSAL_MAX_FILES = 500;
 const REWARD_PROPOSAL_MAX_BYTES = 5 * 1024 * 1024;
@@ -648,6 +650,29 @@ export async function adminCommand(options) {
       },
     };
   }
+  if (operation.name === "chat-reports.export" && operation.evidenceDir) {
+    // The package goes to disk only; the printed result keeps paths, sizes
+    // and hashes, never the evidence itself.
+    const written = writeEvidencePackage({
+      directory: operation.evidenceDir,
+      files: result?.data?.files,
+    });
+    const { files: _files, manifest: _manifest, ...summary } = result?.data || {};
+    if (
+      summary.manifestSha256 &&
+      summary.manifestSha256 !== written.manifestSha256
+    ) {
+      const error = new Error(
+        "The written manifest.json does not match the hash the server recorded. Export again into a new directory.",
+      );
+      error.code = "LUMINE_ADMIN_EVIDENCE_HASH_MISMATCH";
+      throw error;
+    }
+    result = {
+      ...result,
+      data: { ...summary, evidenceDirectory: written.directory, files: written.files },
+    };
+  }
   if (operation.name === "news.claim") {
     const artifacts = writeNewsClaimArtifacts({
       result,
@@ -1295,6 +1320,86 @@ function noActiveRunError() {
   return error;
 }
 
+function requireChatSafetyNote(value) {
+  const note = String(value || "").trim();
+  if (!note) {
+    throw cliValidationError(
+      "Say why with --note <text>; it is kept in the safety audit trail.",
+    );
+  }
+  if (note.length > 2000) {
+    throw cliValidationError("--note must be at most 2000 characters.");
+  }
+  return note;
+}
+
+function parseIdList(value, label) {
+  const ids = String(value || "")
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => parseRequiredInteger(part, label, 1));
+  if (!ids.length) throw cliValidationError(`${label} needs at least one id.`);
+  return Array.from(new Set(ids));
+}
+
+// Writes a child-safety evidence package into a new or empty private
+// directory and checks every written file against the server's SHA-256
+// manifest, so what lands on disk is exactly what the server hashed.
+export function writeEvidencePackage({ directory, files }) {
+  const list = Array.isArray(files) ? files : [];
+  const manifestFile = list.find((file) => file?.path === "manifest.json");
+  if (!manifestFile) {
+    throw cliValidationError("The evidence package has no manifest.json.");
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(String(manifestFile.content || ""));
+  } catch {
+    throw cliValidationError("The evidence manifest is not valid JSON.");
+  }
+  let written;
+  try {
+    written = writeRewardReviewSnapshot({ directory, files: list });
+  } catch (error) {
+    error.message = String(error.message || "").replaceAll("--dir", "--out");
+    throw error;
+  }
+  const sha = (text) => createHash("sha256").update(text).digest("hex");
+  const mismatches = [];
+  for (const entry of manifest.files || []) {
+    const target = path.join(written.directory, entry.path);
+    const actual = existsSync(target) ? sha(readFileSync(target)) : "missing";
+    if (actual !== entry.sha256) mismatches.push(entry.path);
+  }
+  const listed = new Set((manifest.files || []).map((entry) => entry.path));
+  for (const file of list) {
+    if (file.path !== "manifest.json" && !listed.has(file.path)) {
+      mismatches.push(file.path);
+    }
+  }
+  if (mismatches.length) {
+    const error = new Error(
+      `The evidence package in ${written.directory} does not match its manifest (${mismatches.join(", ")}). Do not hand it over; export again into a new directory.`,
+    );
+    error.code = "LUMINE_ADMIN_EVIDENCE_HASH_MISMATCH";
+    throw error;
+  }
+  return {
+    directory: written.directory,
+    manifestSha256: sha(readFileSync(path.join(written.directory, "manifest.json"))),
+    files: written.files.map((file) => ({
+      path: file.path.replace(/^\//, ""),
+      bytes: file.bytes,
+      sha256:
+        file.path === "/manifest.json"
+          ? null
+          : (manifest.files || []).find((entry) => `/${entry.path}` === file.path)
+              ?.sha256 || null,
+    })),
+  };
+}
+
 export function parseAdminOperation(options) {
   const [namespace = "", action = "", target = "", extra = ""] =
     options.positional;
@@ -1594,6 +1699,159 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "chat-reports" || namespace === "chat-report") {
+    // Members' in-chat message reports. Like reward reviews they are handled
+    // any time, never inside a daily-run lease; recording an outcome only
+    // annotates the report and never acts against a member.
+    if (!action || action === "list") {
+      return readOperation(
+        "chat-reports.list",
+        withQuery("/cli/admin/chat-reports", {
+          status: parseChoice(
+            options.adminStatus || "pending",
+            "--status",
+            CHAT_REPORT_LIST_STATUSES,
+          ),
+          beforeId: options.adminCursor
+            ? parseRequiredInteger(options.adminCursor, "--cursor", 1)
+            : "",
+          limit: options.limit,
+        }),
+        { requiresRun: false },
+      );
+    }
+    if (action === "show" || action === "get") {
+      const reportId = parseRequiredInteger(target, "Chat report ID", 1);
+      return readOperation(
+        "chat-reports.show",
+        `/cli/admin/chat-reports/${reportId}`,
+        { requiresRun: false },
+      );
+    }
+    if (action === "set") {
+      const reportId = parseRequiredInteger(target, "Chat report ID", 1);
+      const status = parseChoice(
+        options.adminStatus,
+        "--status",
+        CHAT_REPORT_STATUSES,
+      );
+      const note = String(options.note || "").trim();
+      if (!note) {
+        throw cliValidationError(
+          "Record what was decided or done with --note <text>.",
+        );
+      }
+      if (note.length > 2000) {
+        throw cliValidationError("--note must be at most 2000 characters.");
+      }
+      return writeOperation(
+        "chat-reports.set",
+        "PUT",
+        `/cli/admin/chat-reports/${reportId}`,
+        { status, note },
+        { requiresRun: false, reportId },
+      );
+    }
+    // Child-safety holds, evidence export and suspension (owner only; the
+    // API admits only the owner's login). A hold keeps a protected copy of
+    // anything the held conversation or members delete or edit.
+    if (action === "hold") {
+      const note = requireChatSafetyNote(options.note);
+      const body = { note };
+      if (target) body.reportId = parseRequiredInteger(target, "Chat report ID", 1);
+      if (options.adminUser) {
+        body.userIds = parseIdList(options.adminUser, "--user");
+      }
+      if (options.adminChannel) {
+        body.channelId = parseRequiredInteger(options.adminChannel, "--channel", 1);
+      }
+      if (!body.reportId && !body.userIds && !body.channelId) {
+        throw cliValidationError(
+          "Usage: lumine admin chat-reports hold <report-id> | --user <id>[,<id>] [--channel <id>] | --channel <id> --note <why>.",
+        );
+      }
+      return writeOperation(
+        "chat-reports.hold",
+        "POST",
+        "/cli/admin/chat-reports/holds",
+        body,
+        { requiresRun: false },
+      );
+    }
+    if (action === "release") {
+      const holdId = parseRequiredInteger(
+        target || options.adminHold,
+        "Safety hold ID",
+        1,
+      );
+      return writeOperation(
+        "chat-reports.release",
+        "PUT",
+        `/cli/admin/chat-reports/holds/${holdId}/release`,
+        { note: requireChatSafetyNote(options.note) },
+        { requiresRun: false, holdId },
+      );
+    }
+    if (action === "list-holds" || action === "holds") {
+      return readOperation(
+        "chat-reports.list-holds",
+        withQuery("/cli/admin/chat-reports/holds", {
+          status: parseChoice(
+            options.adminStatus || "active",
+            "--status",
+            ["active", "released", "all"],
+          ),
+        }),
+        { requiresRun: false },
+      );
+    }
+    if (action === "export") {
+      const out = String(options.out || "").trim();
+      if (!out) {
+        throw cliValidationError(
+          "Pass a new or empty directory with --out <dir> for the evidence package.",
+        );
+      }
+      if (target && options.adminHold) {
+        throw cliValidationError("Export either one report ID or one --hold <id>, not both.");
+      }
+      const body = target
+        ? { reportId: parseRequiredInteger(target, "Chat report ID", 1) }
+        : options.adminHold
+          ? { holdId: parseRequiredInteger(options.adminHold, "--hold", 1) }
+          : null;
+      if (!body) {
+        throw cliValidationError(
+          "Usage: lumine admin chat-reports export <report-id> | --hold <hold-id> --out <dir>.",
+        );
+      }
+      // A POST because the export is audited server-side (who, when, the
+      // manifest hash); it changes no member data.
+      return writeOperation(
+        "chat-reports.export",
+        "POST",
+        "/cli/admin/chat-reports/export",
+        body,
+        { requiresRun: false, evidenceDir: out },
+      );
+    }
+    if (action === "suspend") {
+      return writeOperation(
+        "chat-reports.suspend",
+        "POST",
+        "/cli/admin/chat-reports/suspend",
+        {
+          userId: parseRequiredInteger(options.adminUser || target, "--user", 1),
+          note: requireChatSafetyNote(options.note),
+        },
+        { requiresRun: false },
+      );
+    }
+    throw cliValidationError(
+      "Usage: lumine admin chat-reports list [--status pending|open|reviewing|resolved|dismissed|all] [--cursor <id>] | show <id> | set <id> --status reviewing|resolved|dismissed|open --note <decision> | hold <report-id>|--user <id>|--channel <id> --note <why> | release <hold-id> --note <why> | list-holds [--status active|released|all] | export <report-id>|--hold <id> --out <dir> | suspend --user <id> --note <why>.",
+    );
+  }
+
   if (namespace === "reward-activity" || namespace === "reward-telemetry") {
     // Read-only claim telemetry for the daily run: no run lease, no mutation.
     const date = options.adminDate
@@ -4037,8 +4295,53 @@ function printRewardActivity(data) {
   );
 }
 
+function describeSafetyHold(hold) {
+  const covers = [
+    ...(hold.channelIds || []).map((id) => `channel ${id}`),
+    ...(hold.userIds || []).map((id) => `user ${id}`),
+  ].join(", ");
+  const placed = hold.placedAt
+    ? new Date(hold.placedAt * 1000).toISOString()
+    : "unknown";
+  return `Hold #${hold.id} ${hold.status} (${hold.source}, placed ${placed}${hold.placedByUserId ? ` by user ${hold.placedByUserId}` : " automatically"}): ${covers || "nothing"}; reports ${(hold.reportIds || []).map((id) => `#${id}`).join(", ") || "none"}; ${hold.preservedRecords || 0} preserved cop${hold.preservedRecords === 1 ? "y" : "ies"}. ${hold.reason || ""}`;
+}
+
+function printChatSafetyResult({ operation, data }) {
+  if (operation.name === "chat-reports.hold" || operation.name === "chat-reports.release") {
+    if (data.hold) console.log(describeSafetyHold(data.hold));
+    return true;
+  }
+  if (operation.name === "chat-reports.list-holds") {
+    const holds = data.holds || [];
+    console.log(`${holds.length} ${data.filter || ""} safety hold(s).`);
+    for (const hold of holds) console.log(`  ${describeSafetyHold(hold)}`);
+    return true;
+  }
+  if (operation.name === "chat-reports.export") {
+    console.log(
+      `Evidence package written to ${data.evidenceDirectory} (${(data.files || []).length} files, hashes verified).`,
+    );
+    console.log(`manifest.json SHA-256: ${data.manifestSha256}`);
+    for (const file of data.files || []) {
+      console.log(`  ${file.path}  ${file.bytes} bytes${file.sha256 ? `  ${file.sha256}` : ""}`);
+    }
+    console.log(
+      "Keep this folder private. Give it only to police or child-protection staff handling the case, and write the manifest hash in your records.",
+    );
+    return true;
+  }
+  if (operation.name === "chat-reports.suspend") {
+    console.log(
+      `${data.user?.username || "user"} (user ${data.user?.id}) ${data.alreadySuspended ? "was already" : "is now"} suspended (full ban: signed out, cannot use the site).${(data.holdIds || []).length ? ` Safety hold(s): #${data.holdIds.join(", #")}.` : " No safety hold covers this account yet; place one with chat-reports hold."}`,
+    );
+    return true;
+  }
+  return false;
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (printChatSafetyResult({ operation, data })) return;
   if (operation.name === "reward-activity.report") {
     printRewardActivity(data);
     return;

package/lib/commands.js

@@ -2578,6 +2578,9 @@ export function parseArgs(args) {
     adminBucketId: raw.bucketId ? String(raw.bucketId) : "",
     adminLabel: raw.label ? String(raw.label) : "",
     adminUserIds: raw.userIds ? String(raw.userIds) : "",
+    adminUser: raw.user ? String(raw.user) : "",
+    adminChannel: raw.channel ? String(raw.channel) : "",
+    adminHold: raw.hold ? String(raw.hold) : "",
     adminEmail: raw.email ? String(raw.email) : "",
     adminMode: raw.mode ? String(raw.mode) : "",
     adminType: raw.type ? String(raw.type) : "",
@@ -2984,6 +2987,14 @@ export function printHelp() {
   lumine admin sponsor integrity review <case-id> --decision clear|hold|flag|disqualify [--note <evidence>] [--json]
   lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] [--json]
   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)
+  lumine admin chat-reports set <report-id> --status reviewing|resolved|dismissed|open --note <what was decided> [--json]
+  lumine admin chat-reports hold <report-id> | --user <id>[,<id>] [--channel <id>] | --channel <id> --note <why> [--json]   (child-safety evidence hold)
+  lumine admin chat-reports release <hold-id> --note <why> [--json]
+  lumine admin chat-reports list-holds [--status active|released|all] [--json]
+  lumine admin chat-reports export <report-id> | --hold <hold-id> --out <new-dir> [--json]   (evidence package + SHA-256 manifest)
+  lumine admin chat-reports suspend --user <id> --note <why> [--json]   (full ban: signs them out)
   lumine admin reward-review show <review-id> [--dir <path>] [--json]
   lumine admin reward-review approve <review-id> [--config <rules.json>] [--reason <text>] [--json]   (approval publishes the approved version)
   lumine admin reward-review propose <review-id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--json]

package/lib/rewards.js

@@ -238,7 +238,7 @@ function printRewardsHelp() {
 
 rewards.json (project root) declares the economy the reviewer approves:
   { "userDailyXP", "userDailyCoins", "userDailyClaims"?,
-    "rules": [{ "id", "title", "xp", "coins", "verifier": "numeric-quiz" | "completion",
+    "rules": [{ "id", "title", "howTo"? (how to earn it, in the player's words), "xp", "coins", "verifier": "numeric-quiz" | "completion",
                 "maxAttempts"?, "retry"?: { "xpPercent", "coinsPercent", "paidAttempts"? }, "minSeconds"? (completion), "progression"?: "dated" | "until-earned" (quiz) }] }
 Questions and answer keys never go in project files; they belong in the sheet.`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.90",
+  "version": "0.2.91",
   "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.59.0
-Updated: 2026-09-26
-Generated: 2026-09-26T05:55:48.545Z
+Version: 1.60.0
+Updated: 2026-09-27
+Generated: 2026-09-27T07:17:40.033Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -36,7 +36,7 @@ Generated: 2026-09-26T05:55:48.545Z
 - 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, 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.
 - 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). Profiles are platform-owned; an app cannot invent a verifier or authorize its own reward.
+- 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.
@@ -608,9 +608,10 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Returns subject ids plus rootType/rootId metadata for picker UIs. Empty queries return an empty result set.
   - Example: const { subjects } = await Twinkle.subjects.search({ query: searchText, limit: 12 });
 - async getSubject(subjectId) | scopes: content:read
-  - Returns: { subject: { id, title, description, filePath, fileName, fileSize, thumbUrl, secretAnswer, secretAttachment, timeStamp, userId, username, profilePicUrl, rootType, rootId, rewardLevel } }
+  - Returns: { subject: { id, title, description, filePath, fileName, fileSize, thumbUrl, secretAnswer, secretAttachment, hasSecretAnswer, hasSecretAttachment, secretShown, timeStamp, userId, username, profilePicUrl, rootType, rootId, rewardLevel } }
   - Returns full detail for a single subject, including uploader info and attachments.
   - Any subject can be fetched (not limited to viewer's own).
+  - secretAnswer and secretAttachment follow the site's rule: they are filled only when the viewer posted the subject or has responded to it (secretShown true). Otherwise they are null and hasSecretAnswer / hasSecretAttachment say a secret exists.
 - async getSubjectComments(subjectId, { limit, cursor } = {}) | scopes: content:read
   - Returns: { comments: [{ id, content, filePath, fileName, fileSize, thumbUrl, timeStamp }], cursor? }
   - Returns only the current viewer's own comments on the given subject.
@@ -661,6 +662,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Lists completed existing AI Stories newest first by default; order:'oldest' is allowed only with difficulty, type, and topicKey for chronological book pages.
   - Use difficulty with type and topicKey to load one exact AI Story book without scanning the full corpus in the iframe.
   - Filter with hasImage or hasQuestions when building visual galleries or quiz apps.
+  - A story the signed-in viewer is still playing (an AI Story attempt they have not submitted) comes back without answerIndex on its questions; the site reveals that key only after the viewer submits.
   - Example: const { stories } = await Twinkle.aiStories.list({ difficulty: 1, type: 'science', topicKey: 'Astronomy', order: 'oldest', limit: 20 });
 - async chapters({ limit, cursor, groupBy, difficulty, type, topicKey, storyBy, isListening, userId, hasImage, hasQuestions } = {}) | scopes: content:read
   - Returns: Default (groupBy:'topicKey'): { chapters: [{ difficulty, type, topicKey, title, sampleTopic, storyCount, readingCount, listeningCount, imageCount, questionCount, latestStoryId, latestTimeStamp }], cursor?, pagination, filters }. groupBy:'type': { books: [{ difficulty, type, title, sampleTopic, chapterCount, storyCount, readingCount, listeningCount, imageCount, questionCount, latestStoryId, latestTimeStamp }], ... } — one row per (level, topic) book. groupBy:'author': { authors: [{ storyBy, title, bookCount, chapterCount, storyCount, minDifficulty, maxDifficulty, latestStoryId }], ... } — one row per generating model (the story's author); an index-only landing, so it omits media counts (use a scoped books/chapters call for those).
@@ -676,29 +678,41 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Searches completed existing AI Stories by topic/story text.
   - Use difficulty, type, and topicKey to search within one book of the AI Story corpus; order:'oldest' is rejected without all three filters.
   - Returned questions are normalized to an array even when stored as JSON text.
+  - A story the signed-in viewer is still playing (an AI Story attempt they have not submitted) comes back without answerIndex on its questions; the site reveals that key only after the viewer submits.
   - Example: const { stories } = await Twinkle.aiStories.search({ query: searchText, difficulty: 2, type: 'history', topicKey: 'Ancient Rome', order: 'oldest', limit: 12 });
 - async get(storyId) | scopes: content:read
   - Returns: { story: { id, contentType, contentId, topic, topicKey, type, story, explanation, difficulty, isListening, imagePath, imageUrl, audioPath, audioUrl, questions, questionsBy, hasImage, hasQuestions, userId, username, profilePicUrl, timeStamp } }
   - Fetch one completed existing AI Story by id, including story text for passage typing, media URLs, and normalized questions when available.
   - Fetches one completed existing AI Story by id.
+  - A story the signed-in viewer is still playing (an AI Story attempt they have not submitted) comes back without answerIndex on its questions; the site reveals that key only after the viewer submits.
   - This namespace is read-only and does not generate new AI Stories.
   - Example: const { story } = await Twinkle.aiStories.get(storyId);
 
 ### Twinkle.grammarbles
 - async listQuestions({ level, limit, cursor } = {}) | scopes: content:read
-  - Returns: { questions: [{ id, level, rating, question, choices, answerIndex, correctChoice, correctChoiceKey, isChecked, explanation }], cursor?, pagination: { level, limit, hasMore, nextCursor } }
-  - Read public Grammarbles questions and answers by level with rating/id cursor pagination.
-  - Questions are public Grammarbles training data and include the canonical answer.
+  - Returns: { questions: [{ id, level, rating, question, choices, isChecked }], cursor?, pagination: { level, limit, hasMore, nextCursor } }
+  - Read Grammarbles questions and choices by level with rating/id cursor pagination; answers stay on the server.
+  - Questions do not include the answer, answerIndex or explanation: Grammarbles is a rewarded game, so its key stays on the server. Check a pick with Twinkle.grammarbles.checkAnswer.
+  - Each question's choices come in a fixed order; pass the index of the picked choice in that order to checkAnswer.
   - level is clamped from 1 through 5.
   - Pagination is stable by rating then id. Pass cursor from the previous response to load more questions in the same level.
   - This method does not expose daily attempt state, XP, coins, or daily-task progression.
   - Example: const page = await Twinkle.grammarbles.listQuestions({ level: 3, limit: 100 }); const question = page.questions[Math.floor(Math.random() * page.questions.length)];
+- async checkAnswer({ questionId, choiceIndex }) | scopes: content:read
+  - Returns: { questionId, choiceIndex, isCorrect, explanation }
+  - Check one Grammarbles pick on the server: right or wrong, plus the review explanation on a right pick.
+  - choiceIndex is 0-3 in the order listQuestions returned the choices.
+  - The right position is never returned. Let the learner try again until the pick is right, as Grammarbles itself does.
+  - explanation is null unless the pick is right and the question has a reviewed explanation.
+  - Each viewer has a daily allowance of answer checks (500 per UTC day); past it the call fails with code grammarbles_check_limit.
+  - Checking pays nothing and does not touch daily Grammarbles attempts, XP, coins, or daily tasks.
+  - Example: const { isCorrect, explanation } = await Twinkle.grammarbles.checkAnswer({ questionId: question.id, choiceIndex: pickedIndex }); if (!isCorrect) showTryAgain(); else showCorrect(explanation);
 - async getMyQuestionHistory({ level, limit, cursor } = {}) | scopes: content:read
   - Returns: { attempts: [{ id, questionId, level, grade, gradeRank, isCorrect, attemptNumber, timeStamp }], cursor?, pagination: { level, limit, hasMore, nextCursor } }
   - Read the signed-in viewer's real Grammarbles attempt rows for trainer filtering.
   - Returns real Grammarbles attempt outcome rows for the signed-in viewer, newest first.
   - History rows intentionally omit choice indexes because real Grammarbles choices are shuffled per run and the per-run shuffle order is not persisted.
-  - Use Twinkle.grammarbles.listQuestions for canonical question text, choices, and answers.
+  - Use Twinkle.grammarbles.listQuestions for question text and choices, and Twinkle.grammarbles.checkAnswer to check a pick.
   - Use app-private history in Twinkle.privateDb for trainer-only results, and combine it with this method only when the viewer chooses to include real Grammarbles history.
   - This method is read-only and does not submit, cancel, or mutate daily Grammarbles attempts.
   - Example: const history = await Twinkle.grammarbles.getMyQuestionHistory({ level: selectedLevel, limit: 500 }); const answeredIds = new Set(history.attempts.map((attempt) => attempt.questionId));
@@ -802,19 +816,20 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - limit is 1-50 (default 10). kind filters to helper or workshop builds.
   - Example: const { builds } = await Twinkle.minecraft.getZeroBuilds({ limit: 10, kind: 'workshop' });
 - async getPeople() | scopes: content:read
-  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', op, online, isZero, twinkle: { userId, username } | null, ...owner: groups, banned, protected, firstSeenAt, lastSeenAt | ...others: seen: 'online'|'today'|'week'|'month'|'older'|null }], roles }
+  - Returns: { canManage, people: [{ uuid, name, role: 'visitor'|'member'|'builder'|'moderator', op, online, isZero, twinkle: { userId, username } | null, ...owner: groups, banned, protected, firstSeenAt, lastSeenAt, endorsements: [{ voucherName, voucherUuid, endorsedAt }] | ...others: seen: 'online'|'today'|'week'|'month'|'older'|null }], roles }
   - Everyone who has joined the server with their in-game rank, for a player directory; the server owner also gets the full records for role management.
   - Every viewer gets the list. Only the server owner, in an app they own, gets canManage: true with full records (groups, bans, exact first/last seen); everyone else gets canManage: false and the public view: banned players left out, and seen is a rough bucket instead of exact times. Show role controls only when canManage is true.
   - Roles: visitor (play and chat), member (/tpa, /home, /back, may ask Zero to build), builder (member + /fly and creative/survival), moderator (builder + teleport others, CoreProtect rollback, /kick). op: true players are server operators and have every power regardless of role.
   - protected: true players (the owner and Zero's account) can't be changed from the app. Sorted online first, then most recently seen.
   - Not cached; call on screen open or after a change, not on a timer.
   - twinkle is the Twinkle account linked to that player with /link, or null.
+  - endorsements (owner view only) lists who backed this player's Builder application: a moderator or anyone above typed /vouch for a player already on Twinkle. voucherUuid is the voucher's Minecraft uuid (null when endorsed from the app or console); endorsedAt is an ISO time. Empty when there are none, or when the server's vouch list could not be read.
   - Example: const { canManage, people } = await Twinkle.minecraft.getPeople(); renderDirectory(people, { editable: canManage });
 - async setPlayerRole({ uuid, role }) | scopes: content:write
   - Returns: { player: { uuid, name, role, op } }
   - Change a player's in-game role; it applies immediately, even while they are online.
   - Server owner only, in an app they own; others get 403 with code minecraft_roles_forbidden.
-  - role is visitor, member, builder or moderator. 400 codes: minecraft_bad_uuid, minecraft_bad_role, minecraft_protected_player, minecraft_unknown_player. 503 minecraft_unavailable while the server restarts.
+  - role is visitor, member, builder, moderator, or a Partner rank above moderator: associate, senior_associate, partner, senior_partner (each keeps every moderator power). A promotion also sends the player's linked Twinkle account a DM, and the player gets a title and perks list in game. 400 codes: minecraft_bad_uuid, minecraft_bad_role, minecraft_protected_player, minecraft_unknown_player. 503 minecraft_unavailable while the server restarts.
   - Every change is logged on the server and emailed to the owner; the player is told in game.
   - Example: await Twinkle.minecraft.setPlayerRole({ uuid: person.uuid, role: 'builder' });
 - async getChat({ since } = {}) | scopes: content:read
@@ -938,6 +953,23 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Delete a snap from the Gallery.
   - Who may: the player who took it (by a linked Minecraft account), moderators, and the server owner. Others get 403 minecraft_snap_forbidden.
   - Example: await Twinkle.minecraft.deleteSnap({ id });
+- async getRecruitTours() | scopes: content:read
+  - Returns: { enabled, title, landmarks: [{ id, name, world, x, z, radius }], requirements: { playHours, days }, tours: [{ uuid, name, introducerUuid, introducerName, startedAt, completedAt, visited: [landmarkId], playSeconds, days }] }
+  - Recruit tours: each player someone brought to the server, who brought them, and their progress (landmarks visited, hours and days played). A completed tour is one recruiter point for the introducer.
+  - Everyone can read it; one shared copy refreshes every 15 seconds.
+  - The landmark list and requirements come from the server's config, so show them from here rather than hard-coding them.
+  - Example: const { landmarks, tours } = await Twinkle.minecraft.getRecruitTours();
+- async startRecruitTour({ uuid, introducerUuid }) | scopes: content:write
+  - Returns: { uuid, introducerUuid }
+  - Server owner only: record that introducerUuid brought player uuid to the server and start that player's landmark tour (a quest list in game).
+  - 403 minecraft_roles_forbidden for anyone but the server owner.
+  - 400 minecraft_already_credited when someone else was already credited; minecraft_self_introduced for the same player; minecraft_unknown_player when either never joined.
+  - Example: await Twinkle.minecraft.startRecruitTour({ uuid: recruit.uuid, introducerUuid: friend.uuid });
+- async cancelRecruitTour({ uuid }) | scopes: content:write
+  - Returns: { removed }
+  - Server owner only: remove a player's recruit tour (a mistaken credit).
+  - 403 minecraft_roles_forbidden for anyone but the server owner.
+  - Example: await Twinkle.minecraft.cancelRecruitTour({ uuid });
 - async getArrivalPoints() | scopes: content:read
   - Returns: { accounts: [{ uuid, name, online, world, worldLabel, points: [{ world, label, x, y, z, savedAt }] }] }
   - The viewer's private arrival points: where the Twinkle Gate portals drop their linked Minecraft account in each world.
@@ -1303,12 +1335,13 @@ world.updatePresence({ x, y, z, facing });
 
 ### Twinkle.rewards
 - await Twinkle.rewards.getStatus() | scopes: rewards:claim
-  - Returns: { mode: "live", dayKey, userDailyClaims, claimsToday, budgets: { userDailyXP, userDailyCoins }, rules: [{ id, title, xp, coins, verifier: "numeric-quiz" | "completion", minSeconds?, progression?, retryReward: { xp, coins }, maxAttempts, available, setKey, questionCount }], challenges: [{ challengeId, ruleId, attempts, attemptsRemaining, state: "open" | "finished" | "earned", setKey, questions: [{ prompt, hint?, guide? }] }], history: [{ ruleId, xp, coins, attempt, createdAt }], balances: { xp, coins } } | { mode: "preview", dayKey?, rules, challenges: [], history: [], balances?, problems?: string[], message }
+  - Returns: { mode: "live", dayKey, userDailyClaims, claimsToday, budgets: { userDailyXP, userDailyCoins }, rules: [{ id, title, howTo?, xp, coins, verifier: "numeric-quiz" | "completion", minSeconds?, progression?, retryReward: { xp, coins }, maxAttempts, available, setKey, questionCount }], challenges: [{ challengeId, ruleId, attempts, attemptsRemaining, state: "open" | "finished" | "earned", setKey, questions: [{ prompt, hint?, guide? }] }], history: [{ ruleId, xp, coins, attempt, createdAt }], balances: { xp, coins } } | { mode: "preview", dayKey?, rules, challenges: [], history: [], balances?, problems?: string[], message }
   - Read canonical earning rules (without answer keys), today’s started challenges, today’s receipts and balances. Drafts return preview mode: for the app's owner the rules come from the draft's own rewards.json and question sheet (problems lists what is still wrong with them); anyone else sees no rules. Unapproved or revoked published releases return an error.
   - rules[].available is false on a site day (UTC) the reviewer scheduled no questions for; show the rule as not available instead of starting it. xp/coins are the first-try amounts; retryReward is what a correct answer pays after a wrong one (equal to xp/coins unless the reviewer set a retry share). maxAttempts null means unlimited wrong answers until the site's daily reset (UTC midnight, 9:00 AM in Korea). retry.paidAttempts, when set, is the last attempt number a correct answer is still paid on: a later correct answer is recorded as solved (receipt xp 0, coins 0) and pays nothing — tell the learner before they pass it.
   - challenges lists challenges this viewer already started today with their questions, so an app can resume after a reload without calling start. A question's guide (reviewer-approved JSON teaching content: explanation, interactive-model configuration) is present only once the viewer has answered at least once, right or wrong; render it as the after-attempt lesson. claimsToday against userDailyClaims (null = uncapped) tells whether another bounty can still pay today.
   - Under progression 'until-earned' the same set stays up day after day until somebody earns it; setKey names the set currently up. Completion rules are always available and have questionCount 0.
   - Rules may set maxLifetimeClaims, a per-learner limit for that rule across days and releases. rules[].lifetime contains the server-confirmed limit and remaining claims. App storage never enforces this limit.
+  - howTo is the rule's optional plain-words steps from rewards.json (up to 300 characters, e.g. "Save a new design of at least 64 blocks in Designs"). The Earn page shows it under the title; show it in the app's own rewards list too so players always know exactly what earns each reward.
 - await Twinkle.rewards.getReceipt({ challengeId }) | scopes: rewards:claim
   - Returns: { mode: "live", status: "awarded" | "pending" | "expired" | "not_found", receipt: { id, challengeId, ruleId, reviewId, artifactVersionId, dayKey, xp, coins, attempt, createdAt } | null, balances: { xp, coins } } | { mode: "preview", status: "not_found", receipt: null, message }
   - Read an existing receipt for this app and signed-in viewer by server-issued challengeId, including previous UTC days and previous approved versions. Requires the current approved published release and runtime grant; a stale frame must reload first. Never awards, retries a claim, returns answer keys, or restores removed rewards permission.
@@ -1319,7 +1352,7 @@ world.updatePresence({ x, y, z, facing });
   - Errors: build_reward_not_scheduled when the rule has no questions for today; build_reward_daily_claims_reached when the viewer already earned today’s cap. attemptsRemaining is null for unlimited rules.
   - For a completion rule call start when the activity begins (the moment the stage starts); the challenge's age is what the claim is measured against. In preview mode start also works for the owner (a stateless simulation).
   - For completionProof: classic-tower-v1, start also returns completion { profile, token, maxFrames, completed, failed }. A new start resets only the simulated climb to its canonical spawn; it cannot reset daily or lifetime rewards. Record inputs from the first physics frame. The completion token is bound to the viewer, challenge, rule and published release.
-  - For breadface-v1, breadface-v2 and breadface-v3, pass the zero-based canonical levelIndex. Record [dt, inputBits] from the first physics frame; start returns its server token and maxFrames. For study-record-v1, start returns completion { profile, usesAiEnergy: true }; there is no client-authored proof token. For groove-lab-song-v1 and groove-lab-heard-v1, start returns completion { profile }; there is no progress step.
+  - For breadface-v1, breadface-v2 and breadface-v3, pass the zero-based canonical levelIndex. Record [dt, inputBits] from the first physics frame; start returns its server token and maxFrames. For study-record-v1, start returns completion { profile, usesAiEnergy: true }; there is no client-authored proof token. For groove-lab-song-v1, groove-lab-heard-v1, vigil-guest-coplay-v1 and minecraft-first-link-v1, start returns completion { profile }; there is no progress step.
 - await Twinkle.rewards.progress({ challengeId, completionToken?, frames?, record?, requestId? }) | scopes: rewards:claim
   - Returns: { mode: "live" | "preview", completion: { profile, token?, completed, failed?, decision?, message?, maxFrames? }, aiUsagePolicy? }
   - Verify a bounded batch of inputs for an approved server-simulated climb.
@@ -1335,7 +1368,7 @@ world.updatePresence({ x, y, z, facing });
   - A wrong answer within two seconds of the previous one is refused with build_reward_throttled (HTTP 429) and does not count; wait for the person to try again rather than retry-looping.
   - Completion rules take no answers: claim({ challengeId }) when the activity is finished. build_reward_too_fast (HTTP 409) means fewer than minSeconds passed since start; show nothing and let play continue. In preview mode the receipt carries preview: true and nothing is paid.
   - A completionProof rule also requires the signed completionToken from a successful rewards.progress response. The server simulates the registered game physics and must reach the goal. A timer, forged position, client win flag, altered inventory or token from another viewer, challenge or release cannot authorize payment. maxLifetimeClaims is enforced from receipts in the same award transaction. build_reward_lifetime_claims_reached means all rewards for this rule have been collected; do not retry it.
-  - For study-record-v1, the server verifies the settled private review row and its viewer, app, exact release, challenge and day binding. It never trusts the client’s decision, requested award amount or AI answer. Each successful daily study record is claimable once; display only canonical receipt/balances. For groove-lab-song-v1, pass completionToken as the published song's sharedDb entry id; for groove-lab-heard-v1, pass none. The server reads the app's own groove-lab-songs, groove-lab-song-parts and groove-lab-listens rows and refuses with build_reward_completion_proof_required and a plain reason when the song or listeners do not qualify.
+  - For study-record-v1, the server verifies the settled private review row and its viewer, app, exact release, challenge and day binding. It never trusts the client’s decision, requested award amount or AI answer. Each successful daily study record is claimable once; display only canonical receipt/balances. For groove-lab-song-v1, pass completionToken as the published song's sharedDb entry id; for groove-lab-heard-v1, pass none; for vigil-guest-coplay-v1, pass the guest's world guestId (from world events) or the co-play record id; for minecraft-first-link-v1, pass nothing or the Minecraft UUID to use. The server reads the app's own groove-lab-songs, groove-lab-song-parts and groove-lab-listens rows and refuses with build_reward_completion_proof_required and a plain reason when the song or listeners do not qualify.
 - await Twinkle.rewards.getLeaderboard({ metric?: "xp" | "coins", period?: "day" | "week" | "all", limit? }) | scopes: rewards:claim
   - Returns: { mode: "live", metric, period, limit, dayKey, from, available: { xp, coins }, entries: [{ rank, userId, username, profilePicUrl, xp, coins, claims, lastAt }], me: { rank, xp, coins, claims } | null } | { mode: "preview", metric, period, available, entries: [], me: null, message }
   - Standings of who earned the most XP or Coins in THIS app, computed by Twinkle from its own receipts (never from anything the app submits). period 'day' is today (site day, UTC), 'week' the last 7 site days, 'all' (default) every day since approval. limit defaults to 20, max 100.

package/sdk/LUMINE_ADMIN.md

@@ -1299,6 +1299,109 @@ ids (`reward-review show <id>` lists its events). An `accept` without a
 the comparison; mention it, it is not a fault. Refusals are the concurrency
 guards working; report them, and escalate only a repeated pattern on one app.
 
+### Members' chat reports (any time; also a full-daily-review duty, added 2026-09-27)
+
+Any member can report another member's chat message from the message's "…"
+menu (reasons: bullying or harassment, sexual content, asking for personal
+info, spam or scam, something else; optional note). The API snapshots the
+message and a few messages around it, so a later edit or delete does not
+erase the evidence, and Zero DMs Mikey on the first report of each message.
+The reporter only sees "Thanks. Our team will look at this."; the reported
+member is never told. The full-run intake and report carry `chatReports`
+(pending = `open` + `reviewing`), like `rewardReviews`. These commands need no
+daily run:
+
+```bash
+lumine admin chat-reports list --json                    # pending (default)
+lumine admin chat-reports list --status all --cursor 40 --json
+lumine admin chat-reports show 12 --json                 # snapshot + context
+lumine admin chat-reports set 12 --status resolved --note "What was decided or done" --json
+```
+
+Read every pending report's snapshot and context in each full run. A report
+about a child's safety or wellbeing (sexual content, requests for personal
+information or photos, threats, targeted bullying) belongs at the top of the
+escalation list for Mikey with the report id, both usernames and a one-line
+summary; set it to `reviewing` with a note saying so. Spam, obvious
+misclicks and ordinary disagreements can be `dismissed` with a note.
+Recording a status only annotates the report: never message, ban or
+otherwise act against either member without Mikey's explicit go-ahead.
+
+### Child-safety holds, evidence export and incident runbook (Mikey only, added 2026-09-27)
+
+> Not legal advice. Have a Korean lawyer review this procedure.
+
+Mikey, 2026-09-27: "if someone did something wrong - especially if for
+example a teacher was being inappropriate to a kid - shouldnt we be able to
+help police investigate?"
+
+**Automatic holds.** A report for sexual content or asking for personal
+info, or any report between a minor and an adult where both ages are known
+(an admin-approved birthdate, otherwise the birthdate on the profile), places
+a safety hold on the whole conversation and on both accounts. A second such
+report in the same conversation joins the existing hold. Zero, Ciel and the
+site-wide General channel are never held (a General report holds the two
+accounts). Zero's alert DM to Mikey says when a hold was placed, and
+`chat-reports show <id>` lists `safetyHoldIds`.
+
+**What a hold does**, silently, until it is released: a member's delete or
+edit still works for everyone, but the message row stays and the text before
+an edit (or the row at deletion) is copied to the hold; topic edits, removed
+archived profile pictures and removed previous usernames are copied too.
+Permanent deletion of a held message or of a held member's post or comment is
+refused with a neutral "can't be permanently deleted right now". Twinkle has
+no account deletion, so accounts are never erased. Nothing about a hold is
+shown to members.
+
+These commands are for Mikey. A daily run may read `list-holds` and report
+it, but never places, releases or exports a hold or suspends anyone without
+Mikey's explicit instruction for that case:
+
+```bash
+lumine admin chat-reports hold 12 --note "Why this case is held" --json
+lumine admin chat-reports hold --user 7,9 --channel 40 --note "Parent phoned" --json
+lumine admin chat-reports list-holds [--status active|released|all] --json
+lumine admin chat-reports suspend --user 7 --note "Adult under investigation" --json
+lumine admin chat-reports export 12 --out ~/twinkle-case-12 --json   # or --hold <id>
+lumine admin chat-reports release 3 --note "Police closed the case" --json
+```
+
+Every hold, release, export and suspension is recorded with who and when
+(`chat_safety_actions`), and released holds keep their copies.
+
+**Incident runbook** (for example, an adult or a teacher being inappropriate
+to a child):
+
+1. **Suspend the adult's access**: `chat-reports suspend --user <id> --note
+   <why>`. This is the website's full ban: it signs them out and blocks the
+   site. Lift it later from the website's Management ban editor.
+2. **Place or confirm the hold**: `chat-reports hold <report-id> --note <why>`
+   (or `--user`/`--channel` when there is no report yet, for example after a
+   parent's call), then `list-holds` to check that it covers the conversation
+   and both accounts.
+3. **Export the evidence**: `chat-reports export <report-id> --out <new
+   folder>`. The folder holds the whole conversation with UTC and KST times,
+   deletions and held edits; both accounts (username, id, join date, verified
+   email, birthdates, username history, linked Minecraft players, and the IP
+   addresses the site stores for logouts, searches and page visits); the
+   report(s); the actions taken; and `manifest.json` with each file's
+   SHA-256. Write down the printed manifest hash, keep the folder private,
+   and never edit it. Attachments are listed by storage key, not included.
+4. **Contact the police**: 112 for an emergency or ongoing danger, or the
+   cyber crime report system at https://ecrm.police.go.kr. Give them the
+   export when they ask for it.
+5. **Contact child protection**: report suspected child abuse to 112 (the
+   national child-abuse report line), which connects to the local
+   아동보호전문기관 (child protection agency).
+6. **Teachers and academy staff are mandatory reporters**: under Korea's Act
+   on Special Cases Concerning the Punishment of Child Abuse Crimes, teachers
+   and academy (hagwon) staff must report suspected child abuse. If the adult
+   is a teacher, their employer may also need to be told; ask the lawyer.
+7. **Do not** confront or warn the adult, delete anything, or share the
+   evidence with anyone but the police or child-protection staff.
+8. **Release the hold** only after the case is closed: `chat-reports release
+   <hold-id> --note <why>`.
+
 ## Private carry-over todos
 
 ```bash