@stage5/lumine 0.2.20 → 0.2.22

package/lib/admin.js

@@ -1,9 +1,40 @@
 import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { assertAuthScope, resolveAuth } from "./auth.js";
 import { requestJson } from "./http.js";
 
+const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
+
+function readEditorialFile(filePath) {
+  const normalizedPath = String(filePath || "").trim();
+  if (!normalizedPath) {
+    throw cliValidationError(
+      "Pass the editorial JSON with --file <editorial.json>.",
+    );
+  }
+  let contents;
+  try {
+    contents = readFileSync(normalizedPath, "utf8");
+  } catch {
+    throw cliValidationError(`Could not read ${normalizedPath}.`);
+  }
+  if (Buffer.byteLength(contents, "utf8") > MAX_EDITORIAL_FILE_BYTES) {
+    throw cliValidationError("The editorial file must be under 256KB.");
+  }
+  try {
+    return JSON.parse(contents);
+  } catch {
+    throw cliValidationError(`${normalizedPath} is not valid JSON.`);
+  }
+}
+
 export async function adminCommand(options) {
   const operation = parseAdminOperation(options);
+  const viewFilter = resolveOperatorViewFilter({
+    operation,
+    unviewed: options.adminUnviewed,
+    viewed: options.adminViewed,
+  });
   const recommendationContentTypes =
     operation.name === "recommendations.list"
       ? parseRecommendationContentTypes(options.adminContentTypes)
@@ -64,6 +95,9 @@ export async function adminCommand(options) {
         contentTypes: recommendationContentTypes,
       });
     }
