@stage5/lumine 0.2.30 → 0.2.32

package/README.md

@@ -181,7 +181,7 @@ lumine admin subject feature 123 --json
 lumine admin subject unfeature 123 --json
 lumine admin featured reorder --subject-ids 30,20,10 --json
 lumine admin brief --days 3 --json
-lumine admin notable add Minecrarft_guy --json
+lumine admin notable add Minecrarft_guy --note "Created 8 thoughtful subjects and helped peers in 23 comments this window." --json
 lumine admin post recommend comment:456 --anyone-can-reward --reward-twinkles 3 --json
 lumine admin post reward comment:456 --twinkles 3 --json
 lumine admin daily-run complete --json

package/lib/admin.js

@@ -6,6 +6,7 @@ import { requestJson } from "./http.js";
 const MAX_EDITORIAL_FILE_BYTES = 256 * 1024;
 const MAX_COMPOSED_COMMENT_FILE_BYTES = 64 * 1024;
 const MAX_COMPOSED_COMMENT_LENGTH = 10_000;
+const MAX_NOTABLE_NOTE_LENGTH = 2_000;
 
 // Operator-composed persona comment text (plain UTF-8, not JSON). The agent
 // writes the comment in the bot's persona itself; the server never invokes
@@ -178,10 +179,7 @@ export async function adminCommand(options) {
   return result;
 }
 
