@stage5/lumine 0.2.28 → 0.2.30

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -139,6 +139,17 @@ Escalate, with the canonical `https://www.twin-kle.com/subjects/<id>` or
   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.
+- **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,
+  plus-tagged or dot-variant email families (`kid+1@`, `k.id@`) behind multiple
+  active accounts, repeated first exchanges across accounts already linked by
+  independent evidence, or a rescue claim by an account created under 30 days
+  ago (the API maturity gate should make that last case impossible). A new
+  member's one first exchange is intended onboarding and is not suspicious by
+  itself. The daily battery is real provider money; treat farming signatures
+  with the same seriousness as coin farming. Escalate the account list and
+  evidence; never auto-enforce.
 - **Bug reports** the run encountered, even secondhand in a comment thread.
 
 Two rules that keep the list worth reading:
@@ -1052,7 +1063,8 @@ end every run report with an **"Insights for Mikey"** section carrying only
 the deltas and anomalies worth his time, next to the escalation list. Never
 dump raw sections at him.
 
-Four sections (Mikey's chosen cut, 2026-08-10):
+Nine sections (Mikey's chosen cut 2026-08-10; behavioral-insight and
+farm-signal sections added the same day):
 
 - `economy` — `topGainers` (coin-ledger aggregation over the window: gained,
   spent, net, current balance per user, Zero/Ciel excluded) and `topBalances`
@@ -1068,7 +1080,16 @@ Four sections (Mikey's chosen cut, 2026-08-10):
   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
   dominate that report period. May be `{ unavailable: true }` if the cost
-  report fails; say so rather than guessing.
+  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
+  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
+  an account is young or empty. A run that reads the spending report without
+  asking "could any of this be one person with many accounts?" has skipped a
+  duty.
 - `notableCandidates` — kids (never bots, staff `userType`s, or users already
   on the Notable Users list) ranked by authored activity in the window, with
   `isNewUser` marking window-new signups. Use it to find the overlooked and
@@ -1097,14 +1118,62 @@ Four sections (Mikey's chosen cut, 2026-08-10):
   calendar day before the exact `window.sinceTs`.
   Report the contrast between the buckets, and treat `genuinelyInterested` as
   notable-users-but-for-teachers.
+- `engagementPulse` — distinct users per surface (activeUsers, subjects,
+  comments, recommendations, wordle, reflections, dailyTasks, aiChat,
+  lumineBuildChat, buildsEdited, buildsPlayed) for the current window vs the
+  equal-length previous window, each as `{ current, previous, delta }`.
+  Presence, build edits, and build plays come from durable action/version/view
+  events, not mutable `lastActive`/`updatedAt` snapshots. Zero/Ciel are excluded
+  from authored surfaces. Wordle, daily tasks, and AI chat use the equal
+  calendar-bucket ranges in `dayWindow`; those can begin before the exact
+  timestamp window but always compare the same number of days. This is the
+  "where do users actually live, and is it shifting?" section: report only the
+  deltas that mean something, and read a surface's absolute size before
+  dramatizing a small delta.
+- `launchMetrics` — readouts for recently shipped features so nothing ships
+  unmeasured. v1 carries `firstBuildRescue` (offers recorded and redemptions
+  in the window, each `{ total, byEventType }`, plus first-Lumine-exchange
+  claims) and `wordleSkipShield` (`startDayIndex`, `active`, judged dodges,
+  and skip covers split `earned` vs `fromRescue`). Wordle metrics cover only
+  completed, actually judged days in `judgedWindow`; today's in-progress game
+  is never called a dodge. Offers without redemptions are a reason to inspect
+  sample size, event type, and offer age — not proof of a broken funnel by
+  themselves.
+- `goneQuiet` — the inverse of `notableCandidates`: users whose `lastActive`
+  fell in the 14 days before the window (so they were around, then stopped),
+  ranked by how regular they were in the prior 30 days (daily tasks and
+  Wordle), capped at 15 with `daysQuiet`. Use it for product signal (what did
+  they stop doing?) and gentle outreach candidates; never guilt a child in
+  public about absence.
+- `newUserFunnel` — signups in the window with `activeOnDayOne` (any
+  XP-ledger event within 24h of joining) and `returnedAfterDayOne`
+  (`lastActive` beyond their first day), plus the newest few accounts.
+  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
+  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
+  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.
 
 The command needs only an active run's `content:read` scope and mutates
 nothing; reading the brief is not audited content action. Window boundaries
 on the big append-only ledgers are found by binary-searching the PRIMARY key
 (several tables have no timeStamp index), avoiding lifetime scans; aggregation
-is still bounded to the selected 1–30 day window.
+is still bounded to the selected 1–30 day window. The optional sections run
+serially around the existing core report so this low-frequency command cannot
+occupy the production reader pool; one unavailable section does not suppress
+the others.
 
 ```ts
+type InsightUnavailable = { unavailable: true; error: string };
+type WindowDelta = { current: number; previous: number; delta: number };
+
 type TeacherInsight = {
   userId: number;
   username: string | null;
@@ -1180,7 +1249,115 @@ type InsightsBrief = Success<{
         topAccounts: unknown[];
         topRiskGroups: unknown[];
       }
-    | { unavailable: true; error: string };
+    | InsightUnavailable;
+  engagementPulse:
+    | {
+        windowDays: number;
+        dayWindow: {
+          currentStartDayIndex: number;
+          currentEndDayIndex: number;
+          previousStartDayIndex: number;
+          previousEndDayIndex: number;
+          dayCount: number;
+        };
+        surfaces: {
+          activeUsers: WindowDelta;
+          subjects: WindowDelta;
+          comments: WindowDelta;
+          recommendations: WindowDelta;
+          wordle: WindowDelta;
+          reflections: WindowDelta;
+          dailyTasks: WindowDelta;
+          aiChat: WindowDelta;
+          lumineBuildChat: WindowDelta;
+          buildsEdited: WindowDelta;
+          buildsPlayed: WindowDelta;
+        };
+      }
+    | InsightUnavailable;
+  launchMetrics:
+    | {
+        firstBuildRescue: {
+          offersRecorded: {
+            total: number;
+            byEventType: Record<string, number>;
+          };
+          redemptions: {
+            total: number;
+            byEventType: Record<string, number>;
+          };
+          firstLumineExchangeClaims: number;
+        };
+        wordleSkipShield: {
+          startDayIndex: number;
+          active: boolean;
+          judgedWindow: {
+            startDayIndex: number;
+            endDayIndex: number;
+          } | null;
+          judgedDodges: number;
+          skipCovers: { earned: number; fromRescue: number };
+        };
+      }
+    | InsightUnavailable;
+  goneQuiet:
+    | {
+        users: Array<{
+          userId: number;
+          username: string | null;
+          lastActive: number | null;
+          daysQuiet: number | null;
+          dailyTasksPrior30d: number;
+          wordlePlaysPrior30d: number;
+          regularityScore: number;
+        }>;
+        totals: { wentQuiet: number; previouslyRegular: number };
+      }
+    | InsightUnavailable;
+  newUserFunnel:
+    | {
+        totals: {
+          signups: number;
+          activeOnDayOne: number;
+          returnedAfterDayOne: number;
+        };
+        newest: Array<{
+          userId: number;
+          username: string | null;
+          joinedAt: number | null;
+          activeOnDayOne: boolean;
+          returnedAfterDayOne: boolean;
+        }>;
+      }
+    | InsightUnavailable;
+  farmSignals:
+    | {
+        inboxFamilyActivityDays: number;
+        inboxFamilies: Array<{
+          inbox: string;
+          accounts: Array<{
+            userId: number;
+            username: string | null;
+            joinedAt: number | null;
+            lastActive: number | null;
+          }>;
+          accountCount: number;
+          youngAccounts: number;
+        }>;
+        aiUsageDayWindow: {
+          startDayIndex: number;
+          endDayIndex: number;
+        };
+        youngAccountAiUsage: Array<{
+          userId: number;
+          username: string | null;
+          joinedAt: number | null;
+          energyUnits: number;
+          replies: number;
+        }>;
+        notes: string;
+      }
+    | InsightUnavailable;
 }>;
 ```
 
@@ -1314,6 +1491,27 @@ tried it — ask the author about it instead. This is the standing rule for
 every composed comment, applied to apps: never claim an experience the
 session did not actually have.
 
+**Offer a Lumine prompt when the moment invites it (Mikey's direction,
+2026-08-10).** Zero and Ciel may include one concrete, copy-pasteable Lumine
+prompt in a comment or reply — a genuinely powerful one, tailored to what the
+kid is already doing — when the occasion naturally calls for it. Appropriate
+occasions: a kid describes an idea they wish existed, asks how something on
+the site was made, hits the edge of what a post/drawing/story can do, shares
+a Build app that could grow a specific feature, or shows an interest (space,
+cats, chess, comics) that maps cleanly onto something Lumine could build with
+them. On those occasions, the prompt IS the helpful answer: quote it so it
+can be copied as-is, keep it specific to their interest, and mention it works
+in the Build workspace chat. Restraint rules: never more than one prompt per
+comment; never in condolence, conflict, wellbeing, or moderation-adjacent
+threads; never as a reflex closing line on ordinary comments — if the comment
+is complete without the prompt, post it without the prompt. A run where only
+a few comments carry a prompt is healthy; a run where most do is shameless
+plugging, which is exactly what Mikey asked to avoid. SDK-aware prompt ideas
+are especially good ("ask Lumine to make a magazine that pulls real Twinkle
+posts with Twinkle.subjects.search") because kids do not know the content
+APIs exist — but only suggest SDK capabilities that actually exist; check
+TWINKLE_BUILD_SDK.md if unsure.
+
 A composed draft (`--file`, plain UTF-8 text, at most the website's 10,000
 character comment limit) flows through the identical draft lifecycle —
 reservation, idempotency, context-revision CAS, publish fencing, audit