@stage5/lumine 0.3.77 → 0.3.79

package/lib/admin-daily.js

@@ -10,6 +10,7 @@ import { createDailyReviewState, dailyRunProgress } from "./admin-duties.js";
 import { summarizeOwnerViewport, formatOwnerViewportReport } from "./admin-owner-viewport.js";
 import { createDailyCollection } from "./admin-daily-collection.js";
 import { collectDiagnosticPages, diagnosticCollectionSummary } from "./admin-diagnostic-collection.js";
+import { JEV_THUMBNAIL_MAX_TARGETS } from "./admin-jev-images.js";
 export { dailyRunProgress };
 
 // Multi-step conveniences for the full daily management run. Each one runs
@@ -189,6 +190,45 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
     Object.assign(steps.at(-1), { ok: false, error });
   };
   const evidenceNames = /^(ai-costs|media-costs|reward-activity|reward-diagnostics|jev-review|jev-images|owner-wake|bot-output)/;
+  // A run started from a shell that then exits (`gather ... &`) used to be
+  // hung up and die before gather.json existed (11-02). Keep collecting like
+  // nohup, and keep gather.json current after every step, marked incomplete
+  // until the final summary replaces it, so an interrupted collection always
+  // leaves a readable receipt and `--resume` is only needed to finish it.
+  const ignoreHangup = () => {};
+  process.on("SIGHUP", ignoreHangup);
+  const writeProgress = () => {
+    try {
+      fs.writeFileSync(
+        path.join(dir, "gather.json"),
+        JSON.stringify(
+          {
+            inProgress: true,
+            note: "Collection is still running or was interrupted. Rerun the same gather with --resume to finish it; this file is replaced when it completes.",
+            updatedAt: new Date().toISOString(),
+            dir,
+            yesterdayUtc: yesterday,
+            costDateUtc: yesterday,
+            collection: { id: collection.collectionId, startedAt: collection.startedAt, phase: collection.phase },
+            steps,
+            failed: steps.filter((s) => !s.ok && !s.deferred).map((s) => s.name),
+            deferred: steps.filter((s) => s.deferred).map((s) => ({ name: s.name, reason: s.reason })),
+          },
+          null,
+          2,
+        ),
+        { mode: 0o600 },
+      );
+    } catch {
+      // Progress is best effort; the final summary below is authoritative.
+    }
+  };
+  try {
+    return await gatherSteps();
+  } finally {
+    process.removeListener("SIGHUP", ignoreHangup);
+  }
+  async function gatherSteps() {
   const step = (name, args, file) => {
     const res = collection.collect(name, args, file, evidenceNames.test(name) ? "evidence" : "priority", run);
     steps.push({
@@ -202,6 +242,7 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
       reused: Boolean(res.reused),
       ...(res.deferred ? { deferred: true, reason: res.reason } : res.ok ? {} : { error: res.json?.error || res.stderr }),
     });
+    writeProgress();
     return res;
   };
   step("energy-budget", ["energy-budget"], "energy-budget.json");
@@ -410,6 +451,8 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
   if (botOk) renderBotOutput({ chatMessages, comments }, path.join(dir, "bot-chats.txt"));
 
   const summary = {
+    // The collection finished (failed steps are listed separately).
+    inProgress: false,
     collectedAt: new Date().toISOString(),
     durationMs: Math.round(performance.now() - startedAt),
     dir,
@@ -459,10 +502,30 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
     status: summary.failed.length ? "partial_failure" : summary.deferred.length ? "deferred" : "success",
     data: summary,
   };
+  }
 }
 
 // Recent, provably never-Featured Subjects with the context the editorial
 // ranking needs (comment count, operator view state), newest first.
+export function featuredThumbnailChecks(eligible, run = runAdmin) {
+  const ids = eligible.slice(0, JEV_THUMBNAIL_MAX_TARGETS).map((c) => `subject:${c.id}`);
+  if (!ids.length) return { summary: { status: "none" } };
+  const res = run(["jev-images", "thumbnails", "--targets", ids.join(",")], { timeoutMs: 200000 });
+  const data = res.ok ? res.json?.data : null;
+  if (!data || !Array.isArray(data.items)) {
+    for (const c of eligible) c.thumbnailCheck = { status: "unavailable", reason: "request_failed" };
+    return { summary: { status: "unavailable", reason: "request_failed", advisory: true } };
+  }
+  const byTarget = new Map(data.items.map((item) => [item.target, item]));
+  for (const c of eligible) {
+    const item = byTarget.get(`subject:${c.id}`);
+    c.thumbnailCheck = item
+      ? { status: item.status, ...(item.kind ? { kind: item.kind } : {}), ...(item.status === "ok" ? { verdict: item.verdict, notes: item.notes || [], cached: Boolean(item.cached) } : { reason: item.reason }) }
+      : { status: "unavailable", reason: "not_checked" };
+  }
+  return { summary: { status: data.status, flagged: data.flagged || [], advisory: true, notice: data.notice } };
+}
+
 export async function featuredCandidates(options) {
   const days = Math.max(1, Math.min(30, Number(options.adminDays || 7)));
   const after = options.adminAfter || bangkokCutoff(days);
@@ -528,6 +591,10 @@ export async function featuredCandidates(options) {
       operatorViewed: Boolean(s.operatorViewed?.viewed),
     });
   }
