@stage5/lumine 0.2.21 → 0.2.23

package/lib/admin.js

@@ -30,6 +30,11 @@ function readEditorialFile(filePath) {
 
 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)
@@ -90,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}.`;
@@ -169,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",
@@ -428,17 +500,12 @@ export function parseAdminOperation(options) {
           "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,
-        },
-      );
+      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>",

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) : "",
@@ -2211,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
@@ -2510,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]
@@ -2590,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.21",
+  "version": "0.2.23",
   "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:
@@ -743,8 +875,18 @@ re-checked transactionally at commit.
 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 }>;
+  lead: {
+    eventKey: string;
+    headline: string;
+    summary: string;
+    sourceQuote: string;
+  } | null;
+  stories: Array<{
+    eventKey: string;
+    headline: string;
+    summary: string;
+    sourceQuote: string;
+  }>;
   editorsNote: string;
 };
 ```
@@ -756,6 +898,41 @@ 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`.
 
+**Editorial craft.** The rules above make an edition valid; they do not make
+it good. The server already used the digest's `priority` numbers to select
+the bounded set of eligible events; those numbers do not do the editor's job
+within the returned digest. On a typical day every front subject arrives with
+the same priority, so treat a tied score (or recency) as no signal at all and
+make the call by reading:
+
+- **Choose the lead by argument, not by score or recency.** The best lead is
+  the front event where something is actually *at stake*: a claim with
+  reasoning, a question with a position behind it — ideally one other member
+  are already responding to. A claim plus a reply is a conversation in
+  motion; a drawing, a greeting, or a link is a share, and shares belong
+  further down the page, not in the lead.
+- **Thread a theme through the paper.** Pick the strongest idea of the day
+  and let the masthead, the lead, and the editor's note all carry it, with
+  the editor's note reprising a community value from one of the day's posts
+  rather than summarizing the edition. The paper should end on something a
+  child can take with them.
+- **Cross-reference events into arcs.** The same thing often appears in the
+  digest several times (an app's release, its open-sourcing, and its maker's
+  Daily Reflection about it). Write those as one story arc — the origin
+  story up front, the notices pointing back to it — instead of three
+  disconnected blurbs. Each story still cites only its own `eventKey`.
+- **Headlines tell the story; they do not restate the title.** "Logged Out
+  and Briefly Panicked, X Confirms: Twinkle Is 5% of Life" beats repeating
+  the post's title. Keep every fact traceable to digest text — the craft is
+  in selection and framing, never in invention.
+- **Work mechanics under the ten-minute lease.** Dump every front event's
+  full summary to a file immediately after claiming, before writing a word.
+  Copy `sourceQuote`s byte-exact from the summary — curly apostrophes,
+  markdown asterisks, ellipsis dots and all (an inexact quote is silently
+  replaced with canonical text). An event with an empty summary gets an
+  empty `sourceQuote`; restate its title's facts in your story summary
+  instead.
+
 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