@stage5/lumine 0.2.39 → 0.2.41

package/lib/forum.js

@@ -0,0 +1,375 @@
+import { requestJson } from "./http.js";
+import { sleep } from "./util.js";
+
+const FORUM_SCOPE_MODES = new Set(["all", "branch", "main"]);
+const FORUM_EVENT_TYPES = new Set(["thread", "reply"]);
+const MAX_FORUM_SNAPSHOT_PAGES = 100_000;
+
+function forumProtocolError(message) {
+  const error = new Error(`Invalid Forum response: ${message}`);
+  error.code = "lumine_forum_protocol_error";
+  error.retryable = false;
+  return error;
+}
+
+function normalizeForumSequence(value, label) {
+  const sequence = Number(value);
+  if (!Number.isSafeInteger(sequence) || sequence < 0) {
+    throw forumProtocolError(`${label} must be a non-negative safe integer`);
+  }
+  return sequence;
+}
+
+function normalizePositiveForumId(value, label) {
+  const id = Number(value);
+  if (!Number.isSafeInteger(id) || id <= 0) {
+    throw forumProtocolError(`${label} must be a positive safe integer`);
+  }
+  return id;
+}
+
+export function buildForumScopeKey(scope) {
+  const mode = String(scope?.mode || "");
+  if (!FORUM_SCOPE_MODES.has(mode)) {
+    throw forumProtocolError("scope.mode is not recognized");
+  }
+  const rootBuildId = normalizePositiveForumId(
+    scope?.rootBuildId,
+    "scope.rootBuildId",
+  );
+  const workspaceBuildId = normalizePositiveForumId(
+    scope?.workspaceBuildId,
+    "scope.workspaceBuildId",
+  );
+  const contributionBuildId = scope?.contributionBuildId
+    ? normalizePositiveForumId(
+        scope.contributionBuildId,
+        "scope.contributionBuildId",
+      )
+    : 0;
+  if (mode === "branch" && contributionBuildId !== workspaceBuildId) {
+    throw forumProtocolError(
+      "branch scope does not match its contribution workspace",
+    );
+  }
+  if (mode !== "branch" && contributionBuildId !== 0) {
+    throw forumProtocolError("non-branch scope has a contribution build");
+  }
+  return `${mode}:${rootBuildId}:${workspaceBuildId}:${contributionBuildId}`;
+}
+
+export async function loadBuildForumPage({
+  options,
+  auth,
+  buildId,
+  afterActivitySeq,
+  snapshotActivitySeq,
+  limit,
+}) {
+  const url = new URL(`${options.apiUrl}/cli/build/${buildId}/forum`);
+  url.searchParams.set("afterActivitySeq", String(afterActivitySeq));
+  if (snapshotActivitySeq > 0) {
+    url.searchParams.set("snapshotActivitySeq", String(snapshotActivitySeq));
+  }
+  url.searchParams.set("limit", String(limit));
+  return await requestJson({
+    url: url.toString(),
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+function validateForumPage({
+  page,
+  buildId,
+  pageCursor,
+  snapshotActivitySeq,
+  expectedScopeKey,
+}) {
+  const projectId = normalizePositiveForumId(page?.project?.id, "project.id");
+  const requestedBuildId = normalizePositiveForumId(
+    page?.requestedBuildId,
+    "requestedBuildId",
+  );
+  if (requestedBuildId !== buildId) {
+    throw forumProtocolError("requestedBuildId changed during the read");
+  }
+  const scopeKey = buildForumScopeKey(page?.scope);
+  if (Number(page?.scope?.rootBuildId) !== projectId) {
+    throw forumProtocolError("project.id does not match scope.rootBuildId");
+  }
+  if (expectedScopeKey && scopeKey !== expectedScopeKey) {
+    throw forumProtocolError(
+      "the authorized Forum workspace changed; restart the listener",
+    );
+  }
+
+  const pageSnapshotActivitySeq = normalizeForumSequence(
+    page?.pagination?.snapshotActivitySeq,
+    "pagination.snapshotActivitySeq",
+  );
+  if (
+    snapshotActivitySeq > 0 &&
+    pageSnapshotActivitySeq !== snapshotActivitySeq
+  ) {
+    throw forumProtocolError("snapshotActivitySeq changed between pages");
+  }
+  if (pageSnapshotActivitySeq < pageCursor) {
+    throw forumProtocolError("snapshotActivitySeq precedes the page cursor");
+  }
+
+  const events = Array.isArray(page?.events) ? page.events : null;
+  if (!events) throw forumProtocolError("events is not an array");
+  const pageLimit = Number(page?.pagination?.limit);
+  if (
+    !Number.isSafeInteger(pageLimit) ||
+    pageLimit < 1 ||
+    pageLimit > 100 ||
+    events.length > pageLimit
+  ) {
+    throw forumProtocolError("pagination.limit does not bound the page");
+  }
+  let lastActivitySeq = pageCursor;
+  for (const event of events) {
+    if (!FORUM_EVENT_TYPES.has(String(event?.type || ""))) {
+      throw forumProtocolError("event.type is not recognized");
+    }
+    normalizePositiveForumId(event?.id, "event.id");
+    normalizePositiveForumId(event?.threadId, "event.threadId");
+    const activitySeq = normalizeForumSequence(
+      event?.activitySeq,
+      "event.activitySeq",
+    );
+    if (
+      activitySeq <= lastActivitySeq ||
+      activitySeq > pageSnapshotActivitySeq
+    ) {
+      throw forumProtocolError(
+        "events are not strictly ordered inside the snapshot",
+      );
+    }
+    lastActivitySeq = activitySeq;
+  }
+
+  if (typeof page?.pagination?.hasMore !== "boolean") {
+    throw forumProtocolError("pagination.hasMore is not boolean");
+  }
+  const nextActivitySeq = normalizeForumSequence(
+    page?.pagination?.nextActivitySeq,
+    "pagination.nextActivitySeq",
+  );
+  if (page.pagination.hasMore) {
+    if (
+      events.length === 0 ||
+      nextActivitySeq !== lastActivitySeq ||
+      nextActivitySeq <= pageCursor ||
+      nextActivitySeq >= pageSnapshotActivitySeq
+    ) {
+      throw forumProtocolError("the next Forum page cursor is not progressive");
+    }
+  } else if (nextActivitySeq !== pageSnapshotActivitySeq) {
+    throw forumProtocolError(
+      "the final Forum page did not confirm the full snapshot cursor",
+    );
+  }
+
+  return {
+    events,
+    nextActivitySeq,
+    pageSnapshotActivitySeq,
+    scopeKey,
+  };
+}
+
+export async function readCompleteBuildForumSnapshot({
+  options,
+  auth,
+  buildId,
+  afterActivitySeq = 0,
+  expectedScopeKey = "",
+  loadPage = loadBuildForumPage,
+  maxPages = MAX_FORUM_SNAPSHOT_PAGES,
+}) {
+  const normalizedBuildId = normalizePositiveForumId(buildId, "buildId");
+  const startingActivitySeq = normalizeForumSequence(
+    afterActivitySeq,
+    "afterActivitySeq",
+  );
+  let pageCursor = startingActivitySeq;
+  let snapshotActivitySeq = 0;
+  let scopeKey = expectedScopeKey;
+  let firstPage = null;
+  const events = [];
+
+  for (let pageNumber = 1; pageNumber <= maxPages; pageNumber += 1) {
+    const page = await loadPage({
+      options,
+      auth,
+      buildId: normalizedBuildId,
+      afterActivitySeq: pageCursor,
+      snapshotActivitySeq,
+      limit: options.limit,
+    });
+    const validated = validateForumPage({
+      page,
+      buildId: normalizedBuildId,
+      pageCursor,
+      snapshotActivitySeq,
+      expectedScopeKey: scopeKey,
+    });
+    if (!firstPage) firstPage = page;
+    if (!scopeKey) scopeKey = validated.scopeKey;
+    snapshotActivitySeq = validated.pageSnapshotActivitySeq;
+    events.push(...validated.events);
+    pageCursor = validated.nextActivitySeq;
+    if (!page.pagination.hasMore) {
+      return {
+        project: firstPage.project,
+        requestedBuildId: normalizedBuildId,
+        scope: firstPage.scope,
+        events,
+        pagination: {
+          fromActivitySeq: startingActivitySeq,
+          snapshotActivitySeq,
+          nextActivitySeq: pageCursor,
+          hasMore: false,
+        },
+        scopeKey,
+      };
+    }
+  }
+
+  throw forumProtocolError("snapshot exceeded the safe pagination bound");
+}
+
+export function isRetryableForumListenerError(error) {
+  if (error?.retryable === false) return false;
+  const status = Number(error?.status || 0);
+  if (!status) return true;
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+function formatForumTimestamp(value) {
+  const timestamp = Number(value || 0);
+  if (!Number.isFinite(timestamp) || timestamp <= 0) return "unknown time";
+  return new Date(timestamp * 1000).toISOString();
+}
+
+function formatForumLocation(event) {
+  if (!event?.branch) return "Main";
+  const branchNumber = Number(event.branch.number || 0);
+  return branchNumber > 0
+    ? `Branch #${branchNumber}`
+    : `Branch build #${event.branch.id}`;
+}
+
+function sanitizeForumTerminalText(value) {
+  // Forum text is user-authored. Preserve canonical content in JSON output,
+  // but prevent control, escape, carriage-return, and bidi override bytes from
+  // driving or visually rewriting a human reader's terminal.
+  return String(value || "").replace(
+    /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g,
+    "",
+  );
+}
+
+function printIndented(value) {
+  for (const line of sanitizeForumTerminalText(value).split("\n")) {
+    console.log(`    ${line}`);
+  }
+}
+
+export function printBuildForumSnapshot(snapshot, { json, kind }) {
+  const output = {
+    type: kind,
+    project: snapshot.project,
+    requestedBuildId: snapshot.requestedBuildId,
+    scope: snapshot.scope,
+    events: snapshot.events,
+    cursor: {
+      fromActivitySeq: snapshot.pagination.fromActivitySeq,
+      throughActivitySeq: snapshot.pagination.nextActivitySeq,
+    },
+  };
+  if (json) {
+    console.log(JSON.stringify(output));
+    return;
+  }
+
+  const projectTitle =
+    sanitizeForumTerminalText(snapshot.project?.title).trim() ||
+    `Build #${snapshot.project?.id || snapshot.requestedBuildId}`;
+  console.log(`${projectTitle} — Team Forum`);
+  if (snapshot.events.length === 0) {
+    console.log("No new visible Forum posts or replies.");
+    return;
+  }
+  for (const event of snapshot.events) {
+    const author =
+      sanitizeForumTerminalText(event?.author?.username).trim() ||
+      (event?.author?.role === "lumine" ? "Lumine" : "unknown user");
+    const action = event.type === "reply" ? "replied in" : "opened";
+    console.log(
+      `${formatForumTimestamp(event.createdAt)}  ${formatForumLocation(event)}  ${author} ${action} #${event.threadId} “${sanitizeForumTerminalText(event.threadTitle)}”`,
+    );
+    if (event.replyTo) {
+      const target =
+        sanitizeForumTerminalText(event.replyTo.username).trim() ||
+        `reply #${event.replyTo.replyId}`;
+      console.log(`    ↳ replying to ${target}`);
+    }
+    printIndented(event.body);
+  }
+}
+
+export async function runBuildForumCommand({ options, auth, buildId }) {
+  const listen = options.forumAction === "listen";
+  let cursor = options.forumCursor;
+  let scopeKey = "";
+  let firstSnapshot = true;
+  let consecutiveFailures = 0;
+
+  while (true) {
+    let snapshot;
+    try {
+      snapshot = await readCompleteBuildForumSnapshot({
+        options,
+        auth,
+        buildId,
+        afterActivitySeq: cursor,
+        expectedScopeKey: scopeKey,
+      });
+    } catch (error) {
+      if (!listen || !isRetryableForumListenerError(error)) throw error;
+      consecutiveFailures += 1;
+      const retryDelayMs = Math.min(
+        options.forumPollMs * 2 ** Math.min(consecutiveFailures - 1, 4),
+        30_000,
+      );
+      console.error(
+        `Forum listener temporarily lost contact (${error?.message || error}). Retrying from confirmed cursor ${cursor} in ${retryDelayMs}ms.`,
+      );
+      await sleep(retryDelayMs);
+      continue;
+    }
+
+    if (firstSnapshot || snapshot.events.length > 0) {
+      printBuildForumSnapshot(snapshot, {
+        json: options.json,
+        kind: firstSnapshot ? "forum.snapshot" : "forum.update",
+      });
+    }
+    cursor = snapshot.pagination.nextActivitySeq;
+    scopeKey = snapshot.scopeKey;
+    if (!listen) return;
+
+    if (firstSnapshot) {
+      console.error(
+        `Listening for canonical Forum updates from cursor ${cursor}. Press Ctrl-C to stop.`,
+      );
+    }
+    firstSnapshot = false;
+    consecutiveFailures = 0;
+    await sleep(options.forumPollMs);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.39",
+  "version": "0.2.41",
   "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.32.0
-Updated: 2026-08-02
-Generated: 2026-08-13T00:13:49.827Z
+Version: 1.33.0
+Updated: 2026-08-15
+Generated: 2026-08-15T03:00:24.685Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -20,6 +20,7 @@ Generated: 2026-08-13T00:13:49.827Z
 - Use Twinkle.grammarbles for public Grammarbles question-bank trainer apps and optional signed-in viewer attempt-history filtering.
 - Use Twinkle.chess for chess engine play and analysis; app code still owns chess rules, legal moves, board state, and UI.
 - Use Twinkle.world for realtime multiplayer rooms, avatar presence, movement, emotes, and lightweight actions; world sessions are disposable and durable MMO state belongs in sharedDb/privateDb.
+- Every Twinkle-owned profilePicUrl field returned by the SDK is an absolute HTTPS URL ready for img src, or null. Fields inside app-owned JSON such as sharedDb entry data are not rewritten.
 - Use Twinkle.characters.chat for real Zero/Ciel NPC dialogue with shared room context and AI Energy-aware thinking modes.
 - Twinkle.ai.chat history entries must use { role, content }; map local message.text fields to content before passing history.
 - Live web search is enabled by default for Twinkle.ai.chat and for Medium/High Twinkle.ai.generateObject and Twinkle.characters.chat requests. App authors can pass webSearch: false to disable it for their app. Search uses the provider's live web-search tool and is included in AI Energy usage; structured and character Lite Mode remains tool-free.
@@ -75,6 +76,27 @@ files:read, user:read, users:read, dailyReflections:read, content:read, content:
   - Returns: Canonical shareable deep-link URL string, or null when app info is unavailable
   - Builds a canonical shareable deep link into this app, e.g. https://www.twin-kle.com/app/884/432-the-great-gatsby.
   - Example: await Twinkle.app.getShareUrl('432-the-great-gatsby');
+- history.getState() | scopes: none
+  - Returns: The current app-owned history state object, or null
+  - Read the current Build app view state stored through Twinkle.app.history.
+  - History state is local to this iframe session and never changes the parent Twinkle URL.
+  - Use this for archive/detail/page state inside one Build document; use navigate() to load another project file.
+- history.push(state) | scopes: none
+  - Returns: A JSON-cloned copy of the stored state
+  - Add a confirmed in-app view transition to browser history so Back stays inside the Build app.
+  - State must be a JSON-serializable object no larger than 16 KB.
+  - Push only after the requested view has loaded successfully; do not synthesize server-owned state.
+  - Example: Twinkle.app.history.push({ view: 'edition', dayIndex: 2080, page: 'scores' });
+- history.replace(state) | scopes: none
+  - Returns: A JSON-cloned copy of the stored state
+  - Replace the current in-app history entry without adding a Back step.
+  - Use this to establish the initial confirmed view or reconcile a loading-only change.
+- history.subscribe(listener, { immediate } = {}) | scopes: none
+  - Returns: unsubscribe function
+  - Restore app views when the viewer moves through browser Back or Forward history.
+  - The listener receives a cloned app state object, or null for an entry not owned by this app.
+  - The listener is called immediately by default; pass { immediate: false } to wait for Back or Forward.
+  - Example: const off = Twinkle.app.history.subscribe((state) => restoreView(state), { immediate: false });
 - async navigate(target) | scopes: none
   - Returns: { success, src }
   - Navigate to another Build preview route through the parent bridge without dropping Twinkle SDK access.
@@ -672,6 +694,7 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Always available in the build iframe.
   - World state is ephemeral and heartbeat/TTL based. Use sharedDb/privateDb for durable inventory, XP, quests, ownership, and saved progress — but write those LOW-frequency only (on a user action or an occasional snapshot, never per frame/tick); per-frame/live state stays in world presence or client memory. The server rate-limits sharedDb/privateDb writes and returns 429.
   - Events are room-scoped and include serverTime, seq, eventId, schemaVersion, sessionId, player, and room metadata.
+  - Signed-in player identity comes from the canonical Twinkle user record; player.profilePicUrl is only used for guests and is returned only when it is a valid absolute HTTPS URL.
   - Subscribe to session.ended and catch updatePresence/send errors. Stop using stale handles and reconnect only when Twinkle.world.isSessionEndedError(error) is true; for other Twinkle.world.isRecoverableSessionError(error) cases, drop the transient presence/action and keep the handle.
   - Use updatePresence for live avatar snapshots and send for lightweight actions such as emotes, interactions, and chat bubbles.
   - Throttle movement updates in app code, usually 5-15 updates per second. Do not call updatePresence from every animation frame.

package/sdk/LUMINE_ADMIN.md

@@ -95,6 +95,12 @@ The CLI enforces none of this — it is the standing instruction for the operato
 or agent making the judgments, and it applies to every verb below: recommends,
 rewards, effort levels, Featured, skips, comments, and replies.
 
+Public text authored as Ciel must be English. This is an operator and generation
+instruction, not a script or keyword test: writing systems do not identify a
+language reliably, and the API must not pretend otherwise. This is a
+presentation rule, not an invitation to correct or lecture a member who writes
+in another language; reply naturally in concise English.
+
 **Twinkle is not Reddit.** Do not rank a run's attention by popularity,
 recommendation count, or polish. Most users here are young children, and the
 posts that most need Zero or Ciel are the ones nobody else answered.
@@ -168,6 +174,13 @@ a human owner can decide, and a finding nobody reports is a finding that did not
 happen. **Every run ends with an escalation list**, and it belongs in the run's
 final report whether or not anyone asks for it.
 
+Keep that list narrow enough to be useful. Escalate concrete child-safety,
+exploitation, privacy, targeted harassment, or platform/system-abuse risk — not
+ordinary children experimenting, arguing, making rumors, proposing informal
+in-site loans or contests, asking where media can be found, or making an
+unverified ownership claim. Those may merit a normal age-appropriate response,
+but they are not escalations without credible harmful conduct or a real victim.
+
 Escalate, with the canonical `https://www.twin-kle.com/subjects/<id>` or
 `/comments/<id>` URL, a one-line summary, and why it needs him:
 
@@ -178,11 +191,10 @@ Escalate, with the canonical `https://www.twin-kle.com/subjects/<id>` or
   happened. These outrank every other category.
 - **Account integrity** — someone posting from another person's account,
   impersonation, shared logins, or a user operating a set of alternate accounts.
-- **Economy manipulation** — coin or XP farming across alternate accounts,
-  paid-grinding arrangements, "invest and I will pay you back more" offers,
-  pay-me-to-win contests, and anything that teaches other children a method for
-  any of these. Note the recommendation count: a manipulation how-to that other
-  kids are recommending is spreading, and that is the urgent part.
+- **Economy exploitation** — coordinated coin or XP farming across alternate
+  accounts, coercive or deceptive arrangements, or a repeatable abuse of the
+  platform economy with concrete evidence. A child offering a voluntary loan,
+  repayment, prize, or contest is not enough by itself.
 - **AI-cost exploits** — patterns that convert free AI allowances into farmable
   value: clusters of young accounts with heavy AI/battery usage, one person
   operating many accounts that feed a single build through team branches,
@@ -446,6 +458,11 @@ lumine admin daily-run start --identity auto --comment-mode off --json
 lumine admin daily-run start --identity ciel --comment-mode draft \
   --run-key daily:2026-08-06:review --json
 lumine admin daily-run status --json
+lumine admin daily-run escalation add --target subject:123 \
+  --note "Public contact details need owner review" --severity urgent --json
+lumine admin daily-run escalation add --target chatMessage:3768159 \
+  --note "Concrete safety issue in a bot-authored chat message" --json
+lumine admin daily-run report --json
 lumine admin daily-run complete --json
 lumine admin daily-run fail --reason "operator stopped" --json
 ```
@@ -465,6 +482,14 @@ type DailyRunComplete = Success<{
 type DailyRunFail = DailyRunComplete;
 ```
 
+Record only qualifying escalations as they are confirmed. `daily-run report`
+then composes the active run's canonical audit events, successful mutations,
+completed queue scans, recorded escalations, and the most useful brief deltas
+into one result. Generate it before `complete`, because run-scoped reads require
+the current active run. Queue coverage is written automatically only after an
+`--all` traversal reaches canonical exhaustion; an interrupted scan remains in
+its local checkpoint and cannot be misreported as complete.
+
 `lastRun` makes a lost-response retry of `complete` or `fail` possible after
 the active pointer has been cleared. Other run-scoped commands accept only the
 current unexpired `active` run. Completion first finalizes any mutation whose
@@ -498,13 +523,17 @@ JSON error includes `details.retryIdempotencyKey` for a safe exact retry.
 
 ```bash
 lumine admin recommendations list --kind recommend \
-  --content-types comment,dailyReflection --cursor '<cursor>' --json
+  --content-types comment,dailyReflection --all --json
+lumine admin recommendations list --after 2026-08-14T00:00:00Z \
+  --all --checkpoint recommendations.json --json
+lumine admin recommendations list --include-legacy --all --json
 lumine admin recommendations list --unviewed --json
 lumine admin subjects candidates --after 2026-08-01T00:00:00Z \
-  --cursor '<cursor>' --json
+  --all --checkpoint subjects.json --json
 lumine admin subjects candidates --effort unassigned --json
 lumine admin subjects candidates --unviewed --json
-lumine admin builds candidates --cursor '<cursor>' --limit 50 --json
+lumine admin builds candidates --all --limit 50 --json
+lumine admin builds review build:884 --output-dir ./build-review --json
 ```
 
 Schemas:
@@ -575,12 +604,28 @@ type BuildCandidates = Success<{
 }>;
 ```
 
-Both cursors freeze a primary-key high-water mark and traverse descending IDs,
-so concurrent inserts cannot shift or duplicate later pages. Both walks scan a
-bounded primary-key window (500 rows) per call before applying their residual
-filters, so a page — recommendation or subject — can be empty while `hasMore`
-remains true; continue until `exhausted`. Subject `--after` is inclusive, and
-the opaque cursor is bound to its original date and effort filters.
+Subject cursors freeze a primary-key high-water mark and traverse descending
+IDs. Bounded recommendation cursors freeze both the feed-ID high-water mark and
+the server timestamp, then traverse the indexed `(timeStamp, id)` order; this
+also catches a Daily Reflection whose old feed row moved forward when it was
+reshared. Explicit legacy scans retain the descending primary-key walk. A page
+can be empty while `hasMore` remains true; continue until `exhausted`. `--all`
+does that automatically and writes a private checkpoint after every
+server-confirmed page; `--resume` continues only when the checkpoint belongs to
+the same API, run, and exact request. The final result can be copied to
+`--output`, while `--checkpoint` is resumable operational state. Subject
+`--after` is inclusive, and every opaque cursor is bound to its original
+filters.
+
+Recommendations default to `--since-run`: the server uses the previous
+completed run's start time (or the same bounded seven-day fallback used by the
+brief on a first run). That deliberate start-to-start overlap gives the queue
+at-least-once coverage when content arrives after the prior snapshot but before
+that run completes. `--after` supplies an explicit inclusive timestamp.
+All-history traversal is deliberately available only through
+`--include-legacy`. The CLI requires the API to echo the canonical `after`
+boundary for bounded modes, so deploying a new CLI against an older API cannot
+silently fall back to a million-row historical scan.
 
 `builds candidates` is a management-agent discovery view over the canonical
 public Build browser, ordered by the current published release. It is
@@ -592,6 +637,15 @@ genuinely try the published runtime, or pull and read an open-source project,
 before making that judgment. Direct API/persona automation is never a review
 substitute.
 
+`builds review` is the managed runtime path: it fetches the current published
+artifact identity, launches the app in an isolated temporary Chromium profile,
+captures a screenshot and bounded console evidence, then fetches the identity
+again. It writes `review.json` in a unique per-review subdirectory only when
+the browser completed, the screenshot exists, and the artifact did not change
+mid-review. Attach the returned `receiptPath` with
+`comment draft ... --review-receipt review.json`; this binds the draft to the
+exact reviewed artifact without copying a version number by hand.
+
 During every management run, 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
@@ -919,6 +973,10 @@ If recommendation succeeds but reward fails, the command exits nonzero with
 ```bash
 lumine admin post skip dailyReflection:99 --json
 lumine admin post skip comment:456 --reason "one-line answer, nothing to add" --json
+lumine admin post skip-batch --target-file skip-targets.json \
+  --checkpoint skip-progress.json --json
+lumine admin post skip-batch --target-file skip-targets.json \
+  --checkpoint skip-progress.json --resume --json
 ```
 
 A skip records that the management rotation has judged a recommend-queue item
@@ -937,6 +995,13 @@ metadata — it is the agent's memory of the judgment, not public content.
 The skip requires the `recommendation:write` scope and is audited like every
 other mutation.
 
+`skip-batch` accepts either a JSON array (strings or `{ "target", "reason" }`
+objects), `{ "targets": [...] }`, or one target per text line. It deduplicates
+targets, submits them sequentially through the same canonical audited endpoint,
+and checkpoints only after each response is confirmed. `--resume` verifies the
+exact target-set fingerprint and run ID before continuing; it never guesses
+which writes succeeded.
+
 ```ts
 type PostSkip = Success<{
   skip: {
@@ -953,9 +1018,10 @@ type PostSkip = Success<{
 
 ```bash
 lumine admin news --json
-lumine admin news claim --json
-lumine admin news submit --edition-id 42 --lease-token <token> \
-  --file editorial.json --model "Claude" --json
+lumine admin news claim --output claim.json --scaffold editorial.json --json
+lumine admin news validate --claim claim.json --file editorial.json --json
+lumine admin news submit --claim claim.json --file editorial.json \
+  --model "Ciel" --json
 lumine admin news print --json
 ```
 
@@ -968,9 +1034,18 @@ the run, and if `printedToday` is false with no edition `pending` or
 **Preferred: write the editorial yourself.** `news claim` reserves today's
 edition under the server's generation lease and returns the exact canonical
 event digest the server would otherwise send to its own model, so no provider
-API credits are spent. Write a `GeneratedEditorial` JSON and send it back with
-`news submit` within the ten-minute lease. The server treats the editorial as
-untrusted regardless of author: every story must cite an exact `eventKey`
+API credits are spent. With `--output` and `--scaffold`, the CLI writes that
+lease/digest to a private claim file and creates an editable editorial shell.
+`news validate` runs locally, before authentication or a network request, and
+checks the complete citation graph plus byte-exact quote boundaries. Submit the
+validated pair with `news submit --claim`; the CLI reads the edition and lease
+from the claim file and validates again immediately before the request. The
+explicit `--edition-id` / `--lease-token` form remains available for backwards
+compatibility.
+
+Write a `GeneratedEditorial` JSON and send it back within the ten-minute lease.
+The server still treats the editorial as untrusted regardless of author: every
+story must cite an exact `eventKey`
 from the digest, front-page `sourceQuote`s must be verbatim contiguous
 passages of the cited event's summary (invalid quotes are replaced with
 canonical text), section and page layout are server-enforced, announcements