@stage5/lumine 0.2.31 → 0.2.33

package/lib/admin.js

@@ -313,13 +313,15 @@ export function resolveOperatorViewFilter({ operation, unviewed, viewed }) {
 }
 
 function adminOperationRequiresRun(operation) {
-  return ![
-    "identity.list",
-    "identity.status",
-    "identity.use",
-    "daily-run.start",
-    "daily-run.status",
-  ].includes(operation.name);
+  return (
+    ![
+      "identity.list",
+      "identity.status",
+      "identity.use",
+      "daily-run.start",
+      "daily-run.status",
+    ].includes(operation.name) && !operation.name.startsWith("ai-bucket.")
+  );
 }
 
 function noActiveRunError() {
@@ -360,6 +362,31 @@ export function parseAdminOperation(options) {
     }
   }
 
+  if (namespace === "ai-bucket" || namespace === "ai-buckets") {
+    const bucketId = parseRequiredInteger(
+      options.adminBucketId,
+      "AI bucket ID",
+      1,
+    );
+    if (action === "get" || action === "status") {
+      return readOperation(
+        "ai-bucket.get",
+        `/cli/admin/ai-buckets/${bucketId}`,
+      );
+    }
+    if (action === "accounts" && target === "add") {
+      return writeOperation(
+        "ai-bucket.accounts.add",
+        "POST",
+        `/cli/admin/ai-buckets/${bucketId}/accounts`,
+        {
+          userIds: parseAiBucketUserIds(options.adminUserIds),
+          note: options.note || undefined,
+        },
+      );
+    }
+  }
+
   if (namespace === "daily-run") {
     if (action === "start") {
       return writeOperation(
@@ -628,6 +655,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)) {
@@ -713,7 +768,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 ...",
   );
 }
 
@@ -982,6 +1037,29 @@ function parseOrderedIds(value) {
   return ids;
 }
 
+function parseAiBucketUserIds(value) {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    throw cliValidationError(
+      "Pass explicit accounts with --user-ids <id,id,...>.",
+    );
+  }
+  const ids = raw
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => parseRequiredInteger(part, "AI bucket user ID", 1));
+  if (ids.length > 500) {
+    throw cliValidationError(
+      "An AI bucket batch can contain at most 500 users.",
+    );
+  }
+  if (new Set(ids).size !== ids.length) {
+    throw cliValidationError("AI bucket user IDs must be unique.");
+  }
+  return ids;
+}
+
 function parseRequiredInteger(
   value,
   label,
@@ -1021,6 +1099,15 @@ function cliValidationError(message) {
 
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (data.bucket && Array.isArray(data.memberUserIds)) {
+    const added = Array.isArray(data.accounts)
+      ? `; added ${data.accounts.length} explicit account(s)`
+      : "";
+    console.log(
+      `AI bucket #${data.bucket.id} (${data.bucket.label}): ${data.memberCount} canonical member account(s)${added}.`,
+    );
+    return;
+  }
   if (data.run !== undefined) {
     if (!data.run) {
       console.log("No active delegated administrator daily run.");

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

@@ -2172,6 +2172,8 @@ export function parseArgs(args) {
       : raw.ids
         ? String(raw.ids)
         : "",
+    adminBucketId: raw.bucketId ? String(raw.bucketId) : "",
+    adminUserIds: raw.userIds ? String(raw.userIds) : "",
     adminType: raw.type ? String(raw.type) : "",
     adminKind: raw.kind ? String(raw.kind) : "",
     adminContentTypes: raw.contentTypes ? String(raw.contentTypes) : "",
@@ -2507,6 +2509,8 @@ export function printHelp() {
   lumine thumbnail generate ["<prompt>"] --model <gpt-image-2|nano-banana>
   lumine doctor runtime-assets
   lumine admin identity list|status|use <zero|ciel|auto> [--json]
+  lumine admin ai-bucket get --bucket-id <id> [--json]
+  lumine admin ai-bucket accounts add --bucket-id <id> --user-ids <id,id,...> [--note <text>] [--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] [--unviewed|--viewed] [--cursor <cursor>] [--json]
@@ -2528,6 +2532,8 @@ 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 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]
 
@@ -2603,6 +2609,8 @@ Options:
   --idempotency-key <k> Stable retry key for one admin mutation
   --level <1|2|3>       Admin subject effort level
   --subject-ids <ids>   Complete ordered Featured subject IDs
+  --bucket-id <id>      Unbanned AI identity bucket for account consolidation
+  --user-ids <ids>      Explicit user IDs for an AI bucket batch (up to 500)
   --type <type>         Admin target: subject, comment, aiStory, or dailyReflection
   --kind recommend      Admin recommendation queue kind
   --anyone-can-reward   Enable canonical reward eligibility

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "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

@@ -49,6 +49,30 @@ 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.
 
+### Private AI-bucket maintenance
+
+AI identity buckets are private operator bookkeeping, not a Zero/Ciel public
+action. They therefore do not require or attach to a delegated daily run:
+
+```bash
+lumine admin ai-bucket get --bucket-id 10 --json
+lumine admin ai-bucket accounts add --bucket-id 10 \
+  --user-ids 3127,13037,15410,16288 \
+  --note "operator-confirmed account family" --json
+```
+
+`accounts add` accepts 1-500 unique positive user IDs, preflights the complete
+batch before writing, adds the canonical user and durable verified-email rules,
+re-attributes current-day AI usage, and returns the canonical bucket members.
+It is idempotent to retry. The API records the real operator in the private
+Lumine audit log; no public bot identity is involved.
+
+This surface intentionally accepts only an existing **unbanned** bucket. It
+cannot ban accounts, block signup, add IP/device/risk-key rules, or infer an
+account family. Identification remains a human/LLM evidence judgment and must
+be explicitly requested by Mikey; routine administrator runs still escalate
+suspected alternate accounts and never auto-enforce.
+
 ## Editorial priorities
 
 The CLI enforces none of this — it is the standing instruction for the operator
@@ -900,17 +924,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
@@ -961,16 +1010,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 +1034,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,6 +1103,72 @@ 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
@@ -1078,7 +1200,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
@@ -1254,7 +1385,10 @@ type InsightsBrief = Success<{
         days: number;
         startDayIndex: number;
         endDayIndex: number;
+        generatedAt: number;
+        endDayInProgress: boolean;
         summary: unknown;
+        byDay: unknown[];
         topAccounts: unknown[];
         topRiskGroups: unknown[];
       }
@@ -1388,6 +1522,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