@stage5/lumine 0.3.77 → 0.3.78

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
@@ -463,6 +464,25 @@ export async function dailyRunGather(options, { run = runAdmin, now, clock } = {
 
 // 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 +548,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 +559,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/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",
@@ -2725,6 +2728,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) : "",
@@ -3400,7 +3406,7 @@ export function printHelp() {
   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 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.78",
   "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.77.0
 Updated: 2026-11-01
-Generated: 2026-11-01T11:22:03.891Z
+Generated: 2026-11-01T12:15:43.879Z
 
 ## 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

package/sdk/LUMINE_ADMIN.md

@@ -4008,6 +4008,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 +4018,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 +4072,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