@stage5/lumine 0.2.40 → 0.2.42

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -1,8 +1,8 @@
 # Build SDK Index
 
-Version: 1.32.1
-Updated: 2026-08-14
-Generated: 2026-08-14T03:20:48.358Z
+Version: 1.33.0
+Updated: 2026-08-15
+Generated: 2026-08-15T03:00:24.685Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -76,6 +76,27 @@ files:read, user:read, users:read, dailyReflections:read, content:read, content:
   - Returns: Canonical shareable deep-link URL string, or null when app info is unavailable
   - Builds a canonical shareable deep link into this app, e.g. https://www.twin-kle.com/app/884/432-the-great-gatsby.
   - Example: await Twinkle.app.getShareUrl('432-the-great-gatsby');
+- history.getState() | scopes: none
+  - Returns: The current app-owned history state object, or null
+  - Read the current Build app view state stored through Twinkle.app.history.
+  - History state is local to this iframe session and never changes the parent Twinkle URL.
+  - Use this for archive/detail/page state inside one Build document; use navigate() to load another project file.
+- history.push(state) | scopes: none
+  - Returns: A JSON-cloned copy of the stored state
+  - Add a confirmed in-app view transition to browser history so Back stays inside the Build app.
+  - State must be a JSON-serializable object no larger than 16 KB.
+  - Push only after the requested view has loaded successfully; do not synthesize server-owned state.
+  - Example: Twinkle.app.history.push({ view: 'edition', dayIndex: 2080, page: 'scores' });
+- history.replace(state) | scopes: none
+  - Returns: A JSON-cloned copy of the stored state
+  - Replace the current in-app history entry without adding a Back step.
+  - Use this to establish the initial confirmed view or reconcile a loading-only change.
+- history.subscribe(listener, { immediate } = {}) | scopes: none
+  - Returns: unsubscribe function
+  - Restore app views when the viewer moves through browser Back or Forward history.
+  - The listener receives a cloned app state object, or null for an entry not owned by this app.
+  - The listener is called immediately by default; pass { immediate: false } to wait for Back or Forward.
+  - Example: const off = Twinkle.app.history.subscribe((state) => restoreView(state), { immediate: false });
 - async navigate(target) | scopes: none
   - Returns: { success, src }
   - Navigate to another Build preview route through the parent bridge without dropping Twinkle SDK access.

package/sdk/LUMINE_ADMIN.md

@@ -89,12 +89,52 @@ Mikey; routine administrator runs still escalate suspected alternate accounts
 and never auto-enforce. `accounts add` and `note set` still accept only an
 existing **unbanned** bucket.
 
+### Audited identity inspection
+
+Account-family evidence is private operator work, never a Zero/Ciel public
+action and never a reason to browse unrelated user activity. Use the dedicated
+lookup instead of direct database queries:
+
+```bash
+lumine admin identity inspect Jay1216 \
+  --reason "Confirm the account family before updating its quota bucket" --json
+lumine admin identity inspect Jay1216 \
+  --reason "Mikey requested DOB and email evidence for this decision" \
+  --include-private-evidence --json
+```
+
+The default result resolves the exact username or user ID from the writer,
+returns the canonical current AI bucket, orders candidate accounts oldest
+first, identifies the oldest account within the strongest canonical family
+boundary (bucket before email; never device alone) when that family fits in the
+bounded evidence set, reports whether each
+account has a DOB, and explains whether the link
+came from explicit bucket membership, a verified-email match, or bounded exact-
+device evidence. It does **not** reveal email addresses, DOB values, device IDs,
+IP evidence, private messages, or unrelated activity. `--include-private-evidence`
+adds DOB values and verified email addresses only; exact device IDs are never
+returned.
+
+Every inspection requires a concrete `--reason`. Before loading the evidence,
+the API commits a private `identity.inspect` audit receipt containing the real
+operator, requested target, reason, and whether private evidence was requested.
+The evidence itself is deliberately not copied into the audit log. Inspection
+is run-independent and has no public actor. Results are **candidate accounts
+for human judgment**, not an automatic ownership finding and never automatic
+grounds for moderation, bans, or bucket changes.
+
 ## 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.
 