+  // Advisory JEV thumbnail notes (never a ranking or eligibility input). A
+  // failed or switched-off check leaves the candidate list exactly as before.
+  const eligible = candidates.filter((c) => c.neverFeatured === true);
+  const thumbnailChecks = featuredThumbnailChecks(eligible);
   return {
     ok: true,
     status: "success",
@@ -535,7 +602,8 @@ export async function featuredCandidates(options) {
       postedAfter: after,
       coverage: history.json.data.coverage || null,
       boardCount: onBoard.size,
-      eligible: candidates.filter((c) => c.neverFeatured === true),
+      eligible,
+      thumbnailChecks: thumbnailChecks.summary,
       excluded: candidates
         .filter((c) => c.neverFeatured !== true)
         .map((c) => ({ id: c.id, title: c.title, neverFeatured: c.neverFeatured })),

package/lib/admin-jev-images.js

@@ -6,11 +6,15 @@
 //                                             takes effect within 30 s, no deploy
 //   decide --area <area> --key <subject> --decision <decision>   record a
 //                                             reviewer's final decision
+//   thumbnails --targets subject:<id>,build:<id>,... | --featured [--saved-only]
+//                                             advisory thumbnail notes for
+//                                             Featured review (area thumbnail)
 export const JEV_IMAGES_AREAS = ["arena_paper", "arena_picture", "study_record", "thumbnail", "sdk_decide"];
 export const JEV_IMAGES_USAGE =
   "Usage: lumine admin jev-images report [--days 1..30] | switch --area <" +
   ["all", ...JEV_IMAGES_AREAS].join("|") +
-  "> --mode on|off [--daily-cap <0-5000>] | decide --area <area> --key <subject key, e.g. arenaItem:10176> --decision <decision> [--json]";
+  "> --mode on|off [--daily-cap <0-5000>] [--build <id>, sdk_decide only, no --daily-cap] | decide --area <area> --key <subject key, e.g. arenaItem:10176> --decision <decision> | thumbnails --targets <subject:<id>,build:<id>,...> | --featured [--saved-only] [--json]";
+export const JEV_THUMBNAIL_MAX_TARGETS = 40;
 
 function invalid(message) {
   const error = new Error(message);
@@ -44,6 +48,16 @@ export function buildJevImagesOperation({ action, options = {} }) {
       }
       body.dailyCap = cap;
     }
+    // One app's switch for sdk_decide (Twinkle.ai.decide with images). An app
+    // has no daily cap of its own; bursts are limited by the server.
+    if (options.adminBuild !== "" && options.adminBuild != null) {
+      const buildId = Number(options.adminBuild);
+      if (area !== "sdk_decide" || !Number.isSafeInteger(buildId) || buildId <= 0) {
+        throw invalid("--build is set only with --area sdk_decide and a build id.");
+      }
+      if (body.dailyCap !== undefined) throw invalid("--build sets one app's switch only (--mode on|off); an app has no daily cap of its own.");
+      body.buildId = buildId;
+    }
     return {
       name: "jev-images.switch",
       method: "POST",
@@ -71,18 +85,57 @@ export function buildJevImagesOperation({ action, options = {} }) {
       requiresRun: false,
     };
   }
+  if (action === "thumbnails") {
+    const featured = options.adminFeatured === true;
+    const raw = String(options.adminTargets || "").trim();
+    if (featured === Boolean(raw)) throw invalid("Use --targets subject:<id>,build:<id>,... or --featured (the current board), not both.");
+    const body = featured ? { featured: true } : { targets: parseThumbnailTargets(raw) };
+    // --saved-only: earlier answers only, no provider call.
+    if (options.adminSavedOnly === true) body.run = false;
+    return {
+      name: "jev-images.thumbnails",
+      method: "POST",
+      path: "/cli/admin/jev-images/thumbnails",
+      body,
+      mutates: false,
+      requiresRun: false,
+      timeoutMs: 180000,
+    };
+  }
   throw invalid(JEV_IMAGES_USAGE);
 }
 
+export function parseThumbnailTargets(raw) {
+  const targets = [...new Set(String(raw).split(",").map((value) => value.trim()).filter(Boolean))];
+  if (!targets.length || targets.length > JEV_THUMBNAIL_MAX_TARGETS || targets.some((value) => !/^(subject|build):[1-9][0-9]{0,14}$/.test(value))) {
+    throw invalid(`--targets is 1-${JEV_THUMBNAIL_MAX_TARGETS} of subject:<id> or build:<id>, comma-separated.`);
+  }
+  return targets;
+}
+
+export function thumbnailLine(item) {
+  if (!item) return "no thumbnail check";
+  if (item.status !== "ok") return `no thumbnail check (${item.reason || "unavailable"})`;
+  return `${item.verdict === "flag" ? "LOOK AT THE THUMBNAIL" : "thumbnail looks fine"}${item.cached ? " (saved)" : ""}${item.notes?.length ? ` · ${item.notes.join("; ")}` : ""}`;
+}
+
 const usd = (value) => `$${Number(value || 0).toFixed(4)}`;
 
 export function formatJevImagesResult({ operation, data = {} }) {
   if (operation.name === "jev-images.switch") {
-    return [`JEV images ${data.area}: ${data.mode}${data.dailyCap !== undefined ? `, daily cap ${data.dailyCap}` : ""} (all servers within ${data.effectiveWithinSeconds ?? 30} s).`];
+    return [`JEV images ${data.area}${data.buildId ? ` for build ${data.buildId}` : ""}: ${data.mode}${data.dailyCap !== undefined ? `, daily cap ${data.dailyCap}` : ""} (all servers within ${data.effectiveWithinSeconds ?? 30} s).`];
   }
   if (operation.name === "jev-images.decide") {
     return [`Recorded ${data.decision} for ${data.subjectKey} (${data.area}) on ${data.updated ?? 0} advisory row(s).`];
   }
+  if (operation.name === "jev-images.thumbnails") {
+    const lines = [`Thumbnail notes (advisory, JEV images): ${data.status || "unavailable"}${data.featuredBoard ? " · current Featured board" : ""} · ${(data.flagged || []).length} to look at`];
+    for (const item of data.items || []) {
+      lines.push(`  ${item.target}${item.kind ? ` (${item.kind})` : ""} ${JSON.stringify(item.title || "")}: ${thumbnailLine(item)}`);
+    }
+    if (data.notice) lines.push(`  ${data.notice}`);
+    return lines;
+  }
   const lines = [
     `JEV images (${data.model || "?"}, advisory only) · last ${data.window?.days ?? "?"} day(s) · coverage ${data.coverage?.status || "unknown"} · ${data.totals?.checks ?? 0} checks · ${usd(data.totals?.costUsd)}`,
   ];

package/lib/admin-member-trace.js

@@ -0,0 +1,247 @@
+// `lumine admin member-trace ...`: the owner trace switched on for specific
+// member accounts, so a bug one member reports (and Mikey cannot reproduce)
+// can be read the way his own are. The server keeps 30 days.
+//
+//   lumine admin member-trace list
+//   lumine admin member-trace on <username> --reason "<why>"
+//   lumine admin member-trace off <username>
+//   lumine admin member-trace <username> [--since 2h] [--source all|client|server] [...]
+//     (`member-trace read <username>` is the same, for a member named list/on/off/read)
+
+import { buildOwnerTraceOperation, formatOwnerTrace } from "./admin-owner-trace.js";
+
+export const MEMBER_TRACE_USAGE =
+  "Usage: lumine admin member-trace list | on <username> --reason <why> | off <username> | [read] <username> [--since 2h|30m|3d|<iso>|<unix>] [--until <unix-second>] [--cursor <time:id>] [--source all|client|server] [--type reload,route,chat-select,error,api,...] [--path <substring>] [--limit 300] [--json].";
+
+const ACTIONS = new Set(["list", "on", "off", "read"]);
+const SOURCES = new Set(["all", "client", "server"]);
+
+function validationError(message) {
+  const error = new Error(message);
+  error.code = "CLI_ADMIN_CLI_VALIDATION";
+  return error;
+}
+
+function memberName(value) {
+  const name = String(value || "").trim().replace(/^@/, "");
+  if (!name) throw validationError(MEMBER_TRACE_USAGE);
+  if (!/^[^\s/?#]{1,40}$/.test(name)) {
+    throw validationError("Name the member by username or user id.");
+  }
+  return name;
+}
+
+export function buildMemberTraceOperation({ action = "", target = "", options }) {
+  if (action === "list") {
+    return {
+      name: "member-trace.list",
+      method: "GET",
+      path: "/cli/admin/member-trace/accounts",
+      body: undefined,
+      mutates: false,
+      requiresRun: false,
+    };
+  }
+  if (action === "on") {
+    const reason = String(options.adminReason || "").trim();
+    if (!reason) {
+      throw validationError(
+        'Say why with --reason (for example --reason "General chat main keeps reloading").',
+      );
+    }
+    return {
+      name: "member-trace.on",
+      method: "POST",
+      path: "/cli/admin/member-trace/on",
+      body: { user: memberName(target), reason: reason.slice(0, 255) },
+      mutates: true,
+      requiresRun: false,
+    };
+  }
+  if (action === "off") {
+    return {
+      name: "member-trace.off",
+      method: "POST",
+      path: "/cli/admin/member-trace/off",
+      body: { user: memberName(target) },
+      mutates: true,
+      requiresRun: false,
+    };
+  }
+  const user = memberName(action === "read" ? target : action);
+  if (!ACTIONS.has(action) && target) {
+    throw validationError(MEMBER_TRACE_USAGE);
+  }
+  // the owner trace's filters (--since/--until/--cursor/--type/--path/--limit)
+  const owner = buildOwnerTraceOperation(options);
+  const query = new URLSearchParams(owner.path.split("?")[1] || "");
+  query.set("user", user);
+  const source = String(options.adminTraceSource || "").trim();
+  if (source) {
+    if (!SOURCES.has(source)) {
+      throw validationError("--source is all, client (the website on the device) or server (the API's view of its requests).");
+    }
+    query.set("source", source);
+  }
+  return {
+    name: "member-trace.read",
+    method: "GET",
+    path: `/cli/admin/member-trace?${query.toString()}`,
+    body: undefined,
+    mutates: false,
+    requiresRun: false,
+  };
+}
+
+function formatWhen(seconds) {
+  const value = Number(seconds);
+  if (!value) return "never";
+  return new Date(value * 1000).toISOString().replace("T", " ").slice(0, 16) + " UTC";
+}
+
+export function formatMemberTraceList(data) {
+  const accounts = Array.isArray(data?.accounts) ? data.accounts : [];
+  if (!accounts.length) return ["No member is traced."];
+  const lines = [`${accounts.length} traced member account(s):`];
+  for (const account of accounts) {
+    lines.push(
+      `  ${account.username || "?"} (#${account.userId}) · on since ${formatWhen(account.enabledAt)}${account.enabledByUsername ? ` by ${account.enabledByUsername}` : ""} · ${account.reason || "(no reason)"}`,
+    );
+    lines.push(
+      `      last 24 h: ${account.clientRows24h ?? "?"} website event(s) (last ${formatWhen(account.lastClientAt)}), ${account.serverRows24h ?? "?"} API request row(s) (last ${formatWhen(account.lastServerAt)})`,
+    );
+  }
+  return lines;
+}
+
+export function formatMemberTraceSwitch(data) {
+  const who = `${data?.username || "?"} (#${data?.userId ?? "?"})`;
+  if (data?.enabled) {
+    return [
+      data.alreadyOn
+        ? `Member trace was already on for ${who}.`
+        : `Member trace is on for ${who}. Every API process picks it up within ${data.effectiveWithinSeconds ?? 30} s; the website starts tracing at the member's next page load.`,
+    ];
+  }
+  return [
+    data?.wasOn
+      ? `Member trace is off for ${who}. Rows already kept expire after ${data.keptRowsExpireAfterDays ?? 30} days.`
+      : `Member trace was not on for ${who}.`,
+  ];
+}
+
+function count(map, key) {
+  map.set(key, (map.get(key) || 0) + 1);
+}
+
+function listCounts(map) {
+  return [...map.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .map(([key, n]) => `${key} ×${n}`)
+    .join(", ");
+}
+
+// The plain-words summary the daily run reports: which website build the
+// device runs (as the website says and as the API saw it), page loads and how
+// they were opened, self-reloads by reason, errors.
+export function summarizeMemberTrace(data) {
+  const events = Array.isArray(data?.events) ? data.events : [];
+  const client = events.filter((event) => event.type !== "api" && event.type !== "api-dropped");
+  const server = events.filter((event) => event.type === "api" || event.type === "api-dropped");
+  const versions = new Map();
+  const bundles = new Map();
+  const navTypes = new Map();
+  const reloads = new Map();
+  const errors = new Map();
+  const loadCauses = new Map();
+  let socketDrops = 0;
+  let socketDropsVisible = 0;
+  let chatLoadingScreens = 0;
+  for (const event of client) {
+    const data = event.data || {};
+    if (event.type === "session") {
+      count(versions, data.version || "?");
+      if (data.entry) count(bundles, data.entry);
+      count(navTypes, data.navType || "?");
+    } else if (event.type === "boot") {
+      count(
+        loadCauses,
+        data.byCode ? `code:${data.byCode}` : data.on ? "tracing switched on" : data.navType === "reload" ? "reload by hand/browser" : data.navType || "?",
+      );
+    } else if (event.type === "socket" && data.e === "disconnect") {
+      socketDrops += 1;
+      if (data.vis === "visible") socketDropsVisible += 1;
+    } else if (event.type === "chat-loading" && data.e === "shown") {
+      chatLoadingScreens += 1;
+    } else if (event.type === "reload") {
+      count(reloads, data.reason || "?");
+    } else if (event.type === "error" || event.type === "rejection" || event.type === "boundary-error") {
+      count(errors, `${event.type}: ${String(data.msg || "").slice(0, 80)}`);
+    }
+  }
+  const apiVersions = new Map();
+  const statuses = new Map();
+  const devices = new Set();
+  let sessionLoads = 0;
+  for (const event of server) {
+    const data = event.data || {};
+    if (event.type !== "api") continue;
+    count(apiVersions, data.v || "?");
+    devices.add(event.sessionId);
+    const status = data.s === "aborted" ? "aborted" : Number(data.s) >= 400 ? String(data.s) : null;
+    if (status) count(statuses, status);
+    if (String(event.path || "").startsWith("/user/session") && !String(event.path).startsWith("/user/session/")) {
+      sessionLoads += 1;
+    }
+  }
+  const lines = [];
+  lines.push(
+    `Website: ${client.filter((event) => event.type === "session").length} page load(s)${navTypes.size ? ` (opened by ${listCounts(navTypes)})` : ""}${versions.size ? ` · version ${listCounts(versions)}` : ""}${bundles.size ? ` · bundle ${listCounts(bundles)}` : ""}`,
+  );
+  if (loadCauses.size) lines.push(`Why pages loaded: ${listCounts(loadCauses)}`);
+  lines.push(`Self-reloads: ${reloads.size ? listCounts(reloads) : "none recorded"}`);
+  lines.push(
+    `Socket drops: ${socketDrops}${socketDrops ? ` (${socketDropsVisible} while the page was visible)` : ""} · full chat loading screens: ${chatLoadingScreens}`,
+  );
+  lines.push(`Errors: ${errors.size ? listCounts(errors) : "none recorded"}`);
+  lines.push(
+    `API view: ${server.length} request row(s) from ${devices.size} device(s)${apiVersions.size ? ` · reported website version ${listCounts(apiVersions)}` : ""} · session loads ${sessionLoads}${statuses.size ? ` · failures ${listCounts(statuses)}` : ""}`,
+  );
+  if (!client.length && server.length) {
+    lines.push(
+      "  No website events: the device has not run a website build with the member trace yet (an older cached bundle?), or it has not loaded since tracing was switched on.",
+    );
+  }
+  return lines;
+}
+
+export function formatMemberTrace(data) {
+  const user = data?.user || {};
+  const who = `${user.username || "?"} (#${user.id ?? "?"})`;
+  const lines = [
+    `Member trace for ${who}${user.traced ? `, on since ${formatWhen(user.enabledAt)}: ${user.reason || ""}` : ", tracing is OFF (older rows only)"}${data?.source && data.source !== "all" ? ` · ${data.source} rows only` : ""}${data?.duplicates ? ` · ${data.duplicates} re-sent duplicate(s) hidden` : ""}`,
+  ];
+  for (const line of summarizeMemberTrace(data)) lines.push(`  ${line}`);
+  const events = Array.isArray(data?.events) ? data.events : [];
+  const client = events.filter((event) => event.type !== "api" && event.type !== "api-dropped");
+  const server = events.filter((event) => event.type === "api" || event.type === "api-dropped");
+  if (data?.source !== "server") {
+    lines.push("");
+    lines.push(...formatOwnerTrace({ ...data, events: client }, { title: "Website events (from the device)" }));
+  }
+  if (data?.source !== "client") {
+    lines.push("");
+    lines.push(...formatOwnerTrace({ ...data, events: server }, { title: "API view (requests from this account; session = device tag)" }));
+  }
+  return lines;
+}
+
+export function printMemberTraceResult(operation, data) {
+  const lines =
+    operation.name === "member-trace.list"
+      ? formatMemberTraceList(data)
+      : operation.name === "member-trace.read"
+        ? formatMemberTrace(data)
+        : formatMemberTraceSwitch(data);
+  for (const line of lines) console.log(line);
+}

package/lib/admin-news.js

@@ -252,6 +252,20 @@ export function validateNewsEditorial({ claim: claimValue, editorial }) {
 export function writeNewsClaimArtifacts({ result, outputPath, scaffoldPath }) {
   const claim = result?.data?.claim || null;
   const artifacts = { claimFile: null, scaffoldFile: null };
+  if (!claim) {
+    // Nothing to claim (the edition already printed, or the next one has not
+    // opened yet). Never overwrite an existing claim file with a null claim:
+    // that destroyed a valid claim when a run tried too early (11-01, 11-02).
+    const nextEditionAt = Number(result?.data?.newspaper?.nextEditionAt) || null;
+    artifacts.notClaimed = {
+      status: result?.status || null,
+      printDecision: result?.data?.newspaper?.printDecision || null,
+      nextEditionAt,
+      nextEditionAtIso: nextEditionAt ? new Date(nextEditionAt * 1000).toISOString() : null,
+      outputLeftUnchanged: outputPath || null,
+    };
+    return artifacts;
+  }
   if (outputPath) {
     artifacts.claimFile = writeAdminJsonFile(
       outputPath,

package/lib/admin-owner-trace.js

@@ -129,6 +129,7 @@ function describeSession(data = {}, path = "") {
       : data.navType
         ? `nav ${data.navType}`
         : "",
+    data.entry ? `bundle ${data.entry}` : "",
     describeNet(data.net),
   ].filter(Boolean);
   if (path) parts.push(`at ${path}`);
@@ -186,6 +187,24 @@ export function describeOwnerTraceEvent(event) {
     case "error":
     case "rejection":
       return `${data.msg || "(no message)"}${data.src ? ` (${data.src}:${data.line}:${data.col})` : ""}${data.status ? ` HTTP ${data.status}` : ""}`;
+    // the member trace's events (and the reload/chat ones the owner trace
+    // now records too)
+    case "reload":
+      return `SELF-RELOAD ${data.reason || "?"}${pairs(data, ["reason", "v"]) ? ` · ${pairs(data, ["reason", "v"])}` : ""}`;
+    case "chat-select":
+      return `channel ${data.channelId ?? "?"}${data.subchannel ? `/${data.subchannel}` : ""}${data.subchannelId ? ` (subchannel ${data.subchannelId})` : ""}${data.pathId ? ` · path ${data.pathId}` : ""}${data.chatType ? ` · ${data.chatType}` : ""}`;
+    case "boot":
+      return `page loaded${data.navType ? ` (${data.navType})` : ""}${data.byCode ? ` · reloaded by code: ${data.byCode} ${data.byCodeAgoMs ?? "?"}ms earlier${data.byCodeAt ? ` at ${data.byCodeAt}` : ""}` : data.navType === "reload" ? " · no code reload note (by hand or by the browser)" : ""}${data.kept ? ` · ${data.kept} batch(es) kept from an earlier page` : ""}${data.on ? ` · tracing switched on (${data.on})` : ""}`;
+    case "socket":
+      return `socket ${data.e || "?"}${data.reason ? ` (${data.reason})` : ""} · ${data.vis || "?"}${data.visibleForMs !== undefined ? ` ${formatDuration(data.visibleForMs)} after the page became visible` : ""}${data.upMs !== undefined ? ` · was up ${formatDuration(data.upMs)}` : ""}${data.downMs !== undefined ? ` · was down ${formatDuration(data.downMs)}` : ""}`;
+    case "chat-loading":
+      return data.e === "shown" ? 'full "Loading Twinkle Chat..." screen shown' : `full chat loading screen gone after ${formatDuration(data.ms)}`;
+    case "boundary-error":
+      return `error screen at ${data.at || "?"}: ${data.msg || "(no message)"}${data.lazy ? " · chunk load" : ""}${data.truncated ? " · truncated chunk" : ""}`;
+    case "api":
+      return describeApiRow(data, event.path);
+    case "api-dropped":
+      return `${data.count ?? "?"} more API request(s) in that minute not kept (cap)`;
     default:
       return pairs(data);
   }
@@ -251,6 +270,16 @@ function describeWake(data) {
   return parts.join(" · ");
 }
 
+// One request the API saw from a traced member: method, route, status, time,
+// the website version the request reported.
+function describeApiRow(data) {
+  const params = isPlainObject(data.p)
+    ? ` ${Object.entries(data.p).map(([key, value]) => `${key}=${value}`).join(",")}`
+    : "";
+  const server = [data.h ? `host ${data.h}` : "", data.pst ? `worker since ${new Date(data.pst * 1000).toISOString().slice(11, 19)}Z` : ""].filter(Boolean).join(" ");
+  return `${data.m || "?"} → ${data.s ?? "?"} in ${data.ms ?? "?"}ms · website v${data.v || "?"}${params}${server ? ` · ${server}` : ""}${data.ua ? ` · ua ${data.ua}` : ""}`;
+}
+
 function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -336,13 +365,13 @@ function describeNavTiming(data) {
   return [head, `${data.nav || "?"} via ${data.via || "?"}`, ...steps, ...tail].join(" · ");
 }
 
-export function formatOwnerTrace(data) {
+export function formatOwnerTrace(data, { title = "Owner trace" } = {}) {
   const events = Array.isArray(data?.events) ? data.events : [];
   const lines = [];
   const sessions = new Set(events.map((event) => event.sessionId));
   const since = Number(data?.since || 0);
   lines.push(
-    `Owner trace since ${since ? `${formatDay(since * 1000)} ${formatClock(since * 1000).slice(0, 5)}` : "?"} · ${events.length} event(s) · ${sessions.size} session(s)${data?.truncated ? ` · more pages (keep --since/--until; --cursor ${data.nextCursor || "unavailable"})` : ""}`,
+    `${title} since ${since ? `${formatDay(since * 1000)} ${formatClock(since * 1000).slice(0, 5)}` : "?"} · ${events.length} event(s) · ${sessions.size} session(s)${data?.truncated ? ` · more pages (keep --since/--until; --cursor ${data.nextCursor || "unavailable"})` : ""}`,
   );
   if (!events.length) {
     lines.push("Nothing recorded in this window.");

package/lib/admin.js

@@ -44,6 +44,10 @@ import {
   buildOwnerTraceOperation,
   printOwnerTrace,
 } from "./admin-owner-trace.js";
+import {
+  buildMemberTraceOperation,
+  printMemberTraceResult,
+} from "./admin-member-trace.js";
 import { buildRolesOperation, printRoles } from "./admin-roles.js";
 import { buildSpendingOperation, completeSpendingReport, formatSpending } from "./admin-spending.js";
 import { buildCraftOperation, formatCraftResult } from "./admin-craft.js";
@@ -1872,6 +1876,7 @@ function transformAdminResult({
   }
   if (operation.name === "subjects.candidates") {
     assertSubjectWindowResult({ operation, result: transformed });
+    transformed = markSubjectsNeedingReveal(transformed);
   }
   if (operation.name === "builds.candidates") {
     assertBuildWindowResult({ operation, result: transformed });
@@ -1923,6 +1928,30 @@ export function assertRecommendationWindowResult({ operation, result }) {
   }
 }
 
+// A secret Subject's effort can't be set until its secret is revealed through
+// the canonical action (CLI_ADMIN_SECRET_REVEAL_REQUIRED). Say so on the
+// candidate itself, with the exact command, instead of failing at effort set.
+export function markSubjectsNeedingReveal(result) {
+  const subjects = result?.data?.subjects;
+  if (!Array.isArray(subjects)) return result;
+  return {
+    ...result,
+    data: {
+      ...result.data,
+      subjects: subjects.map((subject) => {
+        const needsReveal =
+          (subject?.secret?.hasSecret === true ||
+            subject?.hasSecretAnswer === true ||
+            subject?.hasSecretAttachment === true) &&
+          subject?.secret?.revealed !== true;
+        return needsReveal
+          ? { ...subject, needsReveal: true, revealCommand: `lumine admin subject reveal ${subject.id}` }
+          : subject;
+      }),
+    },
+  };
+}
+
 export function assertSubjectWindowResult({ operation, result }) {
   const mode = operation?.pagination?.coverageMode;
   if (!mode || mode === "legacy") return;
@@ -2714,6 +2743,10 @@ export function parseAdminOperation(options) {
   if (namespace === "owner-trace") {
     return buildOwnerTraceOperation(options);
   }
+  // The owner trace switched on for specific members (admin-member-trace.js).
+  if (namespace === "member-trace") {
+    return buildMemberTraceOperation({ action, target, options });
+  }
   if (namespace === "jev-routing") {
     return buildJevRoutingReviewOperation({ action, target, extra, options });
   }
@@ -6199,9 +6232,10 @@ async function printSpooledAdminResult({ operation, result, storage }) {
     console.log(`${count} subject(s):`);
     await forEachPaginatedResultItem(result, async (subject) => {
       console.log(
-        `#${subject.id} ${subject.title || "(untitled)"} — ${subject.author?.username || "unknown"} — effort ${subject.effortLevel ?? "unknown"}`,
+        `#${subject.id} ${subject.title || "(untitled)"} — ${subject.author?.username || "unknown"} — effort ${subject.effortLevel ?? "unknown"}${subject.needsReveal ? " — secret: reveal before setting effort" : ""}`,
       );
       console.log(`  ${subject.url}`);
+      if (subject.needsReveal) console.log(`  ${subject.revealCommand}`);
     });
   } else if (storage.collectionKey === "events") {
     console.log(`${count} audit event(s):`);
@@ -7691,6 +7725,10 @@ function printAdminResult({ operation, result }) {
     printOwnerTrace(data);
     return;
   }
+  if (String(operation.name || "").startsWith("member-trace.")) {
+    printMemberTraceResult(operation, data);
+    return;
+  }
   if (operation.name === "jevRouting.review") {
     for (const line of formatJevRoutingReview(data)) console.log(line);
     return;
@@ -8227,9 +8265,10 @@ function printAdminResult({ operation, result }) {
     console.log(`${data.subjects.length} subject(s):`);
     for (const subject of data.subjects) {
       console.log(
-        `#${subject.id} ${subject.title || "(untitled)"} — ${subject.author?.username || "unknown"} — effort ${subject.effortLevel ?? "unknown"}`,
+        `#${subject.id} ${subject.title || "(untitled)"} — ${subject.author?.username || "unknown"} — effort ${subject.effortLevel ?? "unknown"}${subject.needsReveal ? " — secret: reveal before setting effort" : ""}`,
       );
       console.log(`  ${subject.url}`);
+      if (subject.needsReveal) console.log(`  ${subject.revealCommand}`);
     }
     printPagination(data.pagination);
     return;
@@ -8248,6 +8287,19 @@ function printAdminResult({ operation, result }) {
     printPagination(data.pagination);
     return;
   }
+  if (data.artifacts?.notClaimed) {
+    const info = data.artifacts.notClaimed;
+    const opens = info.nextEditionAt
+      ? `${new Date(info.nextEditionAt * 1000).toISOString().replace(".000Z", "Z")} (${new Date(info.nextEditionAt * 1000).toLocaleString("en-US", { timeZone: "Asia/Seoul", hour: "2-digit", minute: "2-digit", month: "short", day: "numeric" })} KST)`
+      : "an unknown time";
+    console.log(
+      `No edition to claim${info.printDecision === "already_printed" ? ": today's paper is already printed" : ""}. The next edition opens at ${opens}.`,
+    );
+    if (info.outputLeftUnchanged) {
+      console.log(`${info.outputLeftUnchanged} was left unchanged. Run news claim again after the edition opens.`);
+    }
+    return;
+  }
   if (data.claim) {
     if (data.artifacts?.claimFile) {
       console.log(

package/lib/commands.js

@@ -2472,6 +2472,9 @@ export function parseArgs(args) {
   const raw = {};
   const positional = [];
   const booleanFlags = new Set([
+    // lumine admin jev-images thumbnails --featured [--saved-only]
+    "featured",
+    "savedOnly",
     // lumine admin arena import --live
     "live",
     "additive",
@@ -2698,6 +2701,8 @@ export function parseArgs(args) {
     adminPath: raw.path ? String(raw.path) : "",
     adminPerf: Boolean(raw.perf),
     adminWake: Boolean(raw.wake),
+    // lumine admin member-trace <username> --source all|client|server
+    adminTraceSource: raw.source ? String(raw.source) : "",
     adminMinLevel: raw.minLevel === undefined ? null : raw.minLevel,
     adminIncludeLegacy: Boolean(raw.includeLegacy),
     adminIncludePrivateEvidence: parseBoolean(
@@ -2725,6 +2730,9 @@ export function parseArgs(args) {
     adminJevArea: raw.area ? String(raw.area) : "",
     adminJevKey: raw.key ? String(raw.key) : "",
     adminJevDailyCap: raw.dailyCap === undefined ? "" : String(raw.dailyCap),
+    adminTargets: raw.targets ? String(raw.targets) : "",
+    adminFeatured: parseBoolean(raw.featured, false),
+    adminSavedOnly: parseBoolean(raw.savedOnly, false),
     adminClaimFile: raw.claim ? String(raw.claim) : "",
     adminScaffoldFile: raw.scaffold ? String(raw.scaffold) : "",
     adminTargetFile: raw.targetFile ? String(raw.targetFile) : "",
@@ -3399,8 +3407,9 @@ export function printHelp() {
   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 owner-trace [--since 2h|30m|3d|<iso>] [--type route,feed-open,scroll-anchor,content-scroll,error,rejection,session,nav-timing,slow-request,stall,page-load,scroll-perf,scroll-frame] [--perf] [--wake] [--path <substring>] [--limit 300] [--json]   (--wake: sessions, 20 s wake profiles, bounded viewport geometry and dropped-event counts after loads or returns; network tags identify the upload network; what the website did on Mikey's own devices: routes with PUSH/POP/REPLACE, Home feed card opens, scroll-anchor restores, content scroll positions, window errors, and performance: tap-to-page timing, API requests over 1 s, main-thread stalls over 200 ms, page load, scroll frame pacing and slow-frame attribution (Long Animation Frame scripts on Chrome, feed card renders on Safari); --perf shows only those; kept 30 days)
+  lumine admin member-trace list | on <username> --reason <why> | off <username> | [read] <username> [--since 2h|30m|3d|<iso>] [--source all|client|server] [--type reload,route,chat-select,boot,session,error,rejection,boundary-error,api] [--path <substring>] [--limit 300] [--json]   (the owner trace switched on for specific member accounts to chase a bug they report: on/off are audited admin actions and take effect within 30 s; the website side records page loads with version and bundle, routes, chat channel/subchannel selection, every self-reload with its reason (kept on the device across the reload), error screens and window errors; the API side records each request from that account with its route, status, time and the website version it reported, so a device stuck on an old cached bundle still shows; read prints a plain summary first; kept 30 days)
   lumine admin roles [--min-level 1] [--limit 50] [--json]   (every user type with its management level and who holds it; admin pages need level 3, achievement points never pass level 2)
-  lumine admin jev-images report [--days 1..30] | switch --area <all|arena_paper|arena_picture|study_record|thumbnail|sdk_decide> --mode on|off [--daily-cap <0-5000>] | decide --area <area> --key <subject key> --decision <decision> [--json]   (JEV image checks: advisory only; per-area health, cost, agreement with final decisions and escalations for the daily run; switch is owner-only and needs no deploy)
+  lumine admin jev-images report [--days 1..30] | switch --area <all|arena_paper|arena_picture|study_record|thumbnail|sdk_decide> --mode on|off [--daily-cap <0-5000>] [--build <id>, sdk_decide only, no --daily-cap] | decide --area <area> --key <subject key> --decision <decision> | thumbnails --targets <subject:<id>,build:<id>,...> | --featured [--saved-only] [--json]   (JEV image checks: advisory only; per-area health, cost, agreement with final decisions and escalations for the daily run; switch is owner-only and needs no deploy; thumbnails adds notes for Featured review and never replaces or unfeatures anything)
   lumine admin jev-routing review --since <unix|ISO> --until <unix|ISO> [--limit 1..20] [--cursor <cursor> | --all --checkpoint <file> [--resume]] [--include-synthetic] [--json]   (bounded frozen evidence for paired disagreements and Auto fallbacks; collection is not 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.77",
+  "version": "0.3.79",
   "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.76.0
+Version: 1.78.0
 Updated: 2026-11-01
-Generated: 2026-11-01T11:22:03.891Z
+Generated: 2026-11-02T01:19:13.071Z
 
 ## Platform rules
 Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.
@@ -71,7 +71,7 @@ Features every app needs whenever they apply. When you build a new app or make a
 
 ## AI decision design
 - Twinkle.ai.decide runs JEV, a model for narrow decisions over supplied text or structured state, and it is free for viewers: decisions are covered by Twinkle and never use their AI Energy. Whenever an app makes a judgment that ordinary code can only approximate, consider JEV first. Proven patterns: an opponent or boss coach that reads the player's habits (favourite lane, repeated trick, cheese move) and picks a counter-plan from a fixed list, as in Red Square's boss and Open Football's opponent coach; NPCs that understand what a player types and choose an action; classifying or scoring user submissions; ranking supplied candidates; and picking the next exercise or difficulty from evidence about the learner. Any app with an AI opponent, NPC, or adaptive difficulty should decide explicitly whether JEV improves it. These are examples to reason from, not a keyword checklist or a requirement to add AI to every app.
-- Choose the mechanism by the work: use ordinary code for known rules, arithmetic, physics, legal moves, storage, and permissions; use ai.decide for contextual choices, yes/no probabilities, and scores; use ai.chat or ai.generateObject for generated dialogue, explanations, open-ended content, and multi-step reasoning. JEV does not generate text, browse the web, inspect images, or supply missing app data. Combine these tools when it benefits the actual request, without silently turning every decision into a more expensive text-model call.
+- Choose the mechanism by the work: use ordinary code for known rules, arithmetic, physics, legal moves, storage, and permissions; use ai.decide for contextual choices, yes/no probabilities, and scores; use ai.chat or ai.generateObject for generated dialogue, explanations, open-ended content, and multi-step reasoning. JEV does not generate text, browse the web, or supply missing app data. Looking at pictures is a preview (decide with images, see its notes): use it only when the creator asks for it, and keep the feature working when it is unavailable. Combine these tools when it benefits the actual request, without silently turning every decision into a more expensive text-model call.
 - Before adopting JEV, identify the concrete decision, the context available at that moment, the allowed outcomes, and why the added latency is worthwhile. Use your model judgment to make that choice. Do not substitute regex or keyword matching for understanding human-language intent. Explain the user-visible benefit simply; the creator does not need to select a provider, enter an API key, or design question schemas.
 - Send related independent questions about the same state together in one ai.decide request (up to 32). Write complete instructions and distinct option or level descriptions. Include an other/uncertain option when the choices might not cover the input. A second call is useful only when it needs newly obtained context or choices that depend on the first result; answers in one batch do not see each other.
 - Keep code in control. Choice returns an option and its probability distribution; score returns a position on the declared levels; noul is the probability of yes, with 0.5 meaning uncertainty rather than medium strength. Confidence describes the distribution and is not proof of correctness. Test the app's criteria and thresholds on clear, ambiguous, and out-of-scope examples, and provide a suitable uncertain outcome. JEV decisions never authorize XP, Coins, purchases, access, or other server-owned state; use the appropriate existing SDK and server approval paths.
@@ -531,10 +531,10 @@ renderBattery(policy?.energyPercent, policy?.energySegmentsRemaining);
   - Use this for in-app AI replies instead of creating or fetching app-local endpoints such as /api/chat.
   - Example: const chatHistory = conversation.slice(-12).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text }));
 const result = await Twinkle.ai.chat({ message, history: chatHistory, systemPrompt: 'You are a cheerful pirate helper who answers in one sentence.', onText: (text, meta) => renderReply(text), onStatus: (status) => setThinking(status === 'thinking') });
-- async decide({ state, questions }) | scopes: none
-  - Returns: { answers, model, provider, aiUsagePolicy }
+- async decide({ state, questions, images }) | scopes: none
+  - Returns: { answers, model, provider, aiUsagePolicy, imageCount? }
   - Use JEV for fast contextual choices, yes/no probabilities, and scores inside a running app. Send several independent questions about the same state together.
-  - Read the AI decision design guidance when deciding whether this capability benefits the app. This method evaluates supplied context; it does not generate prose, browse, inspect images, run tools, grant access, or award XP/Coins.
+  - Read the AI decision design guidance when deciding whether this capability benefits the app. This method evaluates supplied context; it does not generate prose, browse, run tools, grant access, or award XP/Coins. It looks at pictures only through the preview images option below.
   - state is non-empty text, a JSON object, or a JSON array. questions maps your question IDs to { type, instructions, criteria? }. Instructions may be non-empty text or structured JSON. Every question sees the same state and answers independently; put the complete question in instructions, not just its ID.
   - Choice: { type: 'choice', instructions, criteria: { optionName: description, other: description } }. Supply 2–255 named options. Each description is text, structured JSON, or null. Returns { type: 'choice', choice, probabilities, confidence } under answers[questionId].
   - Score: { type: 'score', instructions, criteria: [lowestLevelDescription, ..., highestLevelDescription] }. Supply 2–10 concrete ordered descriptions. Returns { type: 'score', score, probabilities, confidence, legend }. Levels start at 0; score may be fractional and is a probability-weighted position between 0 and criteria.length - 1.
@@ -542,6 +542,7 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - A request accepts 1–32 questions, at most 64 KB of JSON and 20 levels of nesting. Question IDs and option names must be non-empty, at most 128 characters, and cannot be __proto__, constructor, or prototype. Descriptions may use structured JSON; state must contain only data the app is allowed to access.
   - Requires a signed-in viewer and uses the normal runtime AI rate limits. Twinkle selects and calls JEV on its server; never put provider credentials or an external endpoint in app code. Decisions are covered by Twinkle: they never use the viewer's AI Energy, and a viewer with empty Energy still gets answers. The response includes the viewer's current canonical aiUsagePolicy, unchanged by the call.
   - Errors include invalid_ai_decision (bad input), ai_decision_unavailable, ai_decision_timeout, ai_decision_rate_limited, ai_decision_invalid_response, and ai_usage_unavailable, plus the existing auth, access, Energy, and rate-limit errors. Invalid answers are rejected. An answer that fails validation is retried once on the server within the same deadline; there is no other provider retry, fabricated answer, or paid LLM fallback. Do not automatically retry a rejected request.
+  - Preview: images (not generally available yet). Pass images: { name: picture } with 1-4 entries to let JEV look at pictures. Names use lowercase letters, digits and underscores (e.g. drawing); each name becomes a key of state, so state must then be a JSON object without that key, and instructions refer to the picture by name (e.g. 'Does `drawing` show a cat?'). A picture is this app's own upload URL (from Twinkle.files, at most 5 MB each), a canvas, or a PNG/JPEG/WebP Blob of at most 3 MB (5 MB of snapshots per decision). All pictures of one decision together must be at most 10 MB; a larger one is refused with 'Image too large: max 5 MB each, 10 MB per decision. Resize the picture first.' so resize big pictures before asking. Image decisions are covered by Twinkle like text decisions. Only some run at once (one per player, several per app, and a generous ceiling per minute for the app), so wait for one answer before asking again and do not call decide in a tight loop. Until Twinkle turns them on for the app, and whenever a picture cannot be checked or too many decisions are running, decide throws ai_decision_unavailable with a reason (disabled, app_disabled, rate_limited, capped, images_dropped, timeout, ...). There is never a text-only answer that ignores the pictures. Use images only when the creator asks for it, keep the feature usable without it (for example skip the AI check and let the player continue), and never use the answer for safety, access, XP or Coins.
   - Call on meaningful app events with bounded frequency, batch questions, and keep rendering and deterministic game rules in local code. Ignore a result if the app state or turn changed while it was pending. Test uncertain inputs and choose a fallback appropriate to the experience; confidence is not a correctness guarantee.
   - Example: const { answers } = await Twinkle.ai.decide({ state: { playerRequest, availableActions }, questions: { action: { type: 'choice', instructions: 'Which available companion action best fits playerRequest? Use wait when unclear.', criteria: { follow: 'Follow the player', guard: 'Stay and keep watch', wait: 'Do nothing until clarified' } }, needsClarification: { type: 'noul', instructions: 'Is playerRequest too ambiguous to act on?' } } }); const action = answers.needsClarification.noul > 0.5 ? 'wait' : answers.action.choice;
 - async generateObject({ prompt, expectedStructure, images, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus, onReasoning } = {}) | scopes: none
@@ -970,10 +971,11 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - map.heightUrlTemplate (or null) gives the land's shape on the same tile grid for 3D maps (ground heights; buildings and trees narrower than about 20 blocks are left out, so draw those from getTerrainChunks): a gzipped 'THM1' file, 16-byte little-endian header (magic, uint16 samples per side, uint16 blocks per sample, float64 source time) then samples x samples int16 heights row by row (z, then x); -32768 = no ground. Images and heights are served with CORS, so WebGL can use them.
   - Example: const { worlds } = await Twinkle.minecraft.getWorlds(); const w = worlds.find((x) => x.id === 'world'); const z = w.map.maxZoom; const blocksPerTile = w.map.blocksPerTileAtMaxZoom * 2 ** (w.map.maxZoom - z); const tx = Math.floor(blockX / blocksPerTile), ty = Math.floor(blockZ / blocksPerTile); const url = w.map.tileUrlTemplate.replace('{z}', z).replace('{x}', tx).replace('{y}', ty);
 - async getOnlinePlayers() | scopes: content:read
-  - Returns: { players: [{ name, world, x, y, z, isZero }], count, stale }
+  - Returns: { players: [{ name, world, x, y, z, isZero }], count, visitors: [{ userId, username, world, x, y, z, since }], visitorCount, stale }
   - List players currently online with their world and block coordinates. Zero appears with isZero: true and is not counted in count.
   - Cached for about 5 seconds; poll no faster than every 5 seconds.
   - Names are Minecraft usernames, not Twinkle usernames.
+  - visitors are website members walking the world from Twinkle MC Explorers (Twinkle usernames, not Minecraft names). They are online and visible in game but are not players on the server; count counts players only.
   - Example: const { players, count } = await Twinkle.minecraft.getOnlinePlayers();
 - async getZero() | scopes: content:read
   - Returns: { zero: { online, world, position: { x, y, z } | null, activity: 'idle'|'thinking'|'building'|'workshop', currentBuild: { id, title, status, placed, total, requester, world, bounds } | null, queue: [build], workshop: { world, min, max } | null, updatedAt }, stale }
@@ -1004,21 +1006,22 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - 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
-  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived }], latestSeq, online, archiveReady, viewer: { canSend, muted, canModerate }, mutedUserIds }
+  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death'|'visit'|'unvisit', name, text, userId, archived }], latestSeq, online, visitorCount, archiveReady, viewer: { canSend, muted, canModerate }, mutedUserIds }
   - Live server chat after a sequence number: player chat, Zero, messages sent from the web, joins, leaves and deaths.
   - Without since (or 0) it returns the newest 50 events, oldest first. Pass since = latestSeq from the previous response to get only new events. Poll every 2-3 seconds while the chat is visible; stop when hidden.
-  - kind: chat (a player), zero (Zero, the AI builder), web (someone chatting from the Twinkle app; userId is their Twinkle user id), join, leave, death. Private messages are never included.
+  - kind: chat (a player), zero (Zero, the AI builder), web (someone chatting from the Twinkle app; userId is their Twinkle user id), join, leave, death, visit (a website visitor arrived in the world; userId is their Twinkle user id), unvisit (they left). Private messages are never included.
   - name is a Minecraft username for chat/join/leave/death, and a Twinkle username for web.
   - viewer.canModerate is true only for the server owner; mutedUserIds is filled only for them.
+  - online counts players on the server; visitorCount counts website visitors walking the world (Twinkle MC Explorers).
   - Example: let since = 0; async function poll() { const { events, latestSeq } = await Twinkle.minecraft.getChat({ since }); since = latestSeq; render(events); } setInterval(poll, 2500);
 - async getChatHistory({ before, limit, query, includeArchived } = {}) | scopes: content:read
-  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived }], hasMore, nextBefore: { at, seq } | null, includesArchived }
+  - Returns: { events: [{ seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death'|'visit'|'unvisit', name, text, userId, archived }], hasMore, nextBefore: { at, seq } | null, includesArchived }
   - Older server chat, newest first, for scrolling back or searching past days.
   - before is the nextBefore cursor from the previous page; omit it to start from the newest. limit 1-100 (default 50). query searches message text and names (60 chars).
   - Chat from before the web chat bridge existed (imported from server logs) is archived: only the server owner can include it with includeArchived: true; others never receive it.
   - Example: const page = await Twinkle.minecraft.getChatHistory({ limit: 50 }); const older = await Twinkle.minecraft.getChatHistory({ before: page.nextBefore });
 - async sendChat({ text }) | scopes: content:write
-  - Returns: { event: { seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death', name, text, userId, archived } }
+  - Returns: { event: { seq, at, kind: 'chat'|'zero'|'web'|'join'|'leave'|'death'|'visit'|'unvisit', name, text, userId, archived } }
   - Send a chat message from the app into the Minecraft server; players see it as [Web] <your Twinkle username>.
   - Signed-in viewers only. text is trimmed to 200 characters. About one message per 2.5 seconds and 10 per minute per person: 429 with code minecraft_chat_rate_limited and retryAfterMs.
   - 403 minecraft_chat_forbidden for accounts banned from chat; 400 minecraft_muted when the server owner muted them from web chat.
@@ -1052,6 +1055,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Built-in designs (redstone devices and so on) have no author and are public.
   - previewUrl is an image set with updateDesign, or null.
   - access says what this viewer may do: canOrder shows placement tools (builders, moderators, the owner).
+  - access.web is true for a website member with no Minecraft account (a visitor): they may ask Zero for builds (the first is reviewed) and their designs are always public.
   - Example: const { designs } = await Twinkle.minecraft.getDesigns({ query: 'castle' });
 - async getDesign({ id }) | scopes: content:read
   - Returns: { design: { id, version, name, category, summary, size: { width, height, depth }, blocks, status, author, authorUserId, visibility: 'private'|'public', previewUrl, createdAt }, size: [w, h, d], palette: [blockState], cells: number[] }
@@ -1082,27 +1086,50 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
 - async checkPlacement({ designId, world, x, z, y?, facing?: 'north'|'east'|'south'|'west' }) | scopes: content:read
   - Returns: { check: { clear, reasons, world, facing, anchor, bounds: { min, max }, ground: { y, min, max, water }, builtBlocks, builtSamples, placedBy: [{ name, blocks }], design } }
   - Check a building site for a design: where it would sit and whether it would touch anyone's builds.
-  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Website members with no Minecraft account (visitors) may too; a visitor not approved yet has no builds to stop or undo. Others get 403 minecraft_not_linked or minecraft_rank_too_low.
   - The footprint is centred on x/z and turned to face facing; without y it sits on the ground. clear is false when built (non-natural) blocks stand in the footprint or 3 blocks around it, the ground is very uneven, or it would leave the world; reasons explains. placedBy lists players CoreProtect recorded placing blocks there.
   - Call on a user action (drop or rotate), not while dragging.
+  - Visitors (no Minecraft account) may only check or order a site within about 64 blocks of where they stand in Twinkle World (Twinkle.minecraft.visit): 403 minecraft_visit_closer otherwise; and about 10 checks or orders a minute (429 minecraft_web_order_rate_limited with retryAfterMs).
   - Example: const { check } = await Twinkle.minecraft.checkPlacement({ designId: 'harbor_house', world: 'world', x: 1200, z: 700, facing: 'south' }); outline.color = check.clear ? 'green' : 'red';
 - async buildDesign({ ...placement, force }) | scopes: content:write
-  - Returns: { jobId, check, priority }
+  - Returns: { jobId, check, priority, pending?, requestId? }
   - Order Zero to build a design at a site; he switches to creative and builds it before other work.
-  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Who may: the server owner; builders and moderators by their linked Minecraft account (createLinkCode + /link); and website members with no Minecraft account (visitors). A visitor's FIRST order is held for the server owner's review: the answer is { jobId: null, pending: true, requestId, check } and nothing is built yet; once approved (getVisitorRequests().mine.approved) they order like builders. Linked players below builder get 403 minecraft_rank_too_low.
   - Follow progress with getZero() (currentBuild) and getZeroBuilds().
   - Builders: one order waiting or building at a time, published designs or their own, and orders wait in the normal queue (priority false). Moderators: up to 3 orders, ahead of other work. The owner: no limit. force (build on a site that isn't clear) is owner-only.
+  - Visitors (no Minecraft account) may only check or order a site within about 64 blocks of where they stand in Twinkle World (Twinkle.minecraft.visit): 403 minecraft_visit_closer otherwise; and about 10 checks or orders a minute (429 minecraft_web_order_rate_limited with retryAfterMs).
   - Example: const { jobId } = await Twinkle.minecraft.buildDesign({ designId: 'harbor_house', world: 'world', x: 1200, z: 700, facing: 'south' });
+- async getVisitorRequests() | scopes: content:read
+  - Returns: { canReview, requests: [{ id, userId, username, uuid, designId, designName, blocks, world, anchor, facing, bounds, createdAt }], approved: [{ userId, username, approvedAt, approvedBy }], recent: [{ id, userId, username, decision, by, at, note }], mine: { approved, request, lastDecision } }
+  - Website visitors' first Zero build requests, waiting for review like a builder request; and the viewer's own status.
+  - Only the server owner, in an app they own, gets canReview: true and the full lists; everyone else gets empty lists and only mine (their own open request, whether they are approved, and their last decision).
+  - Example: const { canReview, requests, mine } = await Twinkle.minecraft.getVisitorRequests(); if (mine.request) showWaiting(mine.request);
+- async decideVisitorRequest({ id, approve, note }) | scopes: content:write
+  - Returns: { approved, built, jobId, check, message }
+  - Approve or reject a website visitor's first Zero build request. Approving makes them a visitor who may order like a builder from then on and places the held build.
+  - Server owner only, in an app they own; others get 403 minecraft_roles_forbidden.
+  - built is false (with check and message) when the site is no longer clear: they stay approved and can order again elsewhere.
+  - Example: await Twinkle.minecraft.decideVisitorRequest({ id: request.id, approve: true });
+- async withdrawVisitorRequest() | scopes: content:write
+  - Returns: { withdrawn }
+  - A visitor takes back their own build request that is still waiting for review.
+  - withdrawn is false when there was nothing waiting (or the viewer has a linked Minecraft account).
+  - Example: await Twinkle.minecraft.withdrawVisitorRequest();
+- async revokeVisitorBuilder({ userId }) | scopes: content:write
+  - Returns: { revoked }
+  - Take back a visitor's approval: their next Zero order is held for review again.
+  - Server owner only, in an app they own; others get 403 minecraft_roles_forbidden.
+  - Example: await Twinkle.minecraft.revokeVisitorBuilder({ userId: 101 });
 - async stopZero() | scopes: content:write
   - Returns: { stopped, message }
   - Stop the build Zero is doing right now (placed blocks stay).
-  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Website members with no Minecraft account (visitors) may too; a visitor not approved yet has no builds to stop or undo. Others get 403 minecraft_not_linked or minecraft_rank_too_low.
   - Anyone may stop or undo their own builds; moderators also builders' and members' builds and Zero's own projects; the owner anything.
   - Example: await Twinkle.minecraft.stopZero();
 - async undoBuild({ jobId }) | scopes: content:write
   - Returns: { undone, title, message }
   - Undo one of Zero's builds, putting back what was there before.
-  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Others get 403 minecraft_not_linked or minecraft_rank_too_low.
+  - Who may: the server owner, and builders or moderators identified by their linked Minecraft account (Twinkle.minecraft.createLinkCode + /link). Website members with no Minecraft account (visitors) may too; a visitor not approved yet has no builds to stop or undo. Others get 403 minecraft_not_linked or minecraft_rank_too_low.
   - Anyone may stop or undo their own builds; moderators also builders' and members' builds and Zero's own projects; the owner anything.
   - Example: await Twinkle.minecraft.undoBuild({ jobId });
 - async getSnaps({ before, limit, uuid } = {}) | scopes: content:read
@@ -1193,6 +1220,28 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - It shows the world as last saved (the server saves every few minutes). Pair it with world.map.heightUrlTemplate for the land farther away.
   - Reads share the 180-per-minute build read limit: ask for 24 at a time, nearest first, and keep what you loaded.
   - Example: const { scenes } = await Twinkle.minecraft.getTerrainChunks({ world: 'world', chunks: [[71, 38], [72, 38]] });
+- async getFullChunks({ world, chunks: [[cx, cz], ...] }) | scopes: content:read
+  - Returns: { scenes: [{ cx, cz, scene: { origin: [x,y,z], size: [w,h,d], palette, blocks, light, biomes, count, wide? } | null }] }
+  - Every block with a visible face in chunk columns of a world (up to 24 per call): roofed interiors and caves too, unlike getTerrainChunks. For walking inside buildings near the viewer.
+  - Same scene format as getTerrainChunks and getPlayAreaChunks; larger, so ask only for the few columns around the viewer and use getTerrainChunks farther out.
+  - It shows the world as last saved (the server saves every few minutes) and is cached for about a minute.
+  - Reads share the 180-per-minute build read limit: keep what you loaded, nearest first.
+  - Only the land around the viewer's own visit spot: call visit first; chunks more than 4 columns from where they stand in that world get 403 minecraft_visit_closer (use getTerrainChunks there).
+  - Example: const { scenes } = await Twinkle.minecraft.getFullChunks({ world: 'world', chunks: [[71, 38]] });
+- async visit({ world, x, y, z, yaw, pitch, moving }) | scopes: content:write
+  - Returns: { players: [{ name, uuid, world, x, y, z, yaw, pitch, sneaking, isZero }], visitors: [{ userId, username, world, x, y, z, yaw, pitch, moving }], stale, full, serverTime, intervalMs }
+  - Visit the real Minecraft world from the app: report where the viewer is standing and get back where the players and the other visitors in that world are. In game, the visitor shows as a figure with their Twinkle username.
+  - Signed-in viewers only. Call it about every intervalMs (500 ms) while the viewer is in the world; faster calls get 429 minecraft_visit_rate_limited with retryAfterMs. Interpolate avatars between answers.
+  - A visitor is not a player on the server: they cannot break, place or use anything there. Members who own Minecraft play at twinklemc.site.
+  - The viewer is never in visitors. stale: true means player positions could not be refreshed (show the last ones).
+  - The figure disappears about 5 seconds after the last call; call leaveVisit when the viewer leaves or switches worlds. 403 minecraft_visit_forbidden for accounts banned from chat.
+  - full: true means the world already shows the most visitors it can (40): this viewer can look around but is not shown in game yet.
+  - Example: const view = await Twinkle.minecraft.visit({ world: 'world', x: 1146.5, y: 64, z: 618.5, yaw: 90, pitch: 0, moving: true }); drawAvatars(view.players, view.visitors);
+- async leaveVisit() | scopes: content:write
+  - Returns: { left }
+  - Stop visiting: the viewer's figure leaves the Minecraft world right away.
+  - Call it when the viewer leaves the world, switches worlds or closes the app; left is false when they were not visiting.
+  - Example: await Twinkle.minecraft.leaveVisit();
 - async createPlayArea({ name, world, box, spawn, id }) | scopes: content:write
   - Returns: { level }
   - Capture a box of a Minecraft world as a new play area (or re-capture an existing id). Runs in the background: poll getPlayArea until status is 'ready'.
@@ -1204,6 +1253,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Zero's build queue: the build he is on, the orders waiting (in the order he will take them) and the campaign steps he works through when no order waits. For an RTS-style build panel and for drawing queued footprints on a map.
   - Everyone can read it; mine marks the viewer's own orders (linked account). Orders always run before campaign steps.
   - noBuildWorlds lists worlds Zero never builds in (World 3, World 4): don't offer placement there.
+  - access.web is true for a website member with no Minecraft account (a visitor): they may ask Zero for builds (the first is reviewed) and their designs are always public.
   - Example: const { active, queue, campaign, access } = await Twinkle.minecraft.getBuildQueue();
 - async moveQueuedBuild({ jobId, to }) | scopes: content:write
   - Returns: same as getBuildQueue

package/sdk/LUMINE_ADMIN.md

@@ -1187,7 +1187,7 @@ lumine admin report serve --file <dir>/daily-management-report.md [--port <n>] [
 
 These compose the documented commands in this contract, running them as child processes, so every scope check, audit and pagination rule applies unchanged.
 - **Arena members waiting for papers come first.** `arena paper-queue --cursor <member-id> --limit <1-100> --json` lists members blocked by the lack of a fresh complete published paper, using the member-facing pass/retry and solo-mastery rules. Follow every `nextCursor`, including after an empty page; require `demandBasis: waiting-published-papers-v1`. Group all pages by exam/difficulty and prioritize these waiting members before generic unseen-question depth. Failed ordinary papers remain retryable; open/pending-marking sittings are not publication waits. Ten successful distinct Full Hard clears, with Zero/Ciel allowed, are needed between solo mastery attempts. The pass and full-marks 20× XP/Coins rewards are separately reserved, each once. Publish complete independently reviewed papers and verify the same members can advance. `gather` collects this queue first as `arena-paper-queue-N.json`, with `paperQueue.complete/pages/waitingTracks`; missing/malformed/partial coverage must not be reported as an empty healthy queue. Use the workspace CLI until npm publication is verified. This step grants no new authoring spend or publication authority.
-- **`gather`** saves its fixed set of read-only reports into `<dir>`, including the canonical published Math Lab queue in `math-lab-queue.json` and all types of pending Build review requests in `build-reviews-N.json`. Build reviews follow `nextCursor` to exhaustion; `gather.json` → `buildReviews` records `complete`, attempted `pages` and collected `items`. A failed/malformed page, cursor loop or 100-page bound reports incomplete coverage, never an empty healthy queue. Read the current collection once; it replaces the rewards-only list. Older packages without `buildReviews` need a separate `review list --status pending` collection through cursor exhaustion. Previous queue receipts remain on disk as history but do not become current evidence or duplicate reading duties after a new gather. It is not the complete daily checklist: app refills/usage, individual review assessments, sponsor integrity and other duties need their own steps. Repository agents follow the current full-run coverage index in `agent-guides/lumine-admin.md`. It follows `bot-output` to exhaustion and renders `bot-chats.txt`, then lists any failed step in `gather.json`. Total/per-step `durationMs`, attempts and recovered reads make recurring slow or failing collection steps visible during the daily review. It also creates `review-state.json`: collection never acknowledges reading. Children bypass update checks, require matching fresh stdout/file receipts, and retry an unconfirmed opted-in read at most once. Mutations never auto-retry. It needs the active run for run-scoped reads.
+- **`gather`** saves its fixed set of read-only reports into `<dir>`, including the canonical published Math Lab queue in `math-lab-queue.json` and all types of pending Build review requests in `build-reviews-N.json`. Build reviews follow `nextCursor` to exhaustion; `gather.json` → `buildReviews` records `complete`, attempted `pages` and collected `items`. A failed/malformed page, cursor loop or 100-page bound reports incomplete coverage, never an empty healthy queue. Read the current collection once; it replaces the rewards-only list. Older packages without `buildReviews` need a separate `review list --status pending` collection through cursor exhaustion. Previous queue receipts remain on disk as history but do not become current evidence or duplicate reading duties after a new gather. It is not the complete daily checklist: app refills/usage, individual review assessments, sponsor integrity and other duties need their own steps. Repository agents follow the current full-run coverage index in `agent-guides/lumine-admin.md`. It follows `bot-output` to exhaustion and renders `bot-chats.txt`, then lists any failed step in `gather.json`. Total/per-step `durationMs`, attempts and recovered reads make recurring slow or failing collection steps visible during the daily review. It also creates `review-state.json`: collection never acknowledges reading. While it runs, `gather.json` is rewritten after every step with `inProgress: true` and the steps so far; the final summary replaces it with `inProgress: false`. An `inProgress: true` file means the collection was interrupted: rerun the same gather with `--resume`. A hang-up from a closing parent shell no longer stops it. Children bypass update checks, require matching fresh stdout/file receipts, and retry an unconfirmed opted-in read at most once. Mutations never auto-retry. It needs the active run for run-scoped reads.
 - **`progress`** reads local review state and explicit operator acknowledgments, writes private `progress.json`, and keeps reading, canonical effort mutations, the run lease, and browser checks separate. `collectionFailures` includes failures without a page file, such as a cursor loop; acknowledging the available files cannot make an incomplete collection complete. A fresh successful gather clears those failures. Add all required duties for the actual run scope and its carryovers; collection alone is not a full review. A completed run lease cannot complete a pending duty. Reading acknowledgments bind to the current file bytes and are operator attestations, not proof of comprehension.
 - **`featured candidates`** returns Subjects posted after the Bangkok-midnight cutoff that are off the board and provably never Featured. Each one comes with its human/bot comment counts, explicit comment truncation/completeness, and whether Mikey has viewed it. Counts from truncated context are partial. An unavailable Subject context fails the collection. Eligibility only: ranking stays editorial.
 - **`report serve`** detaches a loopback server that answers only `/`, `marked.min.js` and the report Markdown. `--open` opens Chrome and reports whether the OS accepted the request. Render, navigation and original-source verification remain pending until actually checked. Startup failures stop only the child this command started.
@@ -2257,6 +2257,11 @@ lumine admin builds review build:884 --output-dir ./build-review \
   --interact ./build-review/steps.json --json
 ```
 
+A secret Subject's effort can't be set until its secret is revealed
+(`CLI_ADMIN_SECRET_REVEAL_REQUIRED`). `subjects candidates` marks such rows
+with `needsReveal: true` and the exact `revealCommand`
+(`lumine admin subject reveal <id>`); run it before `subject effort set`.
+
 Schemas:
 
 ```ts
@@ -3241,6 +3246,13 @@ lumine admin news submit --claim claim.json --file editorial.json \
 lumine admin news print --json
 ```
 
+When there is nothing to claim (today's paper is already printed, or the next
+edition has not opened yet), `news claim` writes no claim or scaffold file and
+leaves any existing `--output` file untouched. Its JSON carries
+`data.artifacts.notClaimed` with `nextEditionAt` (Unix seconds and ISO); the
+text output says when the next edition opens. The daily edition opens at 00:00
+UTC (09:00 KST).
+
 The Twinkle Newspaper (Build app 1929) is normally printed by a community
 member spending their own AI Energy. Making sure today's paper exists is part
 of every delegated website-management run: check `lumine admin news` early in
@@ -4008,6 +4020,9 @@ lumine admin jev-images switch --area all --mode off  # owner kill switch, no de
 lumine admin jev-images switch --area arena_picture --mode on --daily-cap 100
 lumine admin jev-images decide --area arena_picture --key arenaItem:10176 --decision keep|fix|retired
 lumine admin arena picture-audit [--items <id,...> | --cursor <id>] [--limit 1-20] [--renders <dir>] --output <review-list.json> --json
+lumine admin jev-images thumbnails --targets subject:<id>,build:<id>,... | --featured [--saved-only] --json
+lumine admin jev-images decide --area thumbnail --key subject:37265 --decision keep|replace
+lumine admin jev-images switch --area sdk_decide --build <id> --mode on|off   # one app's image decisions (no per-app cap)
 ```
 
 JEV image checks (Mikey, November 1) send pictures to JEV (`jev-1.13.0`,
@@ -4015,8 +4030,11 @@ pinned) with the `TypeSafe-Danger-Zone-Images` opt-in. The vendor marks images
 experimental. **Every answer is advisory:** never the only gate, never a
 child-safety decision and never a reason to pay or withhold a reward (standing
 ruling 11-01). Areas: `arena_paper` (paper-upload pre-screen notes in
-`approvals show`), `arena_picture` (picture-bank audit). `study_record`,
-`thumbnail` and `sdk_decide` are reserved for later steps and stay off.
+`approvals show`), `arena_picture` (picture-bank audit), `thumbnail` (Featured
+thumbnail notes, on by default, cap 2000/day) and `sdk_decide`
+(`Twinkle.ai.decide` with images, a preview, **off** until Mikey turns it on).
+`study_record` has no caller: study-record-v1 records are text only, so there
+are no photos to check, and the area stays off.
 
 Each check carries a small coloured square and asks its colour. A wrong or
 unsure colour, or an answer from a different model, means the pictures were
@@ -4066,6 +4084,37 @@ each `review` item yourself. Record `keep`, `fix` or `retired` with
 `jev-images decide`. Retiring an item through `arena status` records `retired`
 automatically. Fixing or retiring live items needs the usual authorization.
 
+**Featured thumbnails.** `featured candidates` adds a `thumbnailCheck` to each
+eligible candidate and a `thumbnailChecks` summary; `jev-images thumbnails
+--featured` does the same for the current board. Each card's picture (the post's
+own picture, or the cover of the app it is about) gets notes: blank, error or
+loading screen, placeholder, mostly empty at card size, garbled or interface
+text, a watermark, and for an app whether it shows the app. Only
+Twinkle-hosted pictures are read; link previews and videos say
+`external_thumbnail`, and a secret attachment is never looked at. Answers are
+saved per picture, so a re-run makes no new call. The notes are never a ranking
+or eligibility input and nothing is replaced or unfeatured because of them.
+When you look at a flagged picture, record `keep` or `replace` with
+`jev-images decide --area thumbnail --key subject:<id>` (or `build:<id>`).
+Pilot (11-01, app covers only): 43/45 on a held-out set, every good cover
+passed, 2 of 4 bad ones caught. A pass does not mean the picture is fine.
+
+**Image decisions in apps (preview).** `Twinkle.ai.decide({ state, questions,
+images })` lets an app ask about up to four pictures (its own uploads or a
+canvas). Pictures are bounded: an upload at most 5 MB, a snapshot at most 3 MB
+(5 MB of snapshots), and 10 MB for all pictures of one decision; a larger call
+is refused with a plain "Image too large" message before it is fully read. It
+is free for viewers like text decisions. There are no per-app or
+per-viewer daily caps (a decision costs a fraction of a cent); the area's daily
+cap and the cost alarm in the daily report are the spending guard. Bursts are
+limited instead: one image decision in flight per viewer, eight per app, and
+600 a minute per app (per API instance, so up to about twice that across the
+cluster; a class of 30 deciding every ~20 s is about 90 a minute). A throttled call is refused at once as `ai_decision_unavailable` with
+reason `rate_limited`. It never falls back to a text-only answer: when off,
+throttled or failing it returns `ai_decision_unavailable` with a reason.
+`switch --area sdk_decide --build <id> --mode off` switches one app off (or
+`on` to undo it). The report shows its use under `sdk_decide`.
+
 ### Spending by calendar month
 
 ```bash