+    if (viewFilter) {
+      result = filterListResultByOperatorView({ result, viewFilter });
+    }
   } catch (error) {
     if (operation.mutates && requestId) {
       const retryInstruction = `Retry with --idempotency-key ${requestId}.`;
@@ -143,6 +177,70 @@ export function filterRecommendationQueueResult({ result, contentTypes }) {
   };
 }
 
+// Escalation lists are only useful when they exclude what Mikey already read,
+// so list output can be narrowed by his own view state. The server stamps
+// `operatorViewed` on every listed item; an item missing the field (an older
+// deployed API) is treated as unknown and kept, so the filter can never hide
+// something by accident.
+export function filterListResultByOperatorView({ result, viewFilter }) {
+  if (!viewFilter) return result;
+  const collections = ["items", "subjects", "comments"];
+  const data = { ...(result?.data || {}) };
+  let excluded = 0;
+  let unknown = 0;
+  for (const key of collections) {
+    if (!Array.isArray(data[key])) continue;
+    const kept = data[key].filter((entry) => {
+      const state = entry?.operatorViewed;
+      if (!state || typeof state.viewed !== "boolean") {
+        unknown += 1;
+        return true;
+      }
+      const keep = viewFilter === "unviewed" ? !state.viewed : state.viewed;
+      if (!keep) excluded += 1;
+      return keep;
+    });
+    data[key] = kept;
+  }
+  return {
+    ...result,
+    data: {
+      ...data,
+      operatorViewFilter: {
+        mode: viewFilter,
+        excludedItems: excluded,
+        unknownStateItems: unknown,
+      },
+    },
+  };
+}
+
+export function parseOperatorViewFilter({ unviewed, viewed }) {
+  if (unviewed && viewed) {
+    throw cliValidationError("Pass either --unviewed or --viewed, not both.");
+  }
+  if (unviewed) return "unviewed";
+  if (viewed) return "viewed";
+  return null;
+}
+
+const OPERATOR_VIEW_FILTER_OPERATIONS = new Set([
+  "recommendations.list",
+  "subjects.candidates",
+  "featured.list",
+  "subject.comments",
+  "post.comments",
+]);
+
+export function resolveOperatorViewFilter({ operation, unviewed, viewed }) {
+  const viewFilter = parseOperatorViewFilter({ unviewed, viewed });
+  if (!viewFilter) return null;
+  if (OPERATOR_VIEW_FILTER_OPERATIONS.has(operation.name)) return viewFilter;
+  throw cliValidationError(
+    "--unviewed and --viewed are supported only by admin content-list commands.",
+  );
+}
+
 function adminOperationRequiresRun(operation) {
   return ![
     "identity.list",
@@ -374,6 +472,46 @@ export function parseAdminOperation(options) {
     return recommendOperation(action, options);
   }
 
+  if (namespace === "news") {
+    if (!action || action === "status") {
+      return readOperation("news.status", "/cli/admin/news");
+    }
+    if (action === "print") {
+      return writeOperation("news.print", "POST", "/cli/admin/news/print", {});
+    }
+    if (action === "claim") {
+      const repairDate = String(options.adminDate || "").trim();
+      if (repairDate && !/^\d{4}-\d{2}-\d{2}$/.test(repairDate)) {
+        throw cliValidationError("--date must be YYYY-MM-DD.");
+      }
+      return writeOperation("news.claim", "POST", "/cli/admin/news/claim", {
+        ...(repairDate ? { date: repairDate } : {}),
+      });
+    }
+    if (action === "submit") {
+      const editionId = parseRequiredInteger(
+        options.adminEditionId,
+        "--edition-id",
+        1,
+      );
+      const leaseToken = String(options.adminLeaseToken || "").trim();
+      if (!leaseToken) {
+        throw cliValidationError(
+          "Pass the claim's lease token with --lease-token <token>.",
+        );
+      }
+      return writeOperation("news.submit", "POST", "/cli/admin/news/submit", {
+        editionId,
+        leaseToken,
+        editorial: readEditorialFile(options.adminFile),
+        model: options.model || undefined,
+      });
+    }
+    throw cliValidationError(
+      "Usage: lumine admin news [status] | news print | news claim | news submit --edition-id <id> --lease-token <token> --file <editorial.json>",
+    );
+  }
+
   if (namespace === "audit" && (!action || action === "list")) {
     const runFilter = String(options.adminRun || "").trim();
     if (runFilter && !["current", "last"].includes(runFilter)) {
@@ -432,7 +570,7 @@ export function parseAdminOperation(options) {
   }
 
   throw cliValidationError(
-    "Usage: lumine admin identity|daily-run|recommendations|post|subjects|subject|featured|comment|audit ...",
+    "Usage: lumine admin identity|daily-run|recommendations|post|subjects|subject|featured|comment|news|audit ...",
   );
 }
 
@@ -799,6 +937,44 @@ function printAdminResult({ operation, result }) {
     printPagination(data.pagination);
     return;
   }
+  if (data.claim) {
+    console.log(
+      `Claimed edition #${data.claim.editionId} (${data.claim.dateKey}): ${data.claim.events.length} event(s); lease token ${data.claim.leaseToken}.`,
+    );
+    console.log(
+      `Write the editorial JSON, then run: lumine admin news submit --edition-id ${data.claim.editionId} --lease-token ${data.claim.leaseToken} --file editorial.json`,
+    );
+    return;
+  }
+  if (data.newspaper) {
+    const paper = data.newspaper;
+    if (paper.printedToday) {
+      const printed = paper.latestPrinted || {};
+      console.log(
+        `Newspaper ${paper.dateKey}: printed (revision ${printed.revisionNumber || 1}, ${printed.sourceEventCount ?? 0} sources).`,
+      );
+    } else {
+      console.log(
+        `Newspaper ${paper.dateKey}: not printed (${paper.generationStatus}).`,
+      );
+    }
+    if (paper.requestedAction && paper.requestedAction !== "none") {
+      console.log(
+        `${paper.requestedAction === "retry" ? "Queued a retry of" : "Queued"} today's edition; the press typesets it within about a minute. Re-check with: lumine admin news`,
+      );
+    } else if (
+      !paper.printedToday &&
+      ["pending", "generating"].includes(paper.generationStatus)
+    ) {
+      console.log(
+        "An edition is being typeset now. Re-check with: lumine admin news",
+      );
+    }
+    if (paper.failureMessage && !paper.printedToday) {
+      console.log(`Last attempt failed: ${paper.failureMessage}`);
+    }
+    return;
+  }
   if (data.skip) {
     console.log(
       `${result.status}: ${data.skip.contentType}:${data.skip.contentId} skipped.`,

package/lib/commands.js

@@ -47,11 +47,7 @@ import {
   suggestBuildThumbnailToOwner,
   updateBuildMetadata,
 } from "./api.js";
-import {
-  assetsCommand,
-  confirmPrompt,
-  writeAssetsManifest,
-} from "./assets.js";
+import { assetsCommand, confirmPrompt, writeAssetsManifest } from "./assets.js";
 import { thumbnailCommand } from "./thumbnail.js";
 import {
   assertAuthScope,
@@ -491,7 +487,9 @@ export async function suggestions(options) {
 
   if (action === "merge") {
     if (suggestion.type !== "branch") {
-      throw new Error(`Suggestion #${suggestionId} is not a branch suggestion.`);
+      throw new Error(
+        `Suggestion #${suggestionId} is not a branch suggestion.`,
+      );
     }
     const mergeResult = await mergeContributionIntoMain({
       options,
@@ -510,7 +508,9 @@ export async function suggestions(options) {
 
   if (action === "replace-main") {
     if (suggestion.type !== "branch") {
-      throw new Error(`Suggestion #${suggestionId} is not a branch suggestion.`);
+      throw new Error(
+        `Suggestion #${suggestionId} is not a branch suggestion.`,
+      );
     }
     const replaceResult = await replaceMainWithContribution({
       options,
@@ -578,9 +578,7 @@ async function resolveSuggestionRootBuildId(options, auth) {
     auth,
     buildId: requestedBuildId,
   });
-  return (
-    Number(build?.contributionRootBuildId || 0) || Number(build?.id || 0)
-  );
+  return Number(build?.contributionRootBuildId || 0) || Number(build?.id || 0);
 }
 
 export function printBuildSuggestions({
@@ -1872,9 +1870,7 @@ export function printPullResult(result) {
     console.log(
       'Notify the owner when ready: lumine suggest branch "Ready for review"',
     );
-    console.log(
-      "Offer this branch's thumbnail: lumine suggest thumbnail",
-    );
+    console.log("Offer this branch's thumbnail: lumine suggest thumbnail");
   } else {
     console.log("Run `lumine check` or `lumine launch --save` when ready.");
     console.log("Review team nudges: lumine suggestions");
@@ -2097,6 +2093,8 @@ export function parseArgs(args) {
     "includeComments",
     "anyoneCanReward",
     "full",
+    "unviewed",
+    "viewed",
   ]);
 
   for (let i = 0; i < rest.length; i += 1) {
@@ -2177,6 +2175,8 @@ export function parseArgs(args) {
     adminType: raw.type ? String(raw.type) : "",
     adminKind: raw.kind ? String(raw.kind) : "",
     adminContentTypes: raw.contentTypes ? String(raw.contentTypes) : "",
+    adminUnviewed: Boolean(raw.unviewed),
+    adminViewed: Boolean(raw.viewed),
     adminIdentity: raw.identity ? String(raw.identity) : "",
     commentMode: raw.commentMode ? String(raw.commentMode) : "",
     runKey: raw.runKey ? String(raw.runKey) : "",
@@ -2187,6 +2187,10 @@ export function parseArgs(args) {
     adminRun: raw.run ? String(raw.run) : "",
     adminTarget: raw.target ? String(raw.target) : "",
     adminActions: raw.actions ? String(raw.actions) : "",
+    adminDate: raw.date ? String(raw.date) : "",
+    adminEditionId: raw.editionId ? String(raw.editionId) : "",
+    adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
+    adminFile: raw.file ? String(raw.file) : "",
     adminFull: parseBoolean(raw.full, false),
     rewardTwinkles: raw.rewardTwinkles ? String(raw.rewardTwinkles) : "",
     includeComments: parseBoolean(raw.includeComments, false),
@@ -2207,9 +2211,7 @@ export function parseArgs(args) {
     target:
       raw.url ||
       raw.target ||
-      (command === "rename" ||
-        command === "describe" ||
-        command === "suggest"
+      (command === "rename" || command === "describe" || command === "suggest"
         ? ""
         : command === "suggestions"
           ? suggestionListTarget
@@ -2506,14 +2508,17 @@ export function printHelp() {
   lumine admin identity list|status|use <zero|ciel|auto> [--json]
   lumine admin daily-run start [--identity zero|ciel|auto] [--comment-mode off|draft|post] [--run-key <key>] [--json]
   lumine admin daily-run status|complete|fail [--reason <text>] [--json]
-  lumine admin recommendations list [--content-types comment,dailyReflection] [--cursor <cursor>] [--json]
-  lumine admin subjects candidates [--after <date>] [--effort unassigned] [--cursor <cursor>] [--json]
-  lumine admin subject get|comments|reveal <subject-url-or-id> [--cursor <cursor>] [--json]
+  lumine admin recommendations list [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
+  lumine admin subjects candidates [--after <date>] [--effort unassigned] [--unviewed|--viewed] [--cursor <cursor>] [--json]
+  lumine admin subject get|reveal <subject-url-or-id> [--json]
+  lumine admin subject comments <subject-url-or-id> [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin subject effort set <subject-id> --level <1|2|3> [--json]
   lumine admin subject creator set-made-by-poster <subject-id> [--json]
   lumine admin subject feature|unfeature <subject-id> [--json]
-  lumine admin featured list|reorder --subject-ids <id,id,...> [--json]
-  lumine admin post get|comments <target> [--type subject|comment|aiStory|dailyReflection] [--cursor <cursor>] [--json]
+  lumine admin featured list [--unviewed|--viewed] [--json]
+  lumine admin featured reorder --subject-ids <id,id,...> [--json]
+  lumine admin post get <target> [--type subject|comment|aiStory|dailyReflection] [--json]
+  lumine admin post comments <target> [--type subject|aiStory|dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin post recommend <target> [--type subject|comment|aiStory|dailyReflection] [--anyone-can-reward] [--reward-twinkles 3] [--json]
   lumine admin post skip <target> [--type comment|aiStory|dailyReflection] [--reason <text>] [--json]
   lumine admin post reward <target> [--type subject|comment|aiStory|dailyReflection] --twinkles 3 [--json]
@@ -2586,6 +2591,8 @@ Options:
   --cursor <id>         Continue an owner suggestion inbox listing
   --after <date>        Admin subjects: inclusive Unix/ISO creation boundary
   --effort unassigned  Admin subjects: show only unassigned effort
+  --unviewed           Admin content lists: retain unviewed and unknown items
+  --viewed             Admin content lists: retain viewed and unknown items
   --identity <mode>     Admin identity: zero, ciel, or auto
   --comment-mode <mode> Admin run comments: off, draft, or post
   --run-key <key>       Idempotency key for an admin daily run

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -21,8 +21,18 @@ canonical structured data.
 - The public content actor is Zero or Ciel. Mikey's operator ID is retained in
   private audit rows and is not embedded in public comment metadata.
 - Delegated HTTP work never authenticates as the bot, opens a bot socket, changes
-  bot sessions, or updates bot presence/last-seen/typing state. Normal content
-  mutations still emit Twinkle's canonical real-time content events.
+  bot sessions, or updates bot presence/typing state. Normal content mutations
+  still emit Twinkle's canonical real-time content events.
+- One deliberate exception to the last-seen rule: a delegated mutation that
+  actually changed something stamps the acting bot's `users.lastActive`, so
+  Zero's and Ciel's public "last online" reflects the real day they commented on
+  and rewarded kids' posts instead of whenever a socket last closed. It is
+  written after the audit transaction commits, throttled to once a minute, and
+  best-effort — it can never fail or deadlock the content mutation. Presence is
+  still untouched: no socket is opened and no `online_status_changed` is emitted,
+  so the bots remain absent from the online list. Note that `lastActive` is the
+  ordering key for the People directory, so the bots now surface there after a
+  run; that is the intended consequence of the timestamp being truthful.
 - A later human reply to a delegated Zero/Ciel comment enters the existing
   server-side autonomous comment-assistant pipeline. Lumine does not need to
   remain running.
@@ -39,6 +49,117 @@ Comment mode is stored only on the current run:
 - `draft`: server-generated drafts, no public comment.
 - `post`: drafts plus idempotent publication through the ordinary comment path.
 
+## Editorial priorities
+
+The CLI enforces none of this — it is the standing instruction for the operator
+or agent making the judgments, and it applies to every verb below: recommends,
+rewards, effort levels, Featured, skips, comments, and replies.
+
+**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.
+
+- **Look first at new, quiet, and overlooked users.** A child's first post, or a
+  post from someone who rarely gets replies, is worth more of a run's attention
+  than another well-liked post that already has a lively thread.
+- **Clumsy is not the same as low-effort.** Bad spelling, a one-line
+  description, a title that is just "hi", a drawing that did not come out right
+  — these are usually a child trying, not a child spamming. Read for the real
+  thing they were reaching for and respond to that.
+- **Zero engagement is a reason to act, not to skip.** A post sitting at no
+  recommendations and no comments is the strongest signal in the queue that
+  someone should notice it.
+- **Thought-provoking posts deserve substance, not applause — and an unnoticed
+  one is the highest priority of all.** When a child asks a real question or
+  makes a real argument and the thread is empty, that is the clearest case for
+  a Zero/Ciel comment on the whole site. Engage with the idea itself: answer it,
+  add a perspective or a counter-consideration, and leave the author somewhere
+  to go next. A good question that nobody answered teaches a child that thinking
+  hard is not worth it; that is the outcome these runs exist to prevent. This
+  cuts both ways with the point above — the two ends of the queue, the beginner
+  nobody noticed and the strong idea nobody engaged, both outrank the popular
+  post that already has a lively thread.
+- **Always answer Twinkle usage questions.** "How do I change my username",
+  "why can't I reward", "what unlocks the Summoner" — a child stuck on the site
+  cannot use it. Answer concretely and verify anything you are unsure of against
+  the canonical rules before publishing; say you will check with Mikey rather
+  than guessing at mechanics.
+- **Always respond to bug reports, and tag `@mikey` in the comment.** The
+  mention is what notifies him (`postComment` runs `processMentions` /
+  `postMentions` and emits `new_targeted_upload`), so a bug-report comment
+  without `@mikey` fails its main job. Restate what the child observed; never
+  promise a fix or a timeline.
+- **Guide users through the website, without waiting to be asked.** A post can
+  show that a child is stuck, confused, or unaware a feature exists without ever
+  containing a question — someone begging for coins who does not know about
+  daily rewards, someone reposting because they could not find their own post.
+  Give them a short, friendly crash course on the exact thing they are stuck on.
+  Teaching a child to use the site is worth more than any single recommend.
+- **Reserve `post skip` for genuine noise** — card-sale and coin-begging spam,
+  keyboard mash, duplicates, engagement farming — not for sincere posts that
+  merely look unimpressive.
+- **Effort levels are not a verdict on the child.** Level 1 on a thin post is
+  ordinary bookkeeping; it never means the author deserves less attention, and
+  it pairs well with a warm comment.
+- **Featured still selects for quality**, but when two candidates are close,
+  prefer the child who has never been featured over the one who has.
+
+Sensitive disclosures, active disputes, and anything needing crisis or medical
+judgment remain out of scope for a bot comment no matter how neglected the post
+is. Those go to Mikey.
+
+## Escalation to Mikey
+
+A run is not finished when the mutations are done. Curation surfaces things only
+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.
+
+Escalate, with the canonical `https://www.twin-kle.com/subjects/<id>` or
+`/comments/<id>` URL, a one-line summary, and why it needs him:
+
+- **Child-safety and wellbeing** — distress or mental-health disclosures,
+  anything about self-harm, a child asking for a photo of themselves to be
+  removed, requests to delete or hide personal information, contact details
+  posted in public, or a child who says they are leaving because something
+  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.
+- **Bug reports** the run encountered, even secondhand in a comment thread.
+
+Two rules that keep the list worth reading:
+
+- **Check the thread before escalating.** If Mikey already replied in it, the
+  matter is his and it is closed unless something new happened after his reply —
+  re-reporting it wastes the one channel that is supposed to mean "look at this."
+  Say so explicitly when a post looks alarming but he already handled it.
+- **Check `operatorViewed` too.** Every Subject, Comment, StandalonePost, and
+  queue item reports whether Mikey has opened that content and when. Silence is
+  not the same as not having seen it — he often reads without replying. Lead the
+  escalation list with items where `viewed` is false, and mark the rest as
+  already-seen rather than dropping them, since he may have looked before the
+  thing you are escalating happened. `lumine admin subjects candidates --unviewed`
+  and `lumine admin recommendations list --unviewed` filter a page down to what
+  he has not opened (`--viewed` inverts it). The flags are supported by the
+  recommendation, Subject, Featured, and comment-list commands only; they are
+  rejected before any request on every other command.
+
+  Two limits make this a strong negative signal and a weak positive one: a view
+  is recorded only when the content **page** is opened, so reading a post inline
+  in a feed records nothing, and a user's view of their **own** content is never
+  recorded. So `viewed: true` reliably means he opened it; `viewed: false` means
+  "no page open recorded", not "he never saw it". Never tell a child, in public,
+  whether Mikey has or has not looked at their post.
+
+- **Escalate; do not moderate.** Zero and Ciel have no moderation verbs here by
+  design. Do not delete, hide, argue with, or publicly accuse anyone, and do not
+  warn a child that they are in trouble. Report it and let Mikey decide.
+
 ## Common JSON types
 
 All `--json` success output is one uncolored JSON value:
@@ -76,6 +197,15 @@ type Failure = {
 Shared records:
 
 ```ts
+// Present on Subject, Comment, StandalonePost, and every recommend-queue item.
+// This is the OPERATOR's own view state (Mikey), never the bot's, and reading it
+// records nothing.
+type OperatorViewed = {
+  viewed: boolean;
+  firstViewedAt: number | null; // Unix seconds
+  lastViewedAt: number | null;
+};
+
 type Author = { id: number | null; username: string | null };
 
 type Attachment = {
@@ -305,9 +435,11 @@ JSON error includes `details.retryIdempotencyKey` for a safe exact retry.
 ```bash
 lumine admin recommendations list --kind recommend \
   --content-types comment,dailyReflection --cursor '<cursor>' --json
+lumine admin recommendations list --unviewed --json
 lumine admin subjects candidates --after 2026-08-01T00:00:00Z \
   --cursor '<cursor>' --json
 lumine admin subjects candidates --effort unassigned --json
+lumine admin subjects candidates --unviewed --json
 ```
 
 Schemas:
@@ -711,6 +843,155 @@ type PostSkip = Success<{
 }>;
 ```
 
+## Twinkle Newspaper
+
+```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 print --json
+```
+
+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
+the run, and if `printedToday` is false with no edition `pending` or
+`generating`, print it.
+
+**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`
+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
+are appended verbatim outside your output, and source visibility is
+re-checked transactionally at commit.
+
+```ts
+type GeneratedEditorial = {
+  mastheadHeadline: string;
+  mastheadDeck: string;
+  lead: {
+    eventKey: string;
+    headline: string;
+    summary: string;
+    sourceQuote: string;
+  } | null;
+  stories: Array<{
+    eventKey: string;
+    headline: string;
+    summary: string;
+    sourceQuote: string;
+  }>;
+  editorsNote: string;
+};
+```
+
+Editorial rules (the same ones the server's own model works under): use only
+the supplied events — never world news, invented names, invented statistics,
+or unsupported claims. Subjects and shared Daily Reflections are the primary
+authored material; only a `section: "front"` event may be the lead. Preserve
+substance, names, and numbers. Do not mention official announcements (the
+server adds them), and give non-front events an empty `sourceQuote`.
+
+Claim edge cases: a quiet day (no editorial events) is committed as the
+canonical quiet edition at claim time — no editorial needed, the response
+says so. If the claim is not submitted before the lease expires, the server's
+press worker falls back to generating the edition itself. `news submit`
+failing with `CLI_ADMIN_NEWS_CLAIM_LOST` means the lease was superseded —
+re-check `lumine admin news` and claim again only if the paper still needs
+printing.
+
+**Repairing a past edition.** `news claim --date YYYY-MM-DD` leases an
+already-printed historical edition and returns a fresh digest of its original
+coverage window (primary Subjects/Reflections are re-projected from canonical
+tables, and anything since deleted or made private drops out). Submitting
+appends the next revision — every prior press run stays browsable in the
+archive, and repairs never re-notify subscribers (only a day's first revision
+does). Today's edition is never repaired this way; refreshing today is the
+Newspaper owner's website-only action. Repair only when an edition is
+genuinely degraded (missing masthead, missing lead, empty pages), not to
+rewrite history editorially.
+
+**Fallback: queue the server's own model.** `news print` reserves the edition
+and lets the server's press worker write it (spends provider credits). It is
+idempotent per day: it queues a new edition when today has none, requeues a
+retry when today's only attempts failed, and returns `already_done` when the
+paper is printed or being typeset.
+
+Neither path ever reprints or refreshes an already-printed edition —
+refreshing is the Newspaper owner's website-only action. The acting bot is
+recorded as the requester, and the management bots are exempt from AI Energy
+for newspaper generation: the platform absorbs the cost, exactly like their
+coin-exempt recommends and rewards. When a day's first edition is printed,
+the server notifies the app's notification subscribers (users can mute the
+app or unsubscribe in the app; the bots never need to send anything). All
+three mutations require the `news:print` scope (in every run's base scopes)
+and are audited as `news.print` / `news.claim` / `news.submit` against
+`news_edition` targets.
+
+```ts
+type NewsStatus = Success<{
+  newspaper: {
+    dayIndex: number;
+    dateKey: string; // YYYY-MM-DD
+    printedToday: boolean;
+    generationStatus:
+      | "available" // no edition requested today
+      | "pending"
+      | "generating"
+      | "ready"
+      | "failed";
+    failureMessage: string | null;
+    attempts: number | null;
+    latestPrinted: {
+      dayIndex: number;
+      dateKey: string;
+      generatedAt: number | null;
+      sourceEventCount: number;
+      revisionNumber: number;
+    } | null; // most recent printed edition, possibly a previous day
+    nextEditionAt: number;
+    printDecision: "already_printed" | "in_progress" | "retry" | "create";
+    requestedAction?: "none" | "retry" | "create"; // print responses only
+  };
+}>;
+
+type NewsPrint = NewsStatus; // "success" (queued) or "already_done"
+
+type NewsClaim = Success<{
+  newspaper: NewsStatus["data"]["newspaper"] & {
+    quietEditionPrinted?: boolean;
+  };
+  claim: {
+    editionId: number;
+    dayIndex: number;
+    dateKey: string;
+    leaseToken: string;
+    leaseExpiresAt: number;
+    coverage: { startedAt: number; endedAt: number };
+    maxSourceQuoteLength: number;
+    announcementCount: number;
+    events: Array<{
+      eventKey: string;
+      kind: string;
+      section: string; // front | community | notices | scores | marketplace
+      occurredAt: number;
+      priority: number;
+      title: string;
+      summary: string;
+      payload: unknown; // may include author and canonical topComments
+    }>;
+  } | null; // null: already printed/typesetting, or the quiet edition auto-committed
+}>;
+
+type NewsSubmit = NewsStatus; // "success"; newspaper includes revisionNumber
+```
+
 ## Audit history
 
 ```bash