@stage5/lumine 0.2.69 → 0.2.70

package/lib/commands.js

@@ -2403,6 +2403,10 @@ export function parseArgs(args) {
     adminDecision: raw.decision ? String(raw.decision) : "",
     adminWaitMs: raw.waitMs ? String(raw.waitMs) : "",
     adminBrowserPath: raw.browserPath ? String(raw.browserPath) : "",
+    adminInteract: raw.interact ? String(raw.interact) : "",
+    adminDecisionsTemplate: raw.decisionsTemplate
+      ? String(raw.decisionsTemplate)
+      : "",
     adminEffort: raw.effort ? String(raw.effort) : "",
     agentEffort: command === "agent" && raw.effort ? String(raw.effort) : "",
     sponsorArgs: command === "sponsor" ? positional : [],
@@ -2831,12 +2835,12 @@ export function printHelp() {
   lumine sdk call <namespace.method> [jsonArgs]
   lumine assets [list]
   lumine assets upload <file...>
-  lumine assets generate "<prompt>" --model <gpt-image-2|nano-banana>
+  lumine assets generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>
   lumine assets delete <assetId>
   lumine assets prune [--yes]
   lumine thumbnail set <file>
   lumine thumbnail capture [--out <file>]
-  lumine thumbnail generate ["<prompt>"] --model <gpt-image-2|nano-banana>
+  lumine thumbnail generate ["<prompt>"] --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>
   lumine doctor runtime-assets
   lumine admin identity list|status|use <zero|ciel|auto> [--json]
   lumine admin identity inspect <user-id|username> --reason <management-reason> [--include-private-evidence] [--json]
@@ -2865,7 +2869,7 @@ export function printHelp() {
   lumine admin sponsor integrity review <case-id> --decision clear|hold|flag|disqualify [--note <evidence>] [--json]
   lumine admin recommendations list [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin builds candidates [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--limit <number>] [--json]
-  lumine admin builds review <build-url-or-id> [--output-dir <dir>] [--wait-ms <ms>] [--browser-path <path>] [--json]
+  lumine admin builds review <build-url-or-id> [--output-dir <dir>] [--wait-ms <ms>] [--interact <steps.json>] [--browser-path <path>] [--json]
   lumine admin subjects candidates [--since-run|--after <date>|--include-legacy] [--effort unassigned] [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
   lumine admin subject get|reveal <subject-url-or-id> [--json]
   lumine admin subject comments <subject-url-or-id> [--unviewed|--viewed] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--json]
@@ -2880,7 +2884,7 @@ export function printHelp() {
   lumine admin featured plan --remove-subject-ids <ids> --add-subject-ids <ids> [--subject-ids <final-order>] --posted-after <timestamp> --output <plan.json> [--json]
   lumine admin featured apply --file <plan.json> --approve <exact-plan-hash> [--json]
   lumine admin featured comments scan --checkpoint <file> [--resume] [--json]
-  lumine admin featured comments acknowledge --checkpoint <scan-file> --reviewed [--json]
+  lumine admin featured comments acknowledge --checkpoint <scan-file> --reviewed [--decisions-template <file>] [--json]
   lumine admin featured comments recommend --file <decisions.json> --checkpoint <batch-file> [--resume] [--json]
   lumine admin featured comments report --checkpoint <scan-file> [--json]
   lumine admin post get <target> [--type subject|comment|aiStory|dailyReflection] [--json]
@@ -3006,6 +3010,8 @@ Options:
   --severity <level>    Run escalation severity: attention or urgent
   --status <state>      Private escalation or todo lifecycle filter/state
   --wait-ms <ms>        Managed Build observation or sponsor watch duration
+  --interact <file>     Managed Build review: bounded JSON step script (click/type/press/wait/screenshot) run inside the app frame after the start screenshot
+  --decisions-template <file>  Featured acknowledge: write a ready {reviewId, coverageId, selections: []} decisions file
   --browser-path <path> Chrome/Chromium executable for managed Build review
   --effort unassigned  Admin subjects: show only unassigned effort
   --unviewed           Admin content lists: retain unviewed and unknown items
@@ -3048,8 +3054,8 @@ Options:
   --json                Print machine-readable output where supported
   --keep-assets         Keep doctor probe assets instead of deleting them
   --no-browser          Skip doctor browser probes
-  --model <model>       Image model for generate: gpt-image-2 or nano-banana (required, no default)
-  --quality <q>         gpt-image-2 quality: low, medium, high (default high)
+  --model <model>       Image model for generate: gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2, or nano-banana (required)
+  --quality <q>         GPT Image quality: low, medium, high, xhigh, max (default high; xhigh/max require 2.5)
   --name <fileName>     File name hint for a generated asset
   --out <path>          With thumbnail capture: also save the capture locally
   --yes                 Skip confirmation prompts (assets prune/generate, thumbnail)

package/lib/constants.js

@@ -16,11 +16,15 @@ export const DEFAULT_TIMEOUT_MS = 20000;
 export const ASSET_GENERATE_TIMEOUT_MS = 6 * 60 * 1000;
 export const THUMBNAIL_CAPTURE_TIMEOUT_MS = 90 * 1000;
 export const GENERATE_MODEL_ALIASES = {
+  "gpt-image-2.5-flare": "gpt-image-2.5-flare",
+  "gpt-image-2.5-sunburst": "gpt-image-2.5-sunburst",
+  "flare": "gpt-image-2.5-flare",
+  "sunburst": "gpt-image-2.5-sunburst",
   "gpt-image-2": "gpt-image-2",
   "nano-banana": "gemini-3-pro-image-preview",
   "gemini-3-pro-image-preview": "gemini-3-pro-image-preview",
 };
-export const GENERATE_QUALITIES = new Set(["low", "medium", "high"]);
+export const GENERATE_QUALITIES = new Set(["low", "medium", "high", "xhigh", "max"]);
 // Server accepts only these thumbnail content types (8MB max).
 export const THUMBNAIL_CONTENT_TYPE_BY_EXTENSION = {
   ".jpg": "image/jpeg",

package/lib/sdk.js

@@ -2,7 +2,7 @@ import path from "path";
 
 import { ensureAuth, assertAuthScope } from "./auth.js";
 import { mintBuildApiToken } from "./api.js";
-import { requestText } from "./http.js";
+import { requestJson, requestText } from "./http.js";
 import { parseJson, resolveBuildId } from "./util.js";
 import { findLocalProjectMetadata } from "./workspace.js";
 
@@ -152,6 +152,37 @@ export const SDK_CLI_METHODS = {
   "notifications.getSubjectUpdateSubscription": { path: "api/notifications/subject-update-subscription", scopes: ["notifications:read"] },
   "notifications.subscribeToSubjectUpdates": { path: "api/notifications/subject-update-subscription/subscribe", scopes: ["notifications:write"], write: true },
   "notifications.unsubscribeFromSubjectUpdates": { path: "api/notifications/subject-update-subscription/unsubscribe", scopes: ["notifications:write"], write: true },
+  // Rewards go through the same server-verified endpoint the published app
+  // runtime uses: POST api/rewards/<operation> with the rewards:claim build
+  // token PLUS the server-issued published-runtime grant (fetched from the
+  // canonical GET /build/:id/runtime payload, never minted locally). The CLI
+  // holds no award logic; the server checks approval, version and budget.
+  // getStatus is read-only: the endpoint only accepts rewards:claim, so that
+  // scope is minted for it, but only the status operation is ever sent.
+  "rewards.getStatus": {
+    path: "api/rewards/status",
+    special: "rewards",
+    operation: "status",
+    scopes: ["rewards:claim"],
+    readOnly: true,
+    mapArgs: () => ({}),
+  },
+  "rewards.start": {
+    path: "api/rewards/start",
+    special: "rewards",
+    operation: "start",
+    scopes: ["rewards:claim"],
+    write: true,
+    mapArgs: (args) => ({ ruleId: args.ruleId }),
+  },
+  "rewards.claim": {
+    path: "api/rewards/claim",
+    special: "rewards",
+    operation: "claim",
+    scopes: ["rewards:claim"],
+    write: true,
+    mapArgs: (args) => ({ challengeId: args.challengeId, answers: args.answers }),
+  },
   // Leaderboards use the public leaderboard routes (regular login auth, no
   // build API token). args.boardKey selects the board; remaining args are
   // query params (get) or the POST body (submit).
@@ -221,7 +252,9 @@ export const SDK_CLI_READ_SCOPES = [
 ];
 
 export function isWriteCapableScope(scope) {
-  return /:(write|emit)$/.test(String(scope));
+  // rewards:claim is the only rewards scope and it can award XP/Coins, so a
+  // --scopes override naming it is write-capable like any :write scope.
+  return /:(write|emit|claim)$/.test(String(scope));
 }
 
 export async function sdkCommand(options) {
@@ -352,7 +385,13 @@ export async function sdkCall(options) {
   const requestedScopes = options.sdkScopes.length
     ? options.sdkScopes
     : endpoint.scopes || [];
-  const writeScopes = requestedScopes.filter(isWriteCapableScope);
+  // A curated readOnly method (rewards.getStatus) needs a scope whose name is
+  // write-capable but only ever sends its read operation; its own default
+  // scopes do not trip the gate. Explicit --scopes overrides always do.
+  const writeScopes =
+    endpoint.readOnly && !options.sdkScopes.length
+      ? []
+      : requestedScopes.filter(isWriteCapableScope);
   // writeWhen covers endpoints that mutate under a read scope depending on
   // their args (e.g. reminders.getDue acknowledging due reminders).
   const writeByArgs =
@@ -410,6 +449,39 @@ export async function sdkCall(options) {
       attempts.push(lastResult);
       printSdkAttemptLine(attempts.length, lastResult);
     }
+  } else if (endpoint.special === "rewards") {
+    const scopes = requestedScopes.length ? requestedScopes : endpoint.scopes;
+    const grant = await loadRewardRuntimeGrant({
+      options,
+      auth,
+      buildId,
+      methodName,
+    });
+    const tokenResult = await mintBuildApiToken({
+      options,
+      auth,
+      buildId,
+      scopes,
+    });
+    console.error(
+      `token minted in ${tokenResult.ms}ms (scopes: ${
+        tokenResult.scopes.join(", ") || "default"
+      }); published-runtime reward grant loaded from the server`,
+    );
+    const body = endpoint.mapArgs ? endpoint.mapArgs(args) : args;
+    for (let attempt = 0; attempt < options.repeat; attempt += 1) {
+      lastResult = await executeSdkHttpCall({
+        options,
+        method: "POST",
+        url: `${options.apiUrl}/build/${buildId}/api/rewards/${endpoint.operation}`,
+        authToken: auth.token,
+        body,
+        buildApiToken: tokenResult.token,
+        headers: { "x-build-reward-runtime": grant },
+      });
+      attempts.push(lastResult);
+      printSdkAttemptLine(attempts.length, lastResult);
+    }
   } else if (
     endpoint.special === "userDbQuery" ||
     endpoint.special === "userDbExec"
@@ -492,6 +564,34 @@ export function printSdkAttemptLine(attemptNumber, result) {
   );
 }
 
+// The published-runtime reward grant is a server-issued, short-lived JWT that
+// the canonical runtime payload carries only for the current approved
+// published release. Reading it from that payload keeps every rewards call on
+// the same verified path the app itself uses; the CLI never fabricates one.
+export async function loadRewardRuntimeGrant({
+  options,
+  auth,
+  buildId,
+  methodName,
+  request = requestJson,
+}) {
+  const payload = await request({
+    url: `${options.apiUrl}/build/${buildId}/runtime?runtimeSource=published`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+  const grant = payload?.build?.rewardRuntimeGrant;
+  if (typeof grant !== "string" || !grant) {
+    throw new Error(
+      `${methodName}: the server issued no published-runtime reward grant for build ${buildId}. ` +
+        "Rewards exist only for the current approved public release (drafts, " +
+        "private apps and unapproved releases return preview mode in the app), " +
+        "and the grant is issued to the signed-in account. Nothing was called.",
+    );
+  }
+  return grant;
+}
+
 export async function executeSdkHttpCall({
   options,
   method,
@@ -499,6 +599,7 @@ export async function executeSdkHttpCall({
   authToken,
   body,
   buildApiToken,
+  headers = {},
 }) {
   const startedAt = Date.now();
   const { response, text } = await requestText({
@@ -507,7 +608,10 @@ export async function executeSdkHttpCall({
     authToken,
     body,
     timeoutMs: options.timeoutMs,
-    headers: buildApiToken ? { "x-build-api-token": buildApiToken } : {},
+    headers: {
+      ...(buildApiToken ? { "x-build-api-token": buildApiToken } : {}),
+      ...headers,
+    },
   });
   return {
     ok: response.ok,

package/lib/thumbnail.js

@@ -42,7 +42,7 @@ export async function thumbnailCommand(options) {
     return;
   }
   throw new Error(
-    'Usage: lumine thumbnail set <file> | lumine thumbnail capture [--out <file>] | lumine thumbnail generate "<prompt>" --model <gpt-image-2|nano-banana>',
+    'Usage: lumine thumbnail set <file> | lumine thumbnail capture [--out <file>] | lumine thumbnail generate "<prompt>" --model <gpt-image-2.5-flare|gpt-image-2.5-sunburst|gpt-image-2|nano-banana>',
   );
 }
 
@@ -276,7 +276,7 @@ export async function thumbnailGenerate(options) {
     }
     if (selectedOption) {
       console.log(
-        `  Estimated battery cost: ${formatBatteryPercent(selectedOption.energyUnits, estimate?.fullBatteryUnits)} of a full AI battery (~$${Number(selectedOption.estimatedUsd || 0).toFixed(2)})`,
+        `  Estimated image output: ${formatBatteryPercent(selectedOption.energyUnits, estimate?.fullBatteryUnits)} of a full AI battery (~$${Number(selectedOption.estimatedUsd || 0).toFixed(2)}). Prompt input uses additional energy.`,
       );
     }
     if (estimate) {

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -2,7 +2,7 @@
 
 Version: 1.41.0
 Updated: 2026-09-08
-Generated: 2026-09-08T05:12:06.333Z
+Generated: 2026-09-09T02:13:12.499Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -488,8 +488,8 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Listen to shared runtime AI chat stream events.
   - Usually prefer per-call onText/onStatus callbacks on Twinkle.ai.chat.
   - Events include requestId plus type status, text, done, or error.
-- async generateImage({ prompt, referenceImageB64, previousResponseId, previousImageId, engine, quality, requestId, onStatus, timeoutMs } = {}) | scopes: none
-  - Returns: { success, imageUrl, responseId, imageId, engine, quality, aiUsagePolicy } or { success: false, error, reason, code, aiUsagePolicy }
+- async generateImage({ prompt, referenceImageB64, previousResponseId, previousImageId, engine, model, quality, requestId, onStatus, timeoutMs } = {}) | scopes: none
+  - Returns: { success, imageUrl, responseId, imageId, engine, model, quality, aiUsagePolicy } or { success: false, error, reason, code, aiUsagePolicy }
   - Generate or edit an image from a prompt and optional base64/data-URL reference image.
   - Signed-in viewers only.
   - Each successful image generation consumes AI Energy from the signed-in viewer.
@@ -502,6 +502,10 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Pass requestId when you need to correlate browser logs, backend logs, and iframe status events for one generation.
   - partial_image statuses may include partialImageB64 for progressive preview UI before the final imageUrl arrives.
   - referenceImageB64 may be a raw base64 string or a data:image/...;base64 URL.
+  - Optional model: gpt-image-2.5-flare or gpt-image-2.5-sunburst. Without a model, OpenAI uses Flare for new images and Sunburst when a reference image or continuation is supplied. Explicit gpt-image-2 remains supported.
+  - Quality accepts low, medium, high, xhigh, or max. xhigh and max require a GPT Image 2.5 model. Gemini has one quality tier.
+  - GPT Image 2.5 battery spending uses actual image-model input and output token usage. The confirmation shows an image-output estimate; prompts and reference images use additional energy.
+  - responseId and imageId are opaque continuation handles. Pass them back unchanged to edit a prior result; do not assume an OpenAI ID format. Existing GPT Image 2 continuations remain usable.
   - Example: const result = await Twinkle.ai.generateImage({ prompt: 'Create a fashion guide portrait for this face with flattering colors and outfit ideas', referenceImageB64, quality: 'high', onStatus: (status) => console.log(status.stage) });
 - onImageGenerationStatus(listener) | scopes: none
   - Returns: unsubscribe function

package/sdk/LUMINE_ADMIN.md

@@ -912,6 +912,27 @@ type DailyRunComplete = Success<{
   rotationAdvanced: false; // legacy field; calendar schedules never advance by run
 }>;
 type DailyRunFail = DailyRunComplete;
+// `escalation add` echoes the same open-item shape `escalation list` returns,
+// so the run.escalation audit ID that `escalation set <auditId>` needs is in
+// the add response; no list round-trip is required. `recordedAt` (the audit
+// row's timestamp) appears only in `list`.
+type DailyRunEscalationAdd = Success<{
+  escalation: {
+    auditId: number; // run.escalation audit event ID = escalation identity
+    runId: number;
+    targetType: string | null;
+    targetId: number | null;
+    url: string | null;
+    summary: string;
+    severity: "attention" | "urgent";
+    status: "open";
+    decisionNote: null;
+    decisionAuditId: null;
+    decisionRevision: 0;
+    decisionUpdatedAt: null;
+    decisionByUserId: null;
+  };
+}>;
 ```
 
 ### Build Workshop sponsor applications and integrity
@@ -1169,6 +1190,8 @@ lumine admin subjects candidates --effort unassigned --json
 lumine admin subjects candidates --unviewed --json
 lumine admin builds candidates --all --limit 50 --json
 lumine admin builds review build:884 --output-dir ./build-review --json
+lumine admin builds review build:884 --output-dir ./build-review \
+  --interact ./build-review/steps.json --json
 ```
 
 Schemas:
@@ -1294,6 +1317,17 @@ All-history traversal is deliberately available only through
 boundary for bounded modes, so deploying a new CLI against an older API cannot
 silently fall back to a million-row historical scan.
 
+`recommendations list` is the Earn Recommend picker, not a "new comments"
+feed: it returns only comments on subjects with an assigned effort level,
+whose length exceeds that level's threshold (>100 / >250 / >450 / >700
+characters for effort ≤2 / 3 / 4 / 5), with no skip row and no existing
+recommendation from any effective Level 5+ user (1000+ AP or Teacher
+authority), Zero, or Ciel. Community-recommended and short comments are
+deliberately absent, so an empty page or an empty window is normal and is
+not evidence of a broken walk; Featured-subject comments are reviewed through
+the Featured comment scan instead. A successful `post recommend` does not
+imply the target was queue-eligible.
+
 After upgrading the API and CLI to the stable run-start window, start a fresh
 `--since-run` scan with a new checkpoint path, without `--resume`. Older
 since-run checkpoints are rejected even when already exhausted: they may have
@@ -1342,6 +1376,53 @@ learned during that review. The receipt binds the draft to the exact reviewed
 artifact without copying a version number by hand; the server owns the Build,
 version, method, and review-time fields around that understanding.
 
+Without `--interact` the review captures only the start screen after
+`--wait-ms`. `--interact <steps.json>` adds a bounded, ordered interaction
+script that runs inside the app's runtime iframe after that start screenshot,
+so the receipt can show what happens when the app is actually used. The file is
+a JSON array (or `{ "steps": [...] }`) of at most **12** steps, each exactly one
+of:
+
+```json
+[
+  { "click": "text=Start" },
+  { "wait": 1500 },
+  { "screenshot": "after-start" },
+  { "type": { "selector": "input[name=name]", "text": "Zero" } },
+  { "press": "Enter" },
+  { "press": "ArrowLeft" },
+  { "screenshot": "moved" }
+]
+```
+
+- `click`: a CSS selector, or `text=<visible text>` (case-insensitive; the
+  smallest visible element whose text matches, then a bounded contains match).
+  Dispatched as a trusted mouse click at the element's centre, so canvas games
+  and buttons both receive it.
+- `type`: `{ selector, text }` — clicks the element, then inserts single-line
+  text (at most 200 characters) as trusted input.
+- `press`: `Enter`, `Space`, `Escape`, `Tab`, `Backspace`, `ArrowUp/Down/Left/Right`,
+  a letter, or a digit. The frame is focused first if nothing was clicked yet.
+- `wait`: 1–5000 ms.
+- `screenshot`: a unique label (1–40 letters/digits/`-`/`_`, not `runtime` or
+  `review`); saved as `<label>.png` beside `runtime.png`.
+
+The whole script is capped at **60 s**; it stops at the first failed step
+(element not found/not visible, budget exhausted, frame unreachable). Console
+evidence stays bounded exactly as before. `review.json` gains
+`screenshots: [{ label, path, bytes }]` (script screenshots only; the start
+screen stays in `screenshot`) and
+`interaction: { path, stepsPlanned, stepsCompleted, status, failedStep, frame,
+elapsedMs, steps }` with a per-step record (coordinates for clicks, the saved
+path for screenshots, the error for a failed step). Both are `[]`/`null`
+without `--interact`. The review remains one receipt bound to one artifact: the
+published version is re-read after the script finishes, and a script that did
+not complete makes the receipt `failed` with
+`CLI_ADMIN_BUILD_REVIEW_INTERACTION_FAILED` (the completed steps and their
+screenshots are still listed) so a draft can never cite interactions that did
+not happen. `comment draft --review-receipt` accepts a receipt only when every
+listed screenshot still exists unchanged and the script completed.
+
 During every full daily management review, scan recent Build candidates back through the
 run's review window alongside Subjects and the recommendation queue. An app
 that is thin, broken, private, unchanged since a prior substantive bot
@@ -1736,7 +1817,8 @@ lumine admin featured comments scan --checkpoint featured-read.json --json
 # On interruption: repeat with --resume, in the same active run.
 # Read ALL pageFiles, including full root context and nested replies.
 lumine admin featured comments acknowledge \
-  --checkpoint featured-read.json --reviewed --json
+  --checkpoint featured-read.json --reviewed \
+  --decisions-template featured-decisions.json --json
 ```
 
 The scan snapshots every current Featured Subject (up to 100) and its maximum
@@ -1757,6 +1839,26 @@ missing Subject IDs and comment counts, and distinguishes complete from partial
 coverage. A download alone never counts as a read or grants recommendations.
 After a resumed scan fills a gap, read those pages and acknowledge again.
 
+Acknowledge returns `data.reviewedCoverage` (the coverage receipt; its `id` is
+the `coverageId` the recommend step needs — it is a different audit row from
+the review ID) and a ready-to-fill `data.decisionsTemplate`
+`{ reviewId, coverageId, selections: [] }`. With `--decisions-template <file>`
+the CLI also writes that template as a private mode-0600 file; only
+`acknowledge --reviewed` writes it (a scan rejects the flag). Start the
+decisions file from the template rather than assembling the identifiers by
+hand. `readFeaturedSelections` refuses a file whose `coverageId` equals its
+`reviewId` before any request is sent, and the API answers a wrong receipt
+with `CLI_ADMIN_FEATURED_COVERAGE_MISMATCH` naming the expected receipt, e.g.
+`coverageId 5719 is not the acknowledged coverage receipt for review 5719
+(expected 5749; 5719 is the review ID itself).` with
+`details: { reviewId, suppliedCoverageId, expectedCoverageId,
+suppliedReceiptAction, suppliedCoverageReviewId }`, or
+`CLI_ADMIN_FEATURED_COVERAGE_MISSING` when the review has no acknowledged
+coverage in this run. Other receipt failures (a page ID from another run,
+operator, or actor) keep the generic
+`Receipt #<id> is not a completed <action> receipt of this active run,
+operator and actor.` rejection.
+
 Compose a decisions JSON file from the genuinely reviewed comments, using the
 returned review ID, coverage receipt ID, and each selected comment's page ID:
 
@@ -2232,7 +2334,9 @@ streak — "I'm telling you: Stop", guilt framing, ordering him to quit Daily
 Reflections — and it surfaced only because the kid showed Mikey).
 
 `bot-output` returns, windowed since the operator's last completed full run
-(`--days 1..30` overrides): `chatMessages` (every stored Zero/Ciel chat and
+(`--days 1..30` overrides; the bare form sends no `days` parameter at all, so
+the API applies that default window — an older CLI wrongly validated the empty
+default and failed with "--days must be an integer"): `chatMessages` (every stored Zero/Ciel chat and
 reflection reply, with full text and recipient metadata when its best-effort
 prompt audit exists) and `comments`
 (every public bot comment/reply). Individual utterances are returned in full;
@@ -2399,7 +2503,16 @@ checking, and in-place truncation occur on the same open descriptor. It then
 returns `post_clear_review_required` with another immutable snapshot. That
 snapshot also captures normal-output bytes that arrived after the prior
 acknowledged cutoff, so routine stdout traffic cannot make the review infinite.
-Read it and run the same `finish --reviewed` command again. A review clears
+Read it and run the same `finish --reviewed` command again. **Only
+`data.completionStatus: "completed"` means the review is done.** The top-level
+`status` mirrors it: `"needs_review"` for both non-terminal outcomes
+(`needs_review` and `post_clear_review_required`, including a recovered
+pending snapshot), `"success"` only when `completed`, and `"already_done"` for
+a replay of an already-finished review. `ok` stays `true` in every case; a
+`needs_review` result is a valid response that requires another read plus
+finish, not an error. The CLI derives the top-level status from
+`completionStatus`, so it is correct against an API that still answers the
+older `success` envelope. A review clears
 `twinkle-api.err.log` at most once. The lease closes when the reviewed error
 boundary is still stable, i.e. every byte now in the API error log arrived
 after that clear and was captured and acknowledged; errors that arrive before
@@ -3003,12 +3116,19 @@ farm-signal sections added that day; AI Card summon watch added 2026-08-24):
   is never called a dodge. Offers without redemptions are a reason to inspect
   sample size, event type, and offer age — not proof of a broken funnel by
   themselves.
-- `goneQuiet` — the inverse of `notableCandidates`: users whose `lastActive`
-  fell in the 14 days before the window (so they were around, then stopped),
-  ranked by how regular they were in the prior 30 days (daily tasks and
-  Wordle), capped at 15 with `daysQuiet`. Use it for product signal (what did
-  they stop doing?) and gentle outreach candidates; never guilt a child in
-  public about absence.
+- `goneQuiet` — the inverse of `notableCandidates`, and window-relative: a
+  user "went quiet" the moment 7 days of silence passed since their
+  `lastActive`, and the section lists only the users whose quiet moment fell
+  inside the brief's window (`lastActive` between `sinceTs - 7d` and
+  `now - 7d`). A one-day brief therefore reports one day of crossings and
+  contiguous daily runs list each user once; it never re-lists everyone seen
+  in the past fortnight. `totals.wentQuiet` is that cohort; `previouslyRegular`
+  is the subset with at least 7 distinct active days (completed daily tasks or
+  Wordle plays) in the 30 days ending on their own last active day, and
+  `users` is that subset ranked by `regularityScore` (`dailyTasks * 2 +
+  wordlePlays`, both measured over the same per-user span), capped at 15 with
+  `daysQuiet`. Use it for product signal (what did they stop doing?) and
+  gentle outreach candidates; never guilt a child in public about absence.
 - `newUserFunnel` — signups in the window with `activeOnDayOne` (any
   XP-ledger event within 24h of joining) and `returnedAfterDayOne`
   (`lastActive` beyond their first day), plus the newest few accounts.