+Public text authored as Ciel must be English. This is an operator and generation
+instruction, not a script or keyword test: writing systems do not identify a
+language reliably, and the API must not pretend otherwise. This is a
+presentation rule, not an invitation to correct or lecture a member who writes
+in another language; reply naturally in concise English.
+
 **Twinkle is not Reddit.** Do not rank a run's attention by popularity,
 recommendation count, or polish. Most users here are young children, and the
 posts that most need Zero or Ciel are the ones nobody else answered.
@@ -168,6 +208,13 @@ a human owner can decide, and a finding nobody reports is a finding that did not
 happen. **Every run ends with an escalation list**, and it belongs in the run's
 final report whether or not anyone asks for it.
 
+Keep that list narrow enough to be useful. Escalate concrete child-safety,
+exploitation, privacy, targeted harassment, or platform/system-abuse risk — not
+ordinary children experimenting, arguing, making rumors, proposing informal
+in-site loans or contests, asking where media can be found, or making an
+unverified ownership claim. Those may merit a normal age-appropriate response,
+but they are not escalations without credible harmful conduct or a real victim.
+
 Escalate, with the canonical `https://www.twin-kle.com/subjects/<id>` or
 `/comments/<id>` URL, a one-line summary, and why it needs him:
 
@@ -178,11 +225,10 @@ Escalate, with the canonical `https://www.twin-kle.com/subjects/<id>` or
   happened. These outrank every other category.
 - **Account integrity** — someone posting from another person's account,
   impersonation, shared logins, or a user operating a set of alternate accounts.
-- **Economy manipulation** — coin or XP farming across alternate accounts,
-  paid-grinding arrangements, "invest and I will pay you back more" offers,
-  pay-me-to-win contests, and anything that teaches other children a method for
-  any of these. Note the recommendation count: a manipulation how-to that other
-  kids are recommending is spreading, and that is the urgent part.
+- **Economy exploitation** — coordinated coin or XP farming across alternate
+  accounts, coercive or deceptive arrangements, or a repeatable abuse of the
+  platform economy with concrete evidence. A child offering a voluntary loan,
+  repayment, prize, or contest is not enough by itself.
 - **AI-cost exploits** — patterns that convert free AI allowances into farmable
   value: clusters of young accounts with heavy AI/battery usage, one person
   operating many accounts that feed a single build through team branches,
@@ -224,6 +270,29 @@ Two rules that keep the list worth reading:
   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.
 
+Mikey's decision must remain attached after the originating run closes. These
+commands are private, run-independent bookkeeping:
+
+```bash
+lumine admin escalation list --json
+lumine admin escalation list --status all --json
+lumine admin escalation set 123 --status acknowledged \
+  --note "Mikey is reviewing the bot response" --json
+lumine admin escalation set 123 --status resolved \
+  --note "No user fault; this audit concerned Zero's response" --json
+```
+
+`list` defaults to unresolved `open` items. `--status` also accepts
+`acknowledged`, `resolved`, or `all`. The number passed to `set` is the original
+`run.escalation` audit ID returned by the run report/list. Every disposition is
+an immutable private `escalation.status.set` audit event. A revision allocated
+while the original escalation is locked orders concurrent decisions, so the
+last applied decision is the canonical status and annotation even if request
+audit IDs were reserved in another order. `--status open` can deliberately
+reopen an item with an explanatory note. Status filters walk indexed escalation
+history rather than a fixed latest-event window. No active run or public bot
+identity is used.
+
 ## Common JSON types
 
 All `--json` success output is one uncolored JSON value:
@@ -237,7 +306,9 @@ type Success<D> = {
 };
 ```
 
-Failures print one JSON value, write no progress prose, and exit nonzero:
+Failures print one JSON value to stdout and exit nonzero. A failing `--all`
+scan may already have written bounded page progress to stderr; stdout remains
+protocol-clean:
 
 ```ts
 type Failure = {
@@ -418,6 +489,8 @@ lumine admin identity status --json
 lumine admin identity use zero --json
 lumine admin identity use ciel --json
 lumine admin identity use auto --json
+lumine admin identity inspect Jay1216 \
+  --reason "Confirm the account family before a bucket change" --json
 ```
 
 Schemas:
@@ -436,6 +509,51 @@ type IdentityStatus = Success<{
 }>;
 
 type IdentityUse = IdentityStatus;
+
+type IdentityInspection = Success<{
+  inspection: {
+    targetUserId: number;
+    privateEvidenceIncluded: boolean;
+    manualBucket: {
+      id: number;
+      label: string;
+      memberCount: number;
+      isBanned: boolean;
+    } | null;
+    oldestAccount: IdentityCandidate | null;
+    oldestAccountBasis: "manual_bucket" | "verified_email" | "target_only";
+    oldestAccountComplete: boolean;
+    candidateAltCount: number;
+    accounts: IdentityCandidate[];
+    evidenceCoverage: {
+      deviceLookbackDays: number;
+      targetDeviceEvidenceRows: number;
+      targetDeviceIdsConsidered: number;
+      relatedDeviceEvidenceRows: number;
+      candidateLimit: number;
+      truncated: boolean;
+    };
+  };
+}>;
+
+type IdentityCandidate = {
+  userId: number;
+  username: string | null;
+  joinedAt: number | null;
+  isTarget: boolean;
+  isOldestAccount: boolean;
+  hasDateOfBirth: boolean;
+  banned: boolean;
+  deleted: boolean;
+  relationBasis: Array<
+    "target" | "manual_bucket" | "verified_email" | "exact_device"
+  >;
+  sharedDeviceCount: number;
+  privateEvidence?: {
+    dateOfBirth: string | null;
+    verifiedEmails: string[];
+  };
+};
 ```
 
 `identity use` changes only the preference for a future start. It never changes
@@ -446,8 +564,16 @@ lumine admin daily-run start --identity auto --comment-mode off --json
 lumine admin daily-run start --identity ciel --comment-mode draft \
   --run-key daily:2026-08-06:review --json
 lumine admin daily-run status --json
+lumine admin daily-run escalation add --target subject:123 \
+  --note "Public contact details need owner review" --severity urgent --json
+lumine admin daily-run escalation add --target chatMessage:3768159 \
+  --note "Concrete safety issue in a bot-authored chat message" --json
+lumine admin daily-run report --json
 lumine admin daily-run complete --json
 lumine admin daily-run fail --reason "operator stopped" --json
+lumine admin escalation list --status all --json
+lumine admin escalation set 123 --status resolved \
+  --note "Final owner decision" --json
 ```
 
 Schemas:
@@ -465,6 +591,18 @@ type DailyRunComplete = Success<{
 type DailyRunFail = DailyRunComplete;
 ```
 
+Record only qualifying escalations as they are confirmed. `daily-run report`
+then composes the active run's canonical audit events, successful mutations,
+completed queue scans, recorded escalations, and the most useful brief deltas
+into one result. Generate it before `complete`, because run-scoped reads require
+the current active run. Queue coverage is written automatically only after an
+`--all` traversal reaches canonical exhaustion; an interrupted scan remains in
+its local checkpoint and cannot be misreported as complete.
+
+Creating an escalation belongs to the active run; acknowledging, annotating,
+resolving, or reopening it does not. Use the run-independent `escalation`
+commands after Mikey responds instead of starting a follow-up delegated run.
+
 `lastRun` makes a lost-response retry of `complete` or `fail` possible after
 the active pointer has been cleared. Other run-scoped commands accept only the
 current unexpired `active` run. Completion first finalizes any mutation whose
@@ -498,13 +636,17 @@ JSON error includes `details.retryIdempotencyKey` for a safe exact retry.
 
 ```bash
 lumine admin recommendations list --kind recommend \
-  --content-types comment,dailyReflection --cursor '<cursor>' --json
+  --content-types comment,dailyReflection --all --json
+lumine admin recommendations list --after 2026-08-14T00:00:00Z \
+  --all --checkpoint recommendations.json --json
+lumine admin recommendations list --include-legacy --all --json
 lumine admin recommendations list --unviewed --json
 lumine admin subjects candidates --after 2026-08-01T00:00:00Z \
-  --cursor '<cursor>' --json
+  --all --checkpoint subjects.json --json
 lumine admin subjects candidates --effort unassigned --json
 lumine admin subjects candidates --unviewed --json
-lumine admin builds candidates --cursor '<cursor>' --limit 50 --json
+lumine admin builds candidates --all --limit 50 --json
+lumine admin builds review build:884 --output-dir ./build-review --json
 ```
 
 Schemas:
@@ -575,12 +717,34 @@ type BuildCandidates = Success<{
 }>;
 ```
 
-Both cursors freeze a primary-key high-water mark and traverse descending IDs,
-so concurrent inserts cannot shift or duplicate later pages. Both walks scan a
-bounded primary-key window (500 rows) per call before applying their residual
-filters, so a page — recommendation or subject — can be empty while `hasMore`
-remains true; continue until `exhausted`. Subject `--after` is inclusive, and
-the opaque cursor is bound to its original date and effort filters.
+Subject cursors freeze a primary-key high-water mark and traverse descending
+IDs. Bounded recommendation cursors freeze both the feed-ID high-water mark and
+the server timestamp, then traverse the indexed `(timeStamp, id)` order; this
+also catches a Daily Reflection whose old feed row moved forward when it was
+reshared. Explicit legacy scans retain the descending primary-key walk. A page
+can be empty while `hasMore` remains true; continue until `exhausted`. `--all`
+does that automatically and writes a private checkpoint after every
+server-confirmed page; `--resume` continues only when the checkpoint belongs to
+the same API, run, and exact request. The final result can be copied to
+`--output`, while `--checkpoint` is resumable operational state. Subject
+`--after` is inclusive, and every opaque cursor is bound to its original
+filters.
+
+For `--all --json`, stdout remains exactly one JSON value. Scan-start, first-
+page, every-tenth-page, and exhaustion progress is written to **stderr** with
+only page/scanned/candidate counts and the private checkpoint path. A long
+traversal therefore no longer looks stalled, while piping stdout to `jq` or a
+file remains safe.
+
+Recommendations default to `--since-run`: the server uses the previous
+completed run's start time (or the same bounded seven-day fallback used by the
+brief on a first run). That deliberate start-to-start overlap gives the queue
+at-least-once coverage when content arrives after the prior snapshot but before
+that run completes. `--after` supplies an explicit inclusive timestamp.
+All-history traversal is deliberately available only through
+`--include-legacy`. The CLI requires the API to echo the canonical `after`
+boundary for bounded modes, so deploying a new CLI against an older API cannot
+silently fall back to a million-row historical scan.
 
 `builds candidates` is a management-agent discovery view over the canonical
 public Build browser, ordered by the current published release. It is
@@ -592,6 +756,15 @@ genuinely try the published runtime, or pull and read an open-source project,
 before making that judgment. Direct API/persona automation is never a review
 substitute.
 
+`builds review` is the managed runtime path: it fetches the current published
+artifact identity, launches the app in an isolated temporary Chromium profile,
+captures a screenshot and bounded console evidence, then fetches the identity
+again. It writes `review.json` in a unique per-review subdirectory only when
+the browser completed, the screenshot exists, and the artifact did not change
+mid-review. Attach the returned `receiptPath` with
+`comment draft ... --review-receipt review.json`; this binds the draft to the
+exact reviewed artifact without copying a version number by hand.
+
 During every management run, scan recent Build candidates back through the
 run's review window alongside Subjects and the recommendation queue. An app
 that is thin, broken, private, unchanged since a prior substantive bot
@@ -919,6 +1092,10 @@ If recommendation succeeds but reward fails, the command exits nonzero with
 ```bash
 lumine admin post skip dailyReflection:99 --json
 lumine admin post skip comment:456 --reason "one-line answer, nothing to add" --json
+lumine admin post skip-batch --target-file skip-targets.json \
+  --checkpoint skip-progress.json --json
+lumine admin post skip-batch --target-file skip-targets.json \
+  --checkpoint skip-progress.json --resume --json
 ```
 
 A skip records that the management rotation has judged a recommend-queue item
@@ -937,6 +1114,13 @@ metadata — it is the agent's memory of the judgment, not public content.
 The skip requires the `recommendation:write` scope and is audited like every
 other mutation.
 
+`skip-batch` accepts either a JSON array (strings or `{ "target", "reason" }`
+objects), `{ "targets": [...] }`, or one target per text line. It deduplicates
+targets, submits them sequentially through the same canonical audited endpoint,
+and checkpoints only after each response is confirmed. `--resume` verifies the
+exact target-set fingerprint and run ID before continuing; it never guesses
+which writes succeeded.
+
 ```ts
 type PostSkip = Success<{
   skip: {
@@ -953,9 +1137,10 @@ type PostSkip = Success<{
 
 ```bash
 lumine admin news --json
-lumine admin news claim --json
-lumine admin news submit --edition-id 42 --lease-token <token> \
-  --file editorial.json --model "Claude" --json
+lumine admin news claim --output claim.json --scaffold editorial.json --json
+lumine admin news validate --claim claim.json --file editorial.json --json
+lumine admin news submit --claim claim.json --file editorial.json \
+  --model "Ciel" --json
 lumine admin news print --json
 ```
 
@@ -968,9 +1153,18 @@ the run, and if `printedToday` is false with no edition `pending` or
 **Preferred: write the editorial yourself.** `news claim` reserves today's
 edition under the server's generation lease and returns the exact canonical
 event digest the server would otherwise send to its own model, so no provider
-API credits are spent. Write a `GeneratedEditorial` JSON and send it back with
-`news submit` within the ten-minute lease. The server treats the editorial as
-untrusted regardless of author: every story must cite an exact `eventKey`
+API credits are spent. With `--output` and `--scaffold`, the CLI writes that
+lease/digest to a private claim file and creates an editable editorial shell.
+`news validate` runs locally, before authentication or a network request, and
+checks the complete citation graph plus byte-exact quote boundaries. Submit the
+validated pair with `news submit --claim`; the CLI reads the edition and lease
+from the claim file and validates again immediately before the request. The
+explicit `--edition-id` / `--lease-token` form remains available for backwards
+compatibility.
+
+Write a `GeneratedEditorial` JSON and send it back within the ten-minute lease.
+The server still treats the editorial as untrusted regardless of author: every
+story must cite an exact `eventKey`
 from the digest, front-page `sourceQuote`s must be verbatim contiguous
 passages of the cited event's summary (invalid quotes are replaced with
 canonical text), section and page layout are server-enforced, announcements
@@ -1189,6 +1383,22 @@ 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.
+
+**Privacy boundary:** this is an audit of how Twinkle's bots treated members,
+not a moderation queue for members' private use of the tool. Treat private
+human messages and creative work as confidential context. Read every
+bot-authored row, but inspect adjacent human messages only when the minimum
+necessary context is needed to judge the bot's response; never browse the rest
+of a private conversation out of curiosity. Do not characterize or escalate a
+member's lawful private creative writing — including a teenager's romance
+fiction — merely because its subject is intimate or romantic. An escalation
+must identify what **Zero or Ciel** did (for example, an invented premise,
+pressure, sexualization, abuse, or a failed boundary), include only the narrow
+context needed for Mikey to decide a remedy, and never reuse private material
+for public editorial judgment, Notable User selection, or unrelated identity
+investigation. A separate concrete risk to a member may still be escalated,
+but it does not authorize a broader review of their private activity.
+
 Judge against the same values the editorial priorities encode:
 
 - **premises must be real.** The 08-11 message didn't merely choose a bad
@@ -1272,11 +1482,16 @@ farm-signal sections added the same day):
   ("$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
+  dominate that report period. Routine `topAccounts` rows identify the account
+  by user ID/username and expose only an `identitySummary` count/manual-bucket
+  flag; raw identity strings and verified email addresses are deliberately
+  omitted. Use reason-required `identity inspect`, with
+  `--include-private-evidence` only when Mikey's concrete decision needs the
+  addresses or DOB values. 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
   brief actually exposes — one risk group spanning several user IDs, repeated
-  plus-tag or dot-variant email families among top accounts, or heavy spend by
+  account groups in `farmSignals.inboxFamilies`, or heavy spend by
   accounts that `economy.topGainers` or `notableCandidates` independently marks
   as recent signups. Cross-check those signals against the escalation
   categories. Missing join-date or community data is unknown, not evidence that
@@ -1291,9 +1506,11 @@ farm-signal sections added the same day):
   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.
+  an existing member returns `already_done`; run-independent, privately audited
+  as `notable.add`, and writes through the management page's own canonical
+  service). It can therefore record Mikey's approval after the daily run has
+  closed without opening another delegated run. 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
@@ -1353,12 +1570,14 @@ farm-signal sections added the same day):
   Deliberately coarse: it is an onboarding health check, not per-child
   session tracking.
 - `farmSignals` — AI-cost farm signatures derivable with ZERO new data
