@stage5/lumine 0.2.82 → 0.2.84

package/lib/constants.js

@@ -176,6 +176,11 @@ Lumine CLI as the source of truth for saving this workspace back to Twinkle.
 
 ## Workflow
 
+- When planning a new app or a substantial improvement, read the AI decision design
+  guidance in ${SDK_REFERENCE_FILE}. Consider whether JEV through Twinkle.ai.decide
+  would improve the requested experience, and choose ordinary code or a text model
+  when those fit better. Make this judgment from the app's needs; do not wait for
+  the creator to know the technology or add it automatically to every app.
 - Edit only project files in this workspace.
 - Keep /index.html or /index.htm as the entry file.
 - Before editing an existing project, confirm \`.twinkle/lumine-project.json\`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.82",
+  "version": "0.2.84",
   "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.45.2
-Updated: 2026-09-14
-Generated: 2026-09-19T10:34:03.685Z
+Version: 1.47.0
+Updated: 2026-09-21
+Generated: 2026-09-21T08:06:52.743Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -36,7 +36,15 @@ Generated: 2026-09-19T10:34:03.685Z
 - The creator's agent designs the rewards. Declare the economy in a project file `rewards.json` at the root: budgets (userDailyXP, userDailyCoins, optional userDailyClaims; there is no app-wide daily or lifetime budget, only what one learner can earn per day) and rules [{ id, title, xp, coins, verifier: 'numeric-quiz' | 'completion', maxAttempts?, retry?: { xpPercent, coinsPercent, paidAttempts? }, minSeconds? (completion), progression?: 'dated' | 'until-earned' (quiz) }]. Wire the matching Twinkle.rewards calls with those literal rule ids. Questions and answer keys NEVER go in project files (published source is readable by every player): quiz rules get them from the private question sheet uploaded with `lumine rewards sheet <file.json>` ({ rules: { <ruleId>: { questions?, sets? } } }); `lumine rewards check` validates both together. A review request freezes the code and proposes rewards.json merged with the sheet; the administrator reads the code, checks the amounts and whether the app is exploitable, may change any amount, and approves. Creators are kids and teens: show approval status and one Send for review action; do not ask them to fill in technical forms. Every code update that retains rewards needs a new approval before publishing. Removing the SDK automatically clears its gate. Apps read amounts, tries and sets from getStatus, never from their own file.
 - Verifiers: 'numeric-quiz' pays for server-checked numeric answers (retry share, attempt limits, dated sets or until-earned sets that stay up until somebody earns them, after-answer guides). 'completion' pays when the app reports an activity finished — a cleared stage, a finished round — at least minSeconds after start({ ruleId }); the server checks only the elapsed time, once per learner per site day (UTC midnight), and the budgets. Call start when the activity begins and claim({ challengeId }) with no answers when it ends; keep completion amounts and userDailyXP small enough that a player scripting the calls would not matter, because nothing else is verified.
 - Numeric quiz answers are verified on the server; client scores, privateDb state, timers and completion booleans are not verified reward evidence. Limits reset at UTC midnight. Rules are earned once per viewer per UTC day; attempt limits and retry payouts come from the approved rule. Challenges expire at the UTC day boundary. Budgets apply across release changes.
-- Optional reward rule controls: maxLifetimeClaims caps one learner’s receipts for that rule across every day and release; completionProof: classic-tower-v1 requires a server-simulated Classic Tower finish in addition to minSeconds. These are server-enforced controls. Existing completion rules without completionProof still verify elapsed time only.
+- Optional reward rule controls: maxLifetimeClaims caps one learner’s receipts for that rule across every day and release; completionProof: classic-tower-v1 requires a server-simulated Classic Tower finish in addition to minSeconds. These are server-enforced controls. Existing completion rules without completionProof still verify elapsed time only. Registered proof profiles also include breadface-v1 (server-simulated Breadface inputs) and study-record-v1 (a private study record reviewed by JEV, billed to the learner’s AI Energy). Profiles are platform-owned; an app cannot invent a verifier or authorize its own reward.
+
+## AI decision design
+- When planning a new app or an improvement, consider whether model-based judgments would materially improve the requested experience. Twinkle.ai.decide runs JEV, a model for narrow decisions over supplied text or structured state. Potential uses include interpreting a player's request to an NPC, choosing among legal game actions, classifying user content, ranking supplied candidates, and adapting an activity to evidence about the learner. These are examples to reason from, not a keyword checklist or a requirement to add AI to every app.
+- Choose the mechanism by the work: use ordinary code for known rules, arithmetic, physics, legal moves, storage, and permissions; use ai.decide for contextual choices, yes/no probabilities, and scores; use ai.chat or ai.generateObject for generated dialogue, explanations, open-ended content, and multi-step reasoning. JEV does not generate text, browse the web, inspect images, or supply missing app data. Combine these tools when it benefits the actual request, without silently turning every decision into a more expensive text-model call.
+- Before adopting JEV, identify the concrete decision, the context available at that moment, the allowed outcomes, and why latency plus AI Energy use are worthwhile. Use your model judgment to make that choice. Do not substitute regex or keyword matching for understanding human-language intent. Explain the user-visible benefit simply; the creator does not need to select a provider, enter an API key, or design question schemas.
+- Send related independent questions about the same state together in one ai.decide request (up to 32). Write complete instructions and distinct option or level descriptions. Include an other/uncertain option when the choices might not cover the input. A second call is useful only when it needs newly obtained context or choices that depend on the first result; answers in one batch do not see each other.
+- Keep code in control. Choice returns an option and its probability distribution; score returns a position on the declared levels; noul is the probability of yes, with 0.5 meaning uncertainty rather than medium strength. Confidence describes the distribution and is not proof of correctness. Test the app's criteria and thresholds on clear, ambiguous, and out-of-scope examples, and provide a suitable uncertain outcome. JEV decisions never authorize XP, Coins, purchases, access, or other server-owned state; use the appropriate existing SDK and server approval paths.
+- Call at meaningful user actions or discrete app decision points, not every render, animation frame, keystroke, or background poll. Batch work, debounce changing input, keep one request active per decision flow, and discard results whose app state changed while waiting. Keep rendering, movement, and controls local and responsive. Signed-in viewers use AI Energy based on measured JEV cost. Handle unavailable, timeout, exhausted Energy, and rate-limit errors with a clear retry or an explicitly local fallback; never fabricate an AI answer or run an automatic retry loop. Consider the guest and offline experience before making AI essential.
 
 ## Token Scopes
 files:read, media:read, media:write, live:read, live:write, user:read, users:read, dailyReflections:read, content:read, content:write, sharedDb:read, sharedDb:write, privateDb:read, privateDb:write, files:write, chat:read, chat:write, notifications:read, notifications:write, notifications:emit, reminders:read, reminders:write, rewards:claim
@@ -467,6 +475,19 @@ renderBattery(policy?.energyPercent, policy?.energySegmentsRemaining);
   - Use this for in-app AI replies instead of creating or fetching app-local endpoints such as /api/chat.
   - Example: const chatHistory = conversation.slice(-12).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text }));
 const result = await Twinkle.ai.chat({ message, history: chatHistory, systemPrompt: 'You are a cheerful pirate helper who answers in one sentence.', onText: (text, meta) => renderReply(text), onStatus: (status) => setThinking(status === 'thinking') });
+- async decide({ state, questions }) | scopes: none
+  - Returns: { answers, model, provider, aiUsagePolicy }
+  - Use JEV for fast contextual choices, yes/no probabilities, and scores inside a running app. Send several independent questions about the same state together.
+  - Read the AI decision design guidance when deciding whether this capability benefits the app. This method evaluates supplied context; it does not generate prose, browse, inspect images, run tools, grant access, or award XP/Coins.
+  - state is non-empty text, a JSON object, or a JSON array. questions maps your question IDs to { type, instructions, criteria? }. Instructions may be non-empty text or structured JSON. Every question sees the same state and answers independently; put the complete question in instructions, not just its ID.
+  - Choice: { type: 'choice', instructions, criteria: { optionName: description, other: description } }. Supply 2–255 named options. Each description is text, structured JSON, or null. Returns { type: 'choice', choice, probabilities, confidence } under answers[questionId].
+  - Score: { type: 'score', instructions, criteria: [lowestLevelDescription, ..., highestLevelDescription] }. Supply 2–10 concrete ordered descriptions. Returns { type: 'score', score, probabilities, confidence, legend }. Levels start at 0; score may be fractional and is a probability-weighted position between 0 and criteria.length - 1.
+  - Yes/no probability: { type: 'noul', instructions, criteria?: { true: description, false: description } }. Returns { type: 'noul', noul }, where noul is the probability of yes between 0 and 1. There is no separate confidence field. If criteria is supplied, describe both true and false.
+  - A request accepts 1–32 questions, at most 64 KB of JSON and 20 levels of nesting. Question IDs and option names must be non-empty, at most 128 characters, and cannot be __proto__, constructor, or prototype. Descriptions may use structured JSON; state must contain only data the app is allowed to access.
+  - Requires a signed-in viewer and uses the normal runtime AI rate limits. Twinkle selects and calls JEV on its server; never put provider credentials or an external endpoint in app code. Each successful decision settles measured JEV usage through the existing AI Energy policy and returns the canonical aiUsagePolicy. Empty Energy blocks provider work. Authorized App MCP invocations retain the existing system-covered billing policy.
+  - Errors include invalid_ai_decision (bad input), ai_decision_unavailable, ai_decision_timeout, ai_decision_rate_limited, ai_decision_invalid_response, and ai_usage_unavailable, plus the existing auth, access, Energy, and rate-limit errors. Invalid answers are rejected. There is no automatic provider retry, fabricated answer, or paid LLM fallback. Do not automatically retry a rejected request.
+  - Call on meaningful app events with bounded frequency, batch questions, and keep rendering and deterministic game rules in local code. Ignore a result if the app state or turn changed while it was pending. Test uncertain inputs and choose a fallback appropriate to the experience; confidence is not a correctness guarantee.
+  - Example: const { answers } = await Twinkle.ai.decide({ state: { playerRequest, availableActions }, questions: { action: { type: 'choice', instructions: 'Which available companion action best fits playerRequest? Use wait when unclear.', criteria: { follow: 'Follow the player', guard: 'Stay and keep watch', wait: 'Do nothing until clarified' } }, needsClarification: { type: 'noul', instructions: 'Is playerRequest too ambiguous to act on?' } } }); const action = answers.needsClarification.noul > 0.5 ? 'wait' : answers.action.choice;
 - async generateObject({ prompt, expectedStructure, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus, onReasoning } = {}) | scopes: none
   - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, requestedModel, webSearch, aiUsagePolicy }
   - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic, with optional live output/status callbacks and web search.
@@ -1023,18 +1044,21 @@ world.updatePresence({ x, y, z, facing });
   - Returns: { mode: "live", status: "awarded" | "pending" | "expired" | "not_found", receipt: { id, challengeId, ruleId, reviewId, artifactVersionId, dayKey, xp, coins, attempt, createdAt } | null, balances: { xp, coins } } | { mode: "preview", status: "not_found", receipt: null, message }
   - Read an existing receipt for this app and signed-in viewer by server-issued challengeId, including previous UTC days and previous approved versions. Requires the current approved published release and runtime grant; a stale frame must reload first. Never awards, retries a claim, returns answer keys, or restores removed rewards permission.
   - Reconcile a durable local reward outbox after a lost claim reply: awarded confirms the exact payment; pending means no receipt yet for a current unexpired challenge, so retry the same challengeId. expired or not_found confirms no paid receipt and no claim possible for that ID under the current release. Never refund app items just because getStatus history omitted an older claim or a network request failed. Preview has no durable paid receipts; keep it separate from live recovery.
-- await Twinkle.rewards.start({ ruleId }) | scopes: rewards:claim
+- await Twinkle.rewards.start({ ruleId, levelIndex? }) | scopes: rewards:claim
   - Returns: { mode: "live", challengeId, questions: [{ prompt, hint?, guide? }], setKey, reward: { xp, coins }, retryReward: { xp, coins }, attempts, maxAttempts, attemptsRemaining, firstTryAvailable, expiresAt }
   - Creates or resumes a server-issued challenge for the signed-in viewer. Render its questions (prompt and optional hint) and collect numeric answers in the same order. One daily challenge per rule/review; repeat starts cannot reset attempts. A challenge stays open until the site's daily reset (UTC midnight, 9:00 AM in Korea) (expiresAt). Resuming after a wrong answer includes each question's guide.
   - Errors: build_reward_not_scheduled when the rule has no questions for today; build_reward_daily_claims_reached when the viewer already earned today’s cap. attemptsRemaining is null for unlimited rules.
   - For a completion rule call start when the activity begins (the moment the stage starts); the challenge's age is what the claim is measured against. In preview mode start also works for the owner (a stateless simulation).
   - For completionProof: classic-tower-v1, start also returns completion { profile, token, maxFrames, completed, failed }. A new start resets only the simulated climb to its canonical spawn; it cannot reset daily or lifetime rewards. Record inputs from the first physics frame. The completion token is bound to the viewer, challenge, rule and published release.
-- await Twinkle.rewards.progress({ challengeId, completionToken, frames }) | scopes: rewards:claim
-  - Returns: { mode: "live" | "preview", completion: { profile: "classic-tower-v1", token, maxFrames, completed, failed } }
+  - For breadface-v1, pass the zero-based canonical levelIndex. Record [dt, inputBits] from the first physics frame; start returns its server token and maxFrames. For study-record-v1, start returns completion { profile, usesAiEnergy: true }; there is no client-authored proof token.
+- await Twinkle.rewards.progress({ challengeId, completionToken?, frames?, record?, requestId? }) | scopes: rewards:claim
+  - Returns: { mode: "live" | "preview", completion: { profile, token?, completed, failed?, decision?, message?, maxFrames? }, aiUsagePolicy? }
   - Verify a bounded batch of inputs for an approved server-simulated climb.
   - Only for completionProof: classic-tower-v1. Send 1 to 600 chronological physics frames, each [dt, moveX, moveY, cameraForwardX, cameraForwardZ, jumpPressed, jumpHeld, speedMultiplier]. dt is in seconds, at most 0.05; movement axes are -1 through 1; the camera values are the horizontal components before normalization; jump flags are 0 or 1; speedMultiplier is an existing Classic Tower trail speed (1, 1.1, 1.2, 1.3, 1.35 or 1.4). Geometry and player state are owned by the registered server simulation.
   - Send occasional batches with at most one request in flight. Keep the previous token and the exact batch until a response confirms it; an identical retry is safe. Use the returned token for the next batch. Simulation time cannot outrun wall time. A completed token is evidence of a legal simulated run, not proof that a human played or that inputs were not automated.
   - On respawn or a return from another world, begin a fresh run at the canonical spawn via start. Preserve other worlds and gameplay. Do not submit positions, scores, secret keys, or a client completion flag. Preview tokens can never be redeemed in the published app.
+  - For breadface-v1, send 1–1,000 chronological [dt, inputBits] frames (dt > 0 and <= 0.033). Bits are left=1, right=2, jumpHeld=4, jumpQueued=8, fireHeld=16. The server replays the registered frozen game; only a legitimate goal and any rule-specific bonus qualify. Honor maxFrames and retain unacknowledged inputs for a bounded retry.
+  - For study-record-v1, send record { work, learning, nextStep? } and one stable requestId (16–64 ASCII letters, numbers, hyphens or underscores, e.g. crypto.randomUUID()). The combined record is at most 4,000 UTF-8 bytes. Show that each check uses AI Energy before sending; accept, revise and uncertain decisions all incur measured check cost. Reuse the requestId for a lost response; do not poll in a loop. An accepted, billed review returns completion.completed and a bound token; use that token with claim. A preview charges for the check but never awards real XP/Coins. Keep the record and show completion.message on a refusal or uncertain result.
 - await Twinkle.rewards.claim({ challengeId, answers?: [number], completionToken?: string }) | scopes: rewards:claim
   - Returns: { awarded: false, attempts, attemptsRemaining, questions: [{ prompt, hint?, guide? }] } | { awarded: true, duplicate, receipt: { ruleId, xp, coins, attempt, firstTry }, questions: [{ prompt, hint?, guide? }], balances: { xp, coins } }
   - Twinkle verifies every answer, approval, current published artifact and budget before atomically recording XP and Coins. The receipt’s xp/coins are what was actually paid: the full amounts on a first try, the retry share after a wrong answer (attempt > 1). Retry the same challengeId after a lost response; a confirmed claim returns its original receipt without another award. Never update balance UI optimistically. Under retry.paidAttempts a correct answer past that attempt returns awarded: true with a zero receipt: solved, not paid.
@@ -1042,6 +1066,7 @@ world.updatePresence({ x, y, z, facing });
   - A wrong answer within two seconds of the previous one is refused with build_reward_throttled (HTTP 429) and does not count; wait for the person to try again rather than retry-looping.
   - Completion rules take no answers: claim({ challengeId }) when the activity is finished. build_reward_too_fast (HTTP 409) means fewer than minSeconds passed since start; show nothing and let play continue. In preview mode the receipt carries preview: true and nothing is paid.
   - A completionProof rule also requires the signed completionToken from a successful rewards.progress response. The server simulates the registered game physics and must reach the goal. A timer, forged position, client win flag, altered inventory or token from another viewer, challenge or release cannot authorize payment. maxLifetimeClaims is enforced from receipts in the same award transaction. build_reward_lifetime_claims_reached means all rewards for this rule have been collected; do not retry it.
+  - For study-record-v1, the server verifies the settled private review row and its viewer, app, exact release, challenge and day binding. It never trusts the client’s decision, requested award amount or AI answer. Each successful daily study record is claimable once; display only canonical receipt/balances.
 - await Twinkle.rewards.getLeaderboard({ metric?: "xp" | "coins", period?: "day" | "week" | "all", limit? }) | scopes: rewards:claim
   - Returns: { mode: "live", metric, period, limit, dayKey, from, available: { xp, coins }, entries: [{ rank, userId, username, profilePicUrl, xp, coins, claims, lastAt }], me: { rank, xp, coins, claims } | null } | { mode: "preview", metric, period, available, entries: [], me: null, message }
   - Standings of who earned the most XP or Coins in THIS app, computed by Twinkle from its own receipts (never from anything the app submits). period 'day' is today (site day, UTC), 'week' the last 7 site days, 'all' (default) every day since approval. limit defaults to 20, max 100.

package/sdk/LUMINE_ADMIN.md

@@ -2752,8 +2752,10 @@ primary review does not cover the target. An open review does not block a
 deployment or host hold. Its files, lease and database boundaries persist;
 active requests use the normal drain. A held or unavailable owner returns a
 retryable failure, so keep the session and retry when that host is available
-again. Release operators can review final shutdown deltas via management SSH
-and record their own evidence. An active review keeps ownership of clearing;
+again. Release operators review final shutdown deltas through the deployment
+workflow's private SSM/S3 snapshots (or interactive management access during
+explicit recovery) and record their evidence. Raw logs never belong in GitHub
+output. An active review keeps ownership of clearing;
 otherwise API stderr is cleared with the existing guarded
 `npm run logs:clear-errors` plus post-clear re-read. A stopped target whose final logs
 were reviewed does not need to be started for daily management; starting EC2
@@ -2995,7 +2997,7 @@ Mikey"** section carrying only
 the deltas and anomalies worth his time, next to the escalation list. Never
 dump raw sections at him.
 
-### Jev shadow pilot (standing duty, every full daily review; added 2026-09-19)
+### Jev serving and audits (standing duty, every full daily review; updated 2026-09-20)
 
 Read `data.jevPilot` from `lumine admin brief --json` and carry it into
 the full report for Mikey. The active `daily-run report --json` also includes
@@ -3009,17 +3011,64 @@ seven completed days, and keep the in-progress day separate. Include paired
 decision counts, disagreements (especially Jev react / baseline respond),
 p50/p95 latency for each model, provider errors/timeouts, pending observations,
 known incremental cost, unknown-cost requests, ledger gaps and cap status.
-The pilot's known recorded spend is already in application AI costs: never add
-it again. Shadow mode changes no user-visible decisions and has not established
-savings. Agreement is not accuracy; confidence is not a measured success rate.
+Separate `bySurface.comment` from `bySurface.chat`. For chat, report
+`routingFieldDisagreements`, `candidateSkippedBaselineRequired`, and missing
+routing-comparison evidence. Equal reply actions do not prove equal tool/history
+routing. Chat's baseline also extracts structured plans, while Jev compares seven
+routing choices plus reaction emoji; these latencies do not establish an end-to-end speedup.
+Mikey authorized production serving on September 20 for the tested comment and
+text-chat routing decisions. Include `serving.jevDecisions`, baseline and
+unreserved fallbacks with reasons, audit coverage, served disagreements,
+`serving.decisionLatencyMs`, chat added wait, and comment baseline calls avoided.
+Chat retains the existing full planner for outputs outside Jev's tested scope;
+comments run a 5% independent background baseline audit. Distinguish actual
+selected routes from unused comparisons and identify Turtle's deployment tests.
+Chat's `baseline_requires_reply` fallback preserves the planner's written reply
+when Jev would only react; report its frequency and review those disagreements.
+Reaction-only chat responses require both models to agree.
+Jev chooses the emoji from all 18 supported reactions in `chat-routing-v2`.
+Report `reactionChoices` usage by source, paired emoji disagreements, and missing
+legacy evidence; review whether the chosen tone fits the canonical conversation.
+Candidate and served emoji are in `reviewCandidates` routing objects. Earlier
+`chat-routing-v1` rows have no emoji comparison and must not count as agreement.
+Mikey explicitly requested all eligible requests with no daily request cap
+(`dailyLimit: 0`) and a cost report during every full website-management run.
+Run `lumine admin ai-costs day YYYY-MM-DD --json` for the last completed UTC day.
+Report the canonical `data.dailyAiCosts.byOperation` USD totals for `jev_reply_gate_serve`,
+`jev_chat_routing_serve`, any `_shadow` operations, and `jev_reply_gate_audit`.
+Separate comment/chat provider spend from background baseline-audit spend.
+Report unfinished selection/baseline-audit telemetry; synthetic probes are
+excluded from performance metrics but included in daily request and cost counts.
+If `telemetryStatus: partial` or `telemetryComplete: false`, detail metrics are a
+bounded recent sample, not full-day performance or cost; use the canonical daily
+AI-cost report for complete cost totals and record the coverage gap.
+Known Jev spend and `jev_reply_gate_audit` calls are already in application AI
+costs: never add them again or infer net savings from Jev cost alone. Agreement
+is not accuracy; confidence is not a measured success rate.
 
 Privately inspect the bounded `reviewCandidates` when needed, name what was
-actually reviewed, and account for edited comments. Ordinary model disagreements
+actually reviewed, and account for edited comments or chat messages. Use the
+candidate's surface and target ID to find the correct canonical record. Ordinary model disagreements
 are evaluation findings; outages, stuck telemetry or missing ledger entries are
 operational findings. Report a recommendation to continue, adjust or stop, without
-automatically enabling traffic, raising caps or promoting Jev to serving. Data
-handling for under-18 users and TypeSafe account access must be resolved before
-real conversations are sent. See `twinkle-api/JEV_PILOT.md` for configuration,
+automatically changing mode, scope or caps.
+
+Mikey's September 21 reporting requirement: include a private case-by-case
+comparison for the reviewed disagreements. For each event give the minimum
+relevant excerpt/context, field name and plain-language meaning, exact baseline
+and JEV values, selected value/source and fallback, observed outcome, and your
+assessment with evidence. Explicitly allow “both defensible” or “insufficient
+evidence”; the existing LLM is not ground truth. State reviewed/total coverage and
+rubric version. A bad delivered answer does not establish which routing choice
+caused it, and the alternative model's answer was not necessarily generated.
+`requiresPreviousMessages` means additional retrieval beyond supplied recent
+context; `requiresMathVerification` also covers answer/tutoring verification in
+non-math subjects. Historical v1/v2 telemetry records both decisions and source
+IDs, not original conversation text, model explanations or human verdicts. Read
+canonical context privately and qualify historical reconstruction when edited,
+deleted or missing. The September 21 expansion adds bounded, expiring private
+input snapshots as described below.
+See `twinkle-api/JEV_PILOT.md` for configuration,
 the synthetic evaluation step and release checks.
 
 ### Application AI calendar-month cost (standing duty, every full daily review)
@@ -3170,6 +3219,34 @@ reload while waiting in the queue. The current UTC day is returned with `inProgr
 **Headline `lastCompletedDay` (its exact `dayKey`) — never the in-progress
 day**, exactly as the closed-day AI-cost duty does.
 