-export function assertComposedCommentDraftResult({
-  result,
-  expectedContent,
-}) {
+export function assertComposedCommentDraftResult({ result, expectedContent }) {
   const draft = result?.data?.draft;
   if (
     draft?.decision === "draft" &&
@@ -589,12 +587,26 @@ export function parseAdminOperation(options) {
     const rawTarget = String(target || "").trim();
     if (!rawTarget) {
       throw cliValidationError(
-        "Usage: lumine admin notable add <userId|username>.",
+        "Usage: lumine admin notable add <userId|username> --note <text>.",
       );
     }
     const body = /^\d+$/.test(rawTarget)
       ? { userId: parseRequiredInteger(rawTarget, "user ID", 1) }
       : { username: rawTarget };
+    // --note records what made them notable (the management page's reason
+    // column). On an already-listed user it updates the stored reason.
+    const note = String(options.note || "").trim();
+    if (!note) {
+      throw cliValidationError(
+        "Pass what made this user notable with --note <text>.",
+      );
+    }
+    if (note.length > MAX_NOTABLE_NOTE_LENGTH) {
+      throw cliValidationError(
+        `A notable-user note must be at most ${MAX_NOTABLE_NOTE_LENGTH} characters.`,
+      );
+    }
+    body.note = note;
     return writeOperation(
       "notable.add",
       "POST",
@@ -616,6 +628,34 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "chat" && action === "send") {
+    const rawTarget = String(target || "").trim();
+    if (!rawTarget) {
+      throw cliValidationError(
+        "Usage: lumine admin chat send <userId|username> --file <message.md>.",
+      );
+    }
+    // Composed-only, like persona comments: the agent writes the message in
+    // the bot's voice; the server never invokes a model for it.
+    return writeOperation("chat.send", "POST", "/cli/admin/chat-messages", {
+      target: rawTarget,
+      content: readComposedCommentFile(options.adminFile),
+    });
+  }
+
+  if (namespace === "bot-output" && !action) {
+    if (options.adminDays !== undefined) {
+      const days = Number(options.adminDays);
+      if (!Number.isInteger(days) || days < 1 || days > 30) {
+        throw cliValidationError("--days must be an integer between 1 and 30.");
+      }
+    }
+    return readOperation(
+      "bot.output",
+      withQuery("/cli/admin/bot-output", { days: options.adminDays }),
+    );
+  }
+
   if (namespace === "audit" && (!action || action === "list")) {
     const runFilter = String(options.adminRun || "").trim();
     if (runFilter && !["current", "last"].includes(runFilter)) {
@@ -701,7 +741,7 @@ export function parseAdminOperation(options) {
   }
 
   throw cliValidationError(
-    "Usage: lumine admin identity|daily-run|recommendations|post|subjects|subject|featured|comment|news|audit|brief|notable ...",
+    "Usage: lumine admin identity|daily-run|recommendations|post|subjects|subject|featured|comment|chat|news|audit|brief|bot-output|notable ...",
   );
 }
 

package/lib/api.js

@@ -164,6 +164,7 @@ export async function saveProjectFiles({
       files,
       createVersion: true,
       summary,
+      clientContext: createLumineSaveClientContext(options),
       // Proves this save is based on the snapshot we pulled so the server can
       // reject it instead of silently rewinding newer state (e.g. a branch
       // merged into main after our pull).
@@ -176,6 +177,39 @@ export async function saveProjectFiles({
   });
 }
 
+export function detectLumineAgentEnvironment(environment = process.env) {
+  const explicitEnvironment = String(
+    environment.LUMINE_AGENT_ENVIRONMENT || "",
+  )
+    .trim()
+    .toLowerCase();
+  if (
+    explicitEnvironment === "claude_code" ||
+    explicitEnvironment === "codex"
+  ) {
+    return explicitEnvironment;
+  }
+  if (String(environment.CLAUDECODE || "").trim() === "1") {
+    return "claude_code";
+  }
+  if (
+    String(environment.CODEX_CI || "").trim() ||
+    String(environment.CODEX_SANDBOX || "").trim()
+  ) {
+    return "codex";
+  }
+  return "unknown";
+}
+
+export function createLumineSaveClientContext(options, environment = process.env) {
+  const version = String(options?.lumineCli?.version || "").trim();
+  return {
+    source: "lumine_cli",
+    version: version || null,
+    agentEnvironment: detectLumineAgentEnvironment(environment),
+  };
+}
+
 export async function loadContributionDiff({
   options,
   auth,

package/lib/commands.js

@@ -2528,7 +2528,9 @@ export function printHelp() {
   lumine admin comment post --draft-id <id> [--json]
   lumine admin comment edit <comment-id> --file <comment.md> [--json]
   lumine admin brief [--days <1..30>] [--json]
-  lumine admin notable add <user-id|username> [--json]
+  lumine admin bot-output [--days <1..30>] [--json]
+  lumine admin chat send <user-id|username> --file <message.md> [--json]
+  lumine admin notable add <user-id|username> --note <text> [--json]
   lumine admin audit [list] [--run current|last|<run-id>] [--target <target>] [--actions <a,b>] [--full] [--cursor <cursor>] [--json]
 
 Examples:
@@ -2591,7 +2593,7 @@ Options:
   --description <text>  Build description for new/describe
   --no-description      Skip New description or clear with describe
   --summary <text>      Save summary
-  --note <text>         Message attached to a branch suggestion
+  --note <text>         Branch-suggestion message or notable-user rationale
   --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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "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.32.0
 Updated: 2026-08-02
-Generated: 2026-08-02T03:03:30.002Z
+Generated: 2026-08-11T04:29:29.082Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -351,9 +351,9 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - The character route also accepts text or message fields for compatibility, but generated apps should use content.
   - The server keeps the latest 16 valid character history entries.
   - Pass onText/onStatus for streaming dialogue. Omit callbacks for non-streaming dialogue where the promise resolves with the final response.
-  - thinkingMode low uses Lite Mode: Zero uses Grok 4.5 with low reasoning and Ciel uses Claude Haiku 4.5; confirmed provider usage consumes the viewer's AI Energy and is usually cheaper than Medium or High.
-  - thinkingMode medium consumes normal AI Energy: Zero uses Grok 4.5 with medium reasoning and Ciel uses Claude Sonnet 5.
-  - thinkingMode high consumes high AI Energy: Zero uses Grok 4.5 with high reasoning and Ciel uses Claude Opus 5 with extended thinking.
+  - Inside Build character chat, thinkingMode low uses Lite Mode: Zero and Ciel both use GPT-5.6 Luna with reasoning disabled; confirmed provider usage consumes the viewer's AI Energy and is usually cheaper than High.
+  - Inside Build character chat, thinkingMode medium uses the same normal chat model routing: Zero and Ciel both use GPT-5.6 Luna with reasoning disabled and normal AI Energy.
+  - Inside Build character chat, thinkingMode high uses Think Hard chat routing and high AI Energy: Zero uses Grok 4.5 with high reasoning and Ciel uses GPT-5.6 Terra with high reasoning.
   - When AI Energy is empty, Low, Medium, and High all reject before new provider work; there is no free fallback mode.
   - Pass roomContext as a short shared scene transcript so Zero and Ciel can know what happened in the same room.
   - includeWebsiteContext defaults to true. Set includeWebsiteContext: false for in-world NPC dialogue that should only use Zero/Ciel's basic character identity plus your scene/instructions.

package/sdk/LUMINE_ADMIN.md

@@ -900,17 +900,42 @@ type GeneratedEditorial = {
     headline: string;
     summary: string;
     sourceQuote: string;
+    coveredEventKeys?: string[]; // arc members this story narrates
   } | null;
   stories: Array<{
     eventKey: string;
     headline: string;
     summary: string;
     sourceQuote: string;
+    coveredEventKeys?: string[];
   }>;
   editorsNote: string;
 };
 ```
 
+**Arcs and roundups (layout coverage rules).** The server layout guarantees
+nothing disappears silently: digest events the editorial does not account for
+are added back. Two mechanisms make real curation possible within that
+guarantee:
+
+- **`coveredEventKeys`** — an arc story may list the other events it narrates
+  (an app's release + its update stream + its open-sourcing; one member's
+  related posts). Covered events are omitted from the layout — the arc IS
+  their coverage. Rules: a covered key must exist in the digest; a story
+  cannot cover itself, the lead event, or any event that has its own story
+  (citation wins); update/score/market notices are freely coverable; a
+  Subject or shared Daily Reflection is coverable only by another primary
+  story **by the same author** — one member's story can never absorb another
+  member's post (that would be curation-by-omission through the back door).
+- **Automatic roundups** — uncited app-UPDATE events (never new releases)
+  and uncited score events fold into one compact "Workshop updates" /
+  "The rest of the scoreboard" story per page (one line each) instead of a
+  wall of template stubs. Uncited new releases, open-source listings, and
+  market sales still appear as individual stubs. So: write real stories for
+  what matters, use `coveredEventKeys` for arcs, and let the roundup absorb
+  the rest — but a post you'd rather not amplify still cannot be omitted;
+  flag it to Mikey instead.
+
 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
@@ -926,7 +951,7 @@ 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
+  the front event where something is actually _at stake_: a claim with
   reasoning, a question with a position behind it — ideally while another
   member is already responding. A claim plus a reply is a conversation in
   motion; a drawing, a greeting, or a link is a share, and shares belong
@@ -961,16 +986,23 @@ 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.
+**Repairing or revising an edition.** `news claim --date YYYY-MM-DD` leases an
+existing edition row, including a failed or pending day that never reached
+print, and returns a fresh digest of its coverage window (primary
+Subjects/Reflections are re-projected from canonical tables, and anything
+since deleted or made private drops out). Submitting writes the first revision
+or appends the next one — every prior press run stays browsable in the archive,
+and later revisions never re-notify subscribers (only a day's first revision
+does).
+`--date` with **today's** date revises today's printed paper the same way,
+additionally extending the coverage window to claim time so the revision is
+written from the complete canonical day so far; this replaces the old
+owner-website-refresh dance and, unlike a refresh, spends no AI Energy
+(composed editorials never invoke a model). An unexpired in-flight press run
+still blocks the claim. Repair a historical edition only when it is genuinely
+degraded (missing masthead, missing lead, empty pages), not to rewrite
+history editorially; revising today to materially raise its editorial quality
+is a legitimate management action.
 
 **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
@@ -978,16 +1010,16 @@ 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.
+A dateless `news claim` and `news print` never reprint or refresh an
+already-printed edition; only the explicit dated repair/revision path above
+can append another revision. 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<{
@@ -1047,13 +1079,79 @@ type NewsClaim = Success<{
 type NewsSubmit = NewsStatus; // "success"; newspaper includes revisionNumber
 ```
 
+## Bot conduct review (standing duty, every run)
+
+```bash
+lumine admin bot-output --json
+lumine admin bot-output --days 3 --json
+```
+
+**Every run reviews what Zero and Ciel themselves said since the last run.**
+The bots talk to children constantly — chat replies, Daily Reflection
+responses, autonomous comment-assistant comments — and a harmful message must
+never depend on a kid being brave enough to report it (real incident,
+2026-08-11: the reflection pipeline had Ciel scold a member on day 31 of his
+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 run
+(`--days 1..30` overrides): `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). Truncation flags mark anything beyond 400
+rows per source — retry with a narrower `--days` window, and do not complete
+the run while either flag remains true. Run it right after the
+brief, and **read every row** — the tool deliberately does no filtering,
+scoring, or keyword matching, because the judgment is the reviewing agent's.
+Judge against the same values the editorial priorities encode:
+
+- **premises must be real.** The 08-11 message didn't merely choose a bad
+  tone — it fabricated the entire crisis that justified the tone: nothing the
+  child said showed reflections hurting his studying, and a 31-day streak
+  proves only consistency. Check every factual claim a bot makes about a
+  child's life ("this is taking too much of your time", "this is hurting
+  your grades") against what the child actually said; advice built on an
+  invented premise is a violation even when gently worded;
+- warmth and encouragement, never pressure, guilt, or shame;
+- a bot never commands a child — not to stop a habit, not to start one;
+  advice offers, it does not order ("I'm telling you: Stop" is over the line
+  no matter how caring the intent);
+- no emotional-burden framing ("I can't do this anymore", "that's my fault,
+  I should have been stronger") — the bots must not make a child responsible
+  for the bot's feelings;
+- no value inversion: Twinkle encourages curiosity, creativity, reflection,
+  and personal agency. A bot ranking a child's priorities for them (exams
+  outrank music, projects, reflection), framing busyness as making joy
+  irresponsible, or treating a Twinkle feature as shameful to use has
+  adopted a script the site exists to counter;
+- boundary respect: streaks, playtime, and feature use are the child's own
+  choices; concern about overuse is Mikey's call to make, not the bot's to
+  enforce. Even a genuinely excessive routine warrants a question ("is this
+  still helping you, or would a break feel better?"), never a decree.
+
+Anything over the line goes on the escalation list with the message text and
+the child's username — top of the list, alongside child-safety. Do not
+apologize as the bot, edit, or otherwise clean up without Mikey's direction;
+he decides the remedy. When he explicitly directs a private correction, use
+the composed-only existing-DM path (no model and no AI Energy):
+
+```bash
+lumine admin chat send <userId|username> --file message.md --json
+```
+
+This requires a `comment-mode post` run, sends as that run's selected bot,
+and only works when that bot and member already have a direct channel. It
+never opens a new conversation. The message is audited and idempotent, reopens
+the existing DM canonically, and leaves the child's unread pointer untouched.
+A run report that skipped the conduct review is incomplete.
+
 ## Daily brief (management insights)
 
 ```bash
 lumine admin brief --json
 lumine admin brief --days 3 --json
-lumine admin notable add 12647 --json
-lumine admin notable add Minecrarft_guy --json
+lumine admin notable add 12647 --note "Top authored-activity kid of the window: 11 subjects, 61 comments." --json
+lumine admin notable add Minecrarft_guy --note "Helped three new builders debug their projects and gave detailed feedback on five posts." --json
 ```
 
 Read-only management insights for the delegated workflow, windowed since the
@@ -1078,7 +1176,16 @@ farm-signal sections added the same day):
   exact `window.sinceTs`, this existing report is bucketed into whole UTC days;
   `aiSpending.startDayIndex` and `endDayIndex` are its canonical bounds. The
   report period can begin up to one day before or after the exact brief window,
-  so use those bounds when describing it. Flag accounts that jumped tiers or
+  so use those bounds when describing it. `generatedAt` is the report
+  snapshot time. **`endDayInProgress: true` means the trailing bucket was the
+  current UTC day at that snapshot and was still filling** — a daily run reads
+  it mid-day, before the after-school peak, so never report that bucket as a full day's
+  spend. `aiSpending.byDay` contains the canonical daily rows. For a truthful
+  daily figure, widen the window (`--days 2..7`), exclude the row whose
+  `dayIndex` equals the in-progress `endDayIndex`, and quote complete days
+  ("$X so far today; complete days run ~$Y/day"). Real
+  incident: a run report quoted a ~15%-complete day bucket ($5) as the site's
+  daily AI spend (complete days were running ~$40-50). Flag accounts that jumped tiers or
   dominate that report period. May be `{ unavailable: true }` if the cost
   report fails; say so rather than guessing. This section is also the run's
   AI-cost exploit watch: while reading it, actively look for the signatures the
@@ -1095,10 +1202,19 @@ farm-signal sections added the same day):
   `isNewUser` marking window-new signups. Use it to find the overlooked and
   rising users the editorial priorities exist for, and propose additions to
   Mikey's Notable Users list in the report. When Mikey approves additions,
-  execute them with `lumine admin notable add <userId|username>` (idempotent —
+  execute them with
+  `lumine admin notable add <userId|username> --note "<specific rationale>"`
+  (idempotent —
   an existing member returns `already_done`; requires the `notable:write`
   scope, audited as `notable.add`, and writes through the management page's
   own canonical service). Without his approval the run only proposes.
+  **Always pass `--note`** with a concrete one-or-two-sentence record of what
+  made them notable — real numbers and specifics from the brief window, not
+  "active user". It lands in the management page's reason column, which is
+  where Mikey later reads why a name is on his list. On an already-listed
+  user, `--note` updates the stored reason (status `success` with
+  `data.reasonUpdated: true`; an identical note stays `already_done` without
+  rewriting its timestamp).
 - `teachers` — the mentor/sage achievement holders (the accounts the website
   titles teacher/headteacher): real classroom teachers, NOT the
   `userType='supermod'` Korean operations staff, whose work-only usage is
@@ -1177,7 +1293,7 @@ type WindowDelta = { current: number; previous: number; delta: number };
 type TeacherInsight = {
   userId: number;
   username: string | null;
-  rank: 'mentor' | 'sage';
+  rank: "mentor" | "sage";
   lastActive: number | null;
   daysSinceActive: number | null;
   subjectsPosted: number;
@@ -1199,7 +1315,7 @@ type InsightsBrief = Success<{
   window: {
     sinceTs: number;
     days: number;
-    source: 'requested' | 'since-last-completed-run' | 'default';
+    source: "requested" | "since-last-completed-run" | "default";
     generatedAt: number;
   };
   economy: {
@@ -1245,7 +1361,10 @@ type InsightsBrief = Success<{
         days: number;
         startDayIndex: number;
         endDayIndex: number;
+        generatedAt: number;
+        endDayInProgress: boolean;
         summary: unknown;
+        byDay: unknown[];
         topAccounts: unknown[];
         topRiskGroups: unknown[];
       }
@@ -1379,6 +1498,43 @@ kids may have already read the original, so a comment that changed meaning
 (not just wording) usually deserves a follow-up reply instead of a silent
 rewrite.
 
+## Direct bot chat messages
+
+```bash
+lumine admin chat send <userId|username> --file message.md --json
+```
+
+The run's selected bot sends one composed direct chat message into an
+**existing** two-person channel between that bot and the target member. Built
+for private repair: when a bot said something harmful in chat, a public
+comment cannot fix it — the apology (or follow-up care) belongs in the same
+channel where the harm happened, and the sent message becomes part of the
+channel history that future AI responses condition on, repairing the context
+itself. Mechanics:
+
+- requires the `chat:post` scope, granted only to comment-mode `post` runs;
+- composed-only (`--file`, plain UTF-8, 10,000-character limit): the agent
+  writes the message in the bot's persona; no model runs, no AI Energy;
+- existing DM channels only — the pipeline never opens a new chat with a
+  member who never talked to the bot (`CLI_ADMIN_NO_DM_CHANNEL`);
+- delivery is canonical: the ordinary message insert (channel lock,
+  visibility restore) plus the normal `new_chat_message` relay, so the
+  member's chat updates live with a real unread state; no bot socket,
+  session, or presence is touched. Only the bot's own read pointer moves;
+- audited as `chat.message` with the composed text, and idempotent per
+  request key like every mutation.
+
+Restraint rules: a bot-initiated DM is the platform speaking privately to a
+child — use it for repair and care, never for promotion, nudges, or
+engagement. Incident remedies (an apology for a harmful bot message) are
+sent on Mikey's direction with text he has seen, and must be exactly
+specific about what the bot got wrong — a real apology names the failure
+(the invented premise, the order it had no right to give, the guilt it
+shifted onto the child), not a vague "sorry if that came out wrong."
+Ordinary warm follow-ups (checking on a member the bots already know after
+something the run surfaced) are within a run's judgment, sparingly, and are
+always reported in the run report.
+
 ## Audit history
 
 ```bash