-  collection: `inboxFamilies` (verified emails from accounts active in the
-  last `inboxFamilyActivityDays`, with only Gmail/googlemail's documented
+  collection: `inboxFamilies` (account groups formed from verified emails of
+  accounts active in the last `inboxFamilyActivityDays`, with only
+  Gmail/googlemail's documented
   plus-tag and dot aliases collapsed, flagging inboxes behind 3+ accounts) and
   `youngAccountAiUsage` (accounts under 30 days old drawing battery in the
-  whole-day `aiUsageDayWindow`). SIGNAL ONLY: siblings legitimately share a
-  parent inbox, so an inbox family is a reason to look, never proof or grounds
+  whole-day `aiUsageDayWindow`). The raw canonical inbox is never returned in
+  the routine brief. SIGNAL ONLY: siblings legitimately share a parent inbox,
+  so an inbox family is a reason to look, never proof or grounds
   for action. Feed real suspicions to the AI-cost escalation category. Shared
   AI device/IP risk evidence is already in `aiSpending.topRiskGroups`; do not
   guess it from inbox similarity.
@@ -1451,7 +1670,28 @@ type InsightsBrief = Success<{
         endDayInProgress: boolean;
         summary: unknown;
         byDay: unknown[];
-        topAccounts: unknown[];
+        topAccounts: Array<{
+          userId: number;
+          username: string;
+          eventCount: number;
+          requestCount: number;
+          estimatedCostUsd: number;
+          inputTokens: number;
+          cachedInputTokens: number;
+          cacheEligibleInputTokens: number;
+          outputTokens: number;
+          totalTokens: number;
+          imageCount: number;
+          audioSeconds: number;
+          energyUnits: number;
+          energyChargedUnits: number;
+          energyOverflowUnits: number;
+          coinCharged: number;
+          identitySummary: {
+            observedIdentityCount: number;
+            manualBucketObserved: boolean;
+          };
+        }>;
         topRiskGroups: unknown[];
       }
     | InsightUnavailable;
@@ -1539,7 +1779,6 @@ type InsightsBrief = Success<{
     | {
         inboxFamilyActivityDays: number;
         inboxFamilies: Array<{
-          inbox: string;
           accounts: Array<{
             userId: number;
             username: string | null;