+Since Mikey's 2026-09-20 decision, keep current Energy policy and worker
+capacity while observing. During every full run, supplement these counters
+with the read-only per-request diagnostic report (from the local API checkout):
+
+```bash
+ssh api-primary.twinkle.network \
+  'cd /home/ec2-user/server && timeout 75s node --max-old-space-size=128 -' \
+  < scripts/build-energy-daily.cjs
+```
+
+This uses telemetry already recorded in queue jobs, canonical run sessions,
+provider-turn budget metadata and reservation usage; no new collection or API
+restart is needed. Save its JSON privately. Headline its last completed UTC
+day and compare the complete days in its seven-day window: queue wait p50/p90/
+maximum, starts waiting over 60 seconds, cancellations before start, unchanged
+budget stops, and the separate `handoff_only`, work-without-save and unknown
+patterns. Keep the two explicit denominators separate: unchanged stops / all
+budget stops, and unchanged stops / completed manual runs in the same cohort.
+Do not divide by usage reservations or assume busy-refusal counts measure waits.
+
+Inspect the stop cases' observed starting budget, recorded work/handoff turns,
+remaining Energy and final-reservation spend. Missing lineage is unknown, not
+zero work or zero cost; final-reservation cost can exclude earlier planning
+reservations. The oldest day may be partial under rolling seven-day retention.
+These observations do not by themselves establish a bug or authorize an
+admission floor, extra worker capacity, budget cuts or model changes. Update
+todo 52 with the latest completed-day observations and any concrete regression.
+
 `flags` lists every tripped check with its exact numbers: `overflow_usd`
 (overflow above $1 on a completed day), `budget_stop_unchanged_ratio` (more
 than 30% of at least 5 budget stops ended with nothing saved),
@@ -4301,3 +4378,38 @@ contracts.
 Legacy aliases such as `subjects list`, `subjects get`, `subjects featured`,
 `comments get`, and `recommend` remain accepted, but the singular command forms
 shown above are the canonical interface.
+
+September 21 routing expansion: read `jevRoutingShadow` alongside `jevPilot` in
+both the admin brief and full daily report. The reviewed `chat-routing-v3` path
+is primary; report actual selection latency, chat baseline calls avoided, audit
+coverage and `jev_chat_routing_audit` cost separately from v1/v2. New routing
+families remain comparison-only until Mikey reviews each one and explicitly
+promotes it. Report every registered family, including zero-sample and skipped
+families; no traffic is not a pass. Show paired counts, exact differing fields,
+both values, private input snapshots when available, baseline-controlled outcome,
+provider/LLM timing, failure/skip reasons, stale comparisons, and USD spend from
+canonical `jev_<family>_shadow` cost operations. Context snapshots are bounded,
+private and expire after eight days; do not copy unrelated private content into
+public output. Raw model choices precede existing application guards and are not
+proof an action was performed. Do not call agreement accuracy or infer speedups
+from shadow timings. Full daily costs must include these operations once only.
+
+September 21 Auto exception: Mikey approved JEV as Lumine Auto's primary model
+selector immediately, with an independent LLM comparison for every choice.
+Auto is the new default; stored manual preferences remain manual. Review
+`jevRoutingShadow` / `byRoute.lumine_model` separately from the eight
+comparison-only families: selected model/effort, both decisions, exact selection
+context, confidence, fallback, actual selection latency, missing evidence and
+observed task outcome. Report `jev_lumine_model_serve` and the additional
+`jev_lumine_model_audit` spend separately, using canonical AI-cost totals without
+double-counting. JEV choice confidence and LLM agreement are not correctness
+scores. The other eight families still require review before promotion.
+
+
+### September 21 verified reward follow-up
+
+After the Study review migration is deployed, the full daily website run also reads the API-host report `node scripts/build-study-reviews-daily.cjs --days 1`. It is indexed, read-only and bounded; it reports decisions, known measured cost, unknown-usage requests, p50/p95 latency, settled checks, claims, pending rows older than 60 seconds and graded-but-unsettled rows. `--examples` includes at most 30 private full study records and their exact prompt version for administrator quality review; keep that output private. No traffic is not a quality pass. The 12 synthetic pre-release records are a small initial check, not measured real-user accuracy.
+
+Study's registered `study-record-v1` checks use learner AI Energy for accepted, revise and uncertain results. Preview checks use real AI Energy but cannot award XP/Coins. The agreed proposal pays 2,000 XP + 500 Coins at most once per learner per UTC day. Breadface's `breadface-v1` uses deterministic server physics, not a model. Both creator proposals must be accepted to publish; inspect the canonical review state and acceptance/rejection events during follow-up.
+
+For total JEV cost, include `dailyAiCosts.byProviderModel` for TypeSafe/JEV across both AI Energy and system-covered ledgers. Report serving/shadow/audit operations separately as above; the Build SDK's system-covered/failed calls use `jev_decision`, while ordinary viewer SDK checks are already counted by the AI Energy ledger. Do not add the Study report's known-cost sum on top of the canonical overall AI-cost total: it is a diagnostic breakdown of those same calls.