@stage5/lumine 0.2.51 → 0.2.53

package/README.md

@@ -139,6 +139,10 @@ methods. The JSON args are sent as the request body (shapes follow
 ```bash
 lumine sdk call aiStories.chapters '{"limit": 5}'
 lumine sdk call aiStories.list '{"difficulty": 1}' --repeat 5 --build 1374
+lumine sdk call live.list '{}'
+lumine sdk call live.get '{"sessionId": "..."}'
+lumine sdk call live.listReplays '{"limit": 20}'
+lumine sdk call live.getReplay '{"replayId": "..."}'
 ```
 
 It targets the build in the current workspace, or pass `--build <id>`. Add
@@ -146,6 +150,13 @@ It targets the build in the current workspace, or pass `--build <id>`. Add
 which can differ from a method's `Twinkle.*` SDK return shape — check
 `TWINKLE_BUILD_SDK.md` for SDK return shapes. Methods that change data require
 `--allow-write`.
+Stopping a hosted stream is available as
+`lumine sdk call live.stop '{"sessionId":"..."}' --allow-write`; the command
+prints canonical server state and refuses to mint `live:write` without the
+explicit write flag.
+Replay listing and status are available without exposing private playback
+grants. A creator or app owner can remove one with
+`lumine sdk call live.deleteReplay '{"replayId":"..."}' --allow-write`.
 
 ## Assets and AI image generation
 

package/lib/admin.js

@@ -96,9 +96,7 @@ function readBuildReviewContextFile(filePath) {
     );
   }
   const understanding =
-    typeof parsed.understanding === "string"
-      ? parsed.understanding.trim()
-      : "";
+    typeof parsed.understanding === "string" ? parsed.understanding.trim() : "";
   if (!understanding) {
     throw cliValidationError(
       "The Build review context understanding must be a non-empty string.",
@@ -1235,6 +1233,35 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "ai-costs") {
+    if (action === "monthly" && !target && !extra) {
+      if (options.adminDays) {
+        throw cliValidationError(
+          "ai-costs monthly uses UTC calendar months and does not accept --days.",
+        );
+      }
+      return readOperation("ai-costs.monthly", "/cli/admin/ai-costs/monthly");
+    }
+    throw cliValidationError("Usage: lumine admin ai-costs monthly [--json].");
+  }
+
+  if (namespace === "media-costs") {
+    if (action === "monthly" && !target && !extra) {
+      if (options.adminDays) {
+        throw cliValidationError(
+          "media-costs monthly uses the canonical UTC ledger and does not accept --days.",
+        );
+      }
+      return readOperation(
+        "media-costs.monthly",
+        "/cli/admin/media-costs/monthly",
+      );
+    }
+    throw cliValidationError(
+      "Usage: lumine admin media-costs monthly [--json].",
+    );
+  }
+
   if (namespace === "brief" && !action) {
     if (options.adminDays) {
       const days = Number(options.adminDays);
@@ -1419,9 +1446,7 @@ export function parseAdminOperation(options) {
           ...(confirmedBuildReviewMethod
             ? { buildReviewMethod: confirmedBuildReviewMethod }
             : {}),
-          ...(buildReviewUnderstanding
-            ? { buildReviewUnderstanding }
-            : {}),
+          ...(buildReviewUnderstanding ? { buildReviewUnderstanding } : {}),
         },
       );
     }
@@ -1465,7 +1490,7 @@ export function parseAdminOperation(options) {
   }
 
   throw cliValidationError(
-    "Usage: lumine admin identity|economy|rescue|daily-run|escalation|todo|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|bot-output|notable ...",
+    "Usage: lumine admin identity|economy|rescue|daily-run|escalation|todo|recommendations|builds|post|subjects|subject|featured|comment|announcement|chat|news|audit|brief|ai-costs|media-costs|bot-output|notable ...",
   );
 }
 
@@ -2047,6 +2072,197 @@ function adminValueFingerprint(value) {
   return createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }
 
+function formatAdminUsd(value) {
+  const amount = Number(value);
+  if (!Number.isFinite(amount)) return "unavailable";
+  return `$${amount.toLocaleString("en-US", {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  })}`;
+}
+
+function formatAdminMonthlyCostComparison(projection, previousMonthKey) {
+  const rawPercent = projection?.comparisonToPreviousMonth?.percentChange;
+  const percent = rawPercent === null ? NaN : Number(rawPercent);
+  if (!Number.isFinite(percent)) {
+    return `comparison with ${previousMonthKey} unavailable`;
+  }
+  if (percent === 0) return `even with ${previousMonthKey}`;
+  return `${Math.abs(percent).toFixed(2)}% ${percent < 0 ? "below" : "above"} ${previousMonthKey}`;
+}
+
+function printAdminMonthlyAiCosts(monthlyAiCosts) {
+  const previous = monthlyAiCosts.previousMonth;
+  const current = monthlyAiCosts.currentMonth;
+  const generatedAt = new Date(
+    Number(monthlyAiCosts.generatedAt) * 1000,
+  ).toISOString();
+  console.log(`Application AI-cost ledger (UTC; generated ${generatedAt}).`);
+  console.log(
+    `${previous.monthKey} closed month: ${formatAdminUsd(previous.estimatedCostUsd)} estimated cost.`,
+  );
+  if (current.completed.dayCount > 0) {
+    console.log(
+      `${current.monthKey} completed-day MTD through ${current.completed.throughDayKey}: ${formatAdminUsd(current.completed.estimatedCostUsd)} across ${current.completed.dayCount} completed UTC day(s).`,
+    );
+  } else {
+    console.log(
+      `${current.monthKey} completed-day MTD: ${formatAdminUsd(current.completed.estimatedCostUsd)}; no UTC day has completed yet.`,
+    );
+  }
+  console.log(
+    `${current.inProgressDay.dayKey} in progress: ${formatAdminUsd(current.inProgressDay.estimatedCostUsd)} so far (excluded from completed-day MTD and both projections).`,
+  );
+
+  const allPace = current.projections.allCompletedDaysPace;
+  if (allPace) {
+    console.log(
+      `All-completed-days pace full-month projection: ${formatAdminUsd(allPace.estimatedMonthTotalUsd)} (${formatAdminUsd(allPace.dailyAverageUsd)}/day across ${allPace.basisDayCount} completed day(s); ${formatAdminMonthlyCostComparison(allPace, previous.monthKey)}).`,
+    );
+  } else {
+    console.log(
+      "All-completed-days pace full-month projection: unavailable until one UTC day has completed.",
+    );
+  }
+
+  const recentPace = current.projections.recentSevenCompletedDaysPace;
+  if (recentPace) {
+    console.log(
+      `Recent-seven-completed-day pace full-month projection: ${formatAdminUsd(recentPace.estimatedMonthTotalUsd)} (${formatAdminUsd(recentPace.dailyAverageUsd)}/day from ${recentPace.basisStartDayKey} through ${recentPace.basisEndDayKey}; ${formatAdminMonthlyCostComparison(recentPace, previous.monthKey)}).`,
+    );
+  } else {
+    console.log(
+      "Recent-seven-completed-day pace full-month projection: unavailable until seven UTC days have completed.",
+    );
+  }
+}
+
+function formatAdminMediaUsd(value) {
+  const amount = Number(value);
+  if (!Number.isFinite(amount)) return "unavailable";
+  return `$${amount.toLocaleString("en-US", {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 6,
+  })}`;
+}
+
+function formatAdminMediaBytes(value) {
+  const bytes = Number(value);
+  if (!Number.isFinite(bytes) || bytes < 0) return "unavailable";
+  if (bytes < 1024) return `${Math.floor(bytes)} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let amount = bytes / 1024;
+  let unit = units[0];
+  for (let index = 1; index < units.length && amount >= 1024; index += 1) {
+    amount /= 1024;
+    unit = units[index];
+  }
+  return `${amount.toFixed(amount >= 100 ? 0 : amount >= 10 ? 1 : 2)} ${unit}`;
+}
+
+function printAdminMonthlyMediaCosts(monthlyMediaCosts) {
+  const generatedAt = new Date(
+    Number(monthlyMediaCosts.generatedAt) * 1000,
+  ).toISOString();
+  const current = monthlyMediaCosts.currentMonth;
+  const today = monthlyMediaCosts.currentUtcDay;
+  const operations = monthlyMediaCosts.operations;
+  const streamAttempts = today.streamAttempts || {
+    attemptedCount: 0,
+    reachedLiveCount: 0,
+    endedCount: 0,
+    failedCount: 0,
+    cancelledCount: 0,
+    inProgressCount: 0,
+    failureCodeCounts: [],
+  };
+  console.log(
+    `Lumine media-cost monitor (UTC; ${monthlyMediaCosts.status}; generated ${generatedAt}).`,
+  );
+  console.log(
+    `${current.monthKey}: ${formatAdminMediaUsd(current.estimatedSpentUsd)} settled estimate + ${formatAdminMediaUsd(current.activeReservedUsd)} active reservations + ${formatAdminMediaUsd(current.carryoverUsd)} carryover = ${formatAdminMediaUsd(current.guardedTotalUsd)} guarded of ${formatAdminMediaUsd(current.limitUsd)} (${Number(current.percentUsed).toFixed(2)}% used; ${formatAdminMediaUsd(current.remainingUsd)} remaining).`,
+  );
+  console.log(
+    `${today.dayKey} so far: ${today.reservationsCreated} action(s) reserved, ${today.commitmentsSettled} committed, ${today.cancellationsSettled} cancelled, ${formatAdminMediaUsd(today.estimatedCostSettledUsd)} settled estimate.`,
+  );
+  console.log(
+    `Stream attempts created ${today.dayKey} UTC: ${streamAttempts.attemptedCount} attempted / ${streamAttempts.reachedLiveCount} reached live / ${streamAttempts.endedCount} ended after live / ${streamAttempts.failedCount} failed / ${streamAttempts.cancelledCount} cancelled before live / ${streamAttempts.inProgressCount} still in progress.`,
+  );
+  const streamFailureCodeCounts = Array.isArray(
+    streamAttempts.failureCodeCounts,
+  )
+    ? streamAttempts.failureCodeCounts
+    : [];
+  console.log(
+    streamFailureCodeCounts.length > 0
+      ? `Stream failure codes: ${streamFailureCodeCounts
+          .map((entry) => `${entry.code}=${entry.count}`)
+          .join(", ")}.`
+      : "Stream failure codes: none.",
+  );
+  const stillActiveOrCleanupPendingCount =
+    operations.live.stillActiveOrCleanupPendingCount ??
+    Number(operations.live.provisioningCount || 0) +
+      Number(operations.live.readyCount || 0) +
+      Number(operations.live.liveCount || 0) +
+      Number(operations.live.endingCount || 0) +
+      Number(operations.live.cleanupFailedCount || 0);
+  const replayOperations = operations.replays || {
+    pendingCount: 0,
+    processingCount: 0,
+    readyCount: 0,
+    failedCount: 0,
+    deletePendingCount: 0,
+    deleteFailedCount: 0,
+    expiredReadyCount: 0,
+    finalizationOverdueCount: 0,
+    deletionOverdueCount: 0,
+    storedBytes: 0,
+    storedObjectCount: 0,
+  };
+  const replayViewers = operations.replayViewers || {
+    activeGrantCount: 0,
+    expiredActiveGrantCount: 0,
+  };
+  const kindRows = [
+    ["Short clips", current.byKind.clip],
+    ["Live inputs", current.byKind.liveInput],
+    ["Live viewers", current.byKind.liveViewer],
+  ];
+  if (current.byKind.replayViewer) {
+    kindRows.push(["Replay viewers", current.byKind.replayViewer]);
+  }
+  for (const [label, cost] of kindRows) {
+    console.log(
+      `${label}: ${cost.actionCount} action(s), ${cost.committedCount} committed for ${formatAdminMediaUsd(cost.estimatedSpentUsd)}, ${cost.activeReservedCount} active reservation(s) holding ${formatAdminMediaUsd(cost.activeReservedUsd)}, ${cost.cancelledCount} cancelled.`,
+    );
+  }
+  console.log(
+    `Ledger reconciliation: ${current.reconciliation.consistent ? "consistent" : "MISMATCH"}; spent delta ${formatAdminMediaUsd(current.reconciliation.spentDeltaUsd)}, reserved delta ${formatAdminMediaUsd(current.reconciliation.reservedDeltaUsd)}.`,
+  );
+  console.log(
+    `Operations: clips ${operations.clips.completingCount} completing / ${operations.clips.processingCount} processing / ${operations.clips.staleCount} stale; live ${operations.live.liveCount} broadcasting / ${stillActiveOrCleanupPendingCount} active-or-cleanup-pending / ${operations.live.costBearingChannelCount} cost-bearing channel(s) / ${operations.live.possibleOrphanedCount ?? operations.live.cleanupOverdueCount} possible orphan(s); viewers ${operations.viewers.activeGrantCount} active / ${operations.viewers.expiredActiveGrantCount} expired-active.`,
+  );
+  console.log(
+    `Replays: ${replayOperations.pendingCount} pending / ${replayOperations.processingCount} processing / ${replayOperations.readyCount} ready / ${replayOperations.failedCount} failed / ${replayOperations.deletePendingCount} deleting / ${replayOperations.deleteFailedCount} delete-failed; ${replayOperations.finalizationOverdueCount} finalization-overdue / ${replayOperations.deletionOverdueCount} deletion-overdue / ${replayOperations.expiredReadyCount} expired-ready; ${formatAdminMediaBytes(replayOperations.storedBytes)} across ${replayOperations.storedObjectCount} canonical object(s); viewers ${replayViewers.activeGrantCount} active / ${replayViewers.expiredActiveGrantCount} expired-active.`,
+  );
+  console.log(
+    `Shared runtime storage context: ${operations.runtimeStorage.readyImages.assetCount} ready image(s), ${formatAdminMediaBytes(operations.runtimeStorage.readyImages.totalBytes)}; ${operations.runtimeStorage.readyClips.assetCount} ready clip(s), ${formatAdminMediaBytes(operations.runtimeStorage.readyClips.totalBytes)}. Images include all Build runtime image uploads, not only camera captures.`,
+  );
+  if (monthlyMediaCosts.alerts.length === 0) {
+    console.log("Media-cost alerts: none.");
+  } else {
+    for (const alert of monthlyMediaCosts.alerts) {
+      console.log(
+        `Media-cost alert [${String(alert.severity).toUpperCase()}] ${alert.code}: ${alert.message}`,
+      );
+    }
+  }
+  console.log(
+    "These are conservative provider-cost ledger estimates, not an AWS invoice; reconcile IVS, MediaConvert, replay S3, and shared runtime S3 Cost Explorer data separately after billing lag.",
+  );
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
   if (data.review) {
@@ -2057,6 +2273,14 @@ function printAdminResult({ operation, result }) {
     console.log(`Review receipt: ${data.receiptPath}`);
     return;
   }
+  if (data.monthlyAiCosts) {
+    printAdminMonthlyAiCosts(data.monthlyAiCosts);
+    return;
+  }
+  if (data.monthlyMediaCosts) {
+    printAdminMonthlyMediaCosts(data.monthlyMediaCosts);
+    return;
+  }
   if (data.validation) {
     console.log(
       `Editorial valid for edition #${data.validation.editionId}: ${data.validation.citedEventCount} cited and ${data.validation.coveredEventCount} covered event(s).`,

package/lib/commands.js

@@ -2772,6 +2772,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 ai-costs monthly [--json]
+  lumine admin media-costs monthly [--json]
   lumine admin bot-output [--days <1..30>|--cursor <cursor>] [--json]
   lumine admin announcement post --file <announcement.md> [--json]
   lumine admin chat send <user-id|username> --file <message.md> [--json]

package/lib/constants.js

@@ -115,6 +115,8 @@ export const BUNDLED_SDK_REFERENCE_URL = new URL(
   import.meta.url,
 );
 export const PACKAGE_METADATA_URL = new URL("../package.json", import.meta.url);
+export const LUMINE_WORLD_UPDATE_GUIDANCE = `- For Twinkle.world realtime presence, keep render/input loops local. Queue an update only when relevant state changes, replace any queued snapshot with the newest one, and flush on a fixed 5-15 updates-per-second schedule with at most one updatePresence request in flight. Never call or await updatePresence every animation frame, resend unchanged snapshots, overlap requests, or build a backlog.
+- Send Twinkle.world actions only when the discrete action happens; do not poll or automatically retry them. On WORLD_EVENT_RATE_LIMITED or another recoverable non-session-ended error, drop that attempted presence/action update without an immediate retry and keep the session. Reconnect with backoff only after session.ended or Twinkle.world.isSessionEndedError(error).`;
 export const SDK_REFERENCE_FALLBACK = `${LUMINE_SDK_REFERENCE_MARKER}
 # Twinkle Build SDK Reference
 
@@ -131,6 +133,7 @@ Use these current source-of-truth rules:
 - Use Twinkle.aiStories.list/search/get for existing AI Story passage text, story media, and questions.
 - Use Twinkle.ai.chat with history entries shaped as { role, content }, not { text }. Live web search is enabled by default; pass webSearch: false to disable it for the app.
 - Use Twinkle.preview for canvas, WebGL, Three.js, fullscreen, and game layout.
+${LUMINE_WORLD_UPDATE_GUIDANCE}
 - Prefer existing documented Twinkle.* methods over guessing names from old code.
 `;
 export const LUMINE_THREE_VENDOR_GUIDANCE = `- For Three.js, use the first-party core module: import * as THREE from '${BUILD_VENDOR_THREE_MODULE_IMPORT}';
@@ -285,6 +288,7 @@ lumine save --summary "Describe the change"
 ${LUMINE_THREE_VENDOR_GUIDANCE}
 - Do not invent or guess Twinkle.* SDK method names. Use ${SDK_REFERENCE_FILE} as the local SDK reference and prefer Twinkle.capabilities checks for gated features.
 - Match storage to update frequency. Twinkle.privateDb and Twinkle.sharedDb are for LOW-frequency durable state only — things that change on a user action (settings, inventory checkpoints, completed quests, saved progress; comments, votes, room settings, submitted records). NEVER write high-frequency or per-frame/per-tick state to them (camera or cursor position, animation state, live movement, presence, autosave every frame/tick). Keep live state in client memory, broadcast realtime/presence via Twinkle.world, and for durable per-user state flush an occasional snapshot on an interval or on exit (never per frame) — e.g. the viewer/user DB or a single latest-snapshot key. The server rate-limits these writes per key and returns 429 on excess; never retry-loop a 429.
+${LUMINE_WORLD_UPDATE_GUIDANCE}
 
 ## Local Testing (Playwright / browser probes)
 

package/lib/sdk.js

@@ -100,6 +100,43 @@ export const SDK_CLI_METHODS = {
     write: true,
     sdkReshape: "the SDK returns { success, usage }",
   },
+  "media.getUsage": {
+    path: "api/media/usage",
+    scopes: ["media:read"],
+    sdkReshape: "the SDK returns the mediaEnergy object directly",
+  },
+  "media.getClip": { path: "api/media/clips/status", scopes: ["media:read"] },
+  "media.listClips": { path: "api/media/clips/list", scopes: ["media:read"] },
+  "live.list": {
+    path: "api/live/list",
+    scopes: ["live:read"],
+    sdkReshape: "the SDK returns the sessions array directly",
+  },
+  "live.get": {
+    path: "api/live/status",
+    scopes: ["live:read"],
+    sdkReshape: "the SDK returns the session object directly",
+  },
+  "live.stop": {
+    path: "api/live/stop",
+    scopes: ["live:write"],
+    write: true,
+  },
+  "live.listReplays": {
+    path: "api/live/replays/list",
+    scopes: ["live:read"],
+    sdkReshape: "the SDK returns the replays array directly",
+  },
+  "live.getReplay": {
+    path: "api/live/replays/status",
+    scopes: ["live:read"],
+    sdkReshape: "the SDK returns the replay object directly",
+  },
+  "live.deleteReplay": {
+    path: "api/live/replays/delete",
+    scopes: ["live:write"],
+    write: true,
+  },
   "notifications.getSubscription": { path: "api/notifications/subscription", scopes: ["notifications:read"] },
   "notifications.subscribe": { path: "api/notifications/subscription/subscribe", scopes: ["notifications:write"], write: true },
   "notifications.unsubscribe": { path: "api/notifications/subscription/unsubscribe", scopes: ["notifications:write"], write: true },
@@ -164,6 +201,8 @@ export const SDK_CLI_METHOD_NAMES_BY_PATH = (() => {
 // without --allow-write.
 export const SDK_CLI_READ_SCOPES = [
   "files:read",
+  "media:read",
+  "live:read",
   "user:read",
   "users:read",
   "dailyReflections:read",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.51",
+  "version": "0.2.53",
   "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.37.0
-Updated: 2026-08-25
-Generated: 2026-08-25T02:01:15.207Z
+Version: 1.38.2
+Updated: 2026-08-27
+Generated: 2026-08-27T12:11:09.595Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -26,9 +26,13 @@ Generated: 2026-08-25T02:01:15.207Z
 - Live web search is enabled by default for Twinkle.ai.chat and for Medium/High Twinkle.ai.generateObject and Twinkle.characters.chat requests. App authors can pass webSearch: false to disable it for their app. Search uses the provider's live web-search tool and is included in AI Energy usage; structured and character Lite Mode remains tool-free.
 - Interface text must not be selectable on touch devices: apply user-select: none plus -webkit-user-select: none and -webkit-touch-callout: none to interface text (HUD, buttons, labels, menus, scores, game controls) so mobile long-press does not highlight UI. Keep text inputs and genuinely user-copyable content selectable.
 - Build app tab mute is enforced by the host runtime automatically for standard media elements and Web Audio connections to AudioContext.destination. Apps with custom audio engines can also observe Twinkle.onAudioMuteChange and check Twinkle.isAudioMuted.
+- Use Twinkle.media for camera photos and camera-only two-second clips. Twinkle confirms each capture or paid processing action. Clips are processed to canonical 480p MP4 assets before they become visible; use sharedDb or privateDb to publish/store the returned asset metadata.
+- Static media published through sharedDb is app-owned feed data. A public user-generated feed must provide a visible report flow and owner removal, and must not claim that Twinkle globally moderates those posts.
+- Use Twinkle.live for one-way app livestreams and Twinkle.chat for the accompanying thread. Free livestreams require a verified host, end after at most 15 minutes, and issue at most 10 private viewer grants. Twinkle keeps platform-owned live-status/end controls above active hosts, so app code cannot hide or replace the broadcaster's Stop path.
+- Media Energy is separate from AI Energy. Replace Media Energy UI only from canonical mediaEnergy/getUsage responses; never decrement, reserve, or synthesize it in app code.
 
 ## Token Scopes
-files:read, 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
+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
 
 ## Namespaces
 
@@ -282,7 +286,7 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
   - Simple visible same-origin images can still use normal browser anchors with href and download.
   - Example: await Twinkle.files.saveAs({ fileName: 'fashion-guide.png', dataUrl: imageUrl, mimeType: 'image/png' });
 - async uploadGenerated({ fileName, url, dataUrl, data, text, json, bytes, blob, file, mimeType } = {}) | scopes: files:write
-  - Returns: { assets: [{ id, buildId, fileName, originalFileName, mimeType, sizeBytes, filePath, url, thumbUrl, fileType, uploadedByUserId, createdAt }], failed?: [{ fileName, message }], canceled }
+  - Returns: { assets: [{ id, buildId, fileName, originalFileName, mimeType, sizeBytes, filePath, url, thumbUrl, fileType, mediaKind, durationMs, uploadedByUserId, createdAt }], failed?: [{ fileName, message }], canceled }
   - Upload an app-generated file to Twinkle-hosted cloud storage without opening a picker, then store the returned asset refs in sharedDb/privateDb/userDb.
   - Signed-in viewers only.
   - Uploads generated blobs, files, bytes, data URLs, or fetchable URLs to Twinkle-hosted cloud storage.
@@ -290,7 +294,7 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
   - Store the returned asset metadata in sharedDb/privateDb/userDb instead of storing raw file bytes in a DB record.
   - Example: const { assets } = await Twinkle.files.uploadGenerated({ fileName: 'fashion-guide.png', dataUrl: generatedImageUrl, mimeType: 'image/png' });
 - async pickAndUpload({ accept, multiple } = {}) | scopes: files:write
-  - Returns: { assets: [{ id, buildId, fileName, originalFileName, mimeType, sizeBytes, filePath, url, thumbUrl, fileType, uploadedByUserId, createdAt }], failed?: [{ fileName, message }], canceled }
+  - Returns: { assets: [{ id, buildId, fileName, originalFileName, mimeType, sizeBytes, filePath, url, thumbUrl, fileType, mediaKind, durationMs, uploadedByUserId, createdAt }], failed?: [{ fileName, message }], canceled }
   - Pick supported local files and upload them to Twinkle-hosted cloud storage, then store the returned asset refs in sharedDb/privateDb/userDb.
   - Signed-in viewers only.
   - Uploads to Twinkle-hosted cloud storage and returns asset references.
@@ -299,7 +303,7 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
   - Store the returned asset metadata in sharedDb/privateDb/userDb instead of storing raw file bytes in a DB record.
   - Example: const { assets, canceled } = await Twinkle.files.pickAndUpload({ accept: 'image/*,.pdf', multiple: true });
 - async list({ cursor, limit } = {}) | scopes: files:read
-  - Returns: { assets: [{ id, buildId, fileName, originalFileName, mimeType, sizeBytes, filePath, url, thumbUrl, fileType, uploadedByUserId, createdAt }], nextCursor, usage: { totalBytes, fileCount, maxRuntimeFileStorageBytes, remainingBytes } | null }
+  - Returns: { assets: [{ id, buildId, fileName, originalFileName, mimeType, sizeBytes, filePath, url, thumbUrl, fileType, mediaKind, durationMs, uploadedByUserId, createdAt }], nextCursor, usage: { totalBytes, fileCount, maxRuntimeFileStorageBytes, remainingBytes } | null }
   - List the current viewer's uploaded runtime files for this build.
   - Signed-in viewers only.
   - Lists the current viewer's ready uploads for this build only.
@@ -311,6 +315,117 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
   - Deletes one of the current viewer's uploaded runtime files and updates quota usage.
   - Example: await Twinkle.files.delete(assetId);
 
+### Twinkle.media
+- async capturePhoto({ facingMode?, maxWidth?, quality?, settleMs?, fileName? } = {}) | scopes: files:write
+  - Returns: { asset, assets, failed }
+  - Ask for camera permission, capture one JPEG photo, and upload it to the current viewer's Twinkle file storage.
+  - Signed-in viewers only. Call from an explicit viewer action; Twinkle shows its own one-action confirmation before the browser may show camera permission.
+  - The photo is saved in the viewer's Twinkle file storage. The returned asset is canonical server state and can be stored in sharedDb/privateDb/userDb.
+  - Example: const { asset } = await Twinkle.media.capturePhoto({ facingMode: 'user' });
+if (asset) await Twinkle.sharedDb.addEntry('photos', asset);
+- async recordClip({ previewElement?, facingMode?, fileName?, waitForReady?, timeoutMs? } = {}) | scopes: media:write
+  - Returns: { clip: { id, status, durationMs, failureCode, asset }, mediaEnergy }
+  - Record a camera-only short video, upload it, and by default wait for the canonical two-second 480p MP4 asset.
+  - Call from an explicit viewer action. Twinkle confirms each recording before requesting camera permission.
+  - The recording is camera-only; use Twinkle.live when audio is part of the experience.
+  - The server targets a two-second maximum input window and processes it to 480p MP4. Encoder frame boundaries can differ by one frame; app code cannot raise the limit.
+  - By default this method polls confirmed server state until ready. Pass waitForReady: false to receive the processing ID immediately, then call getClip().
+  - Example: const { clip } = await Twinkle.media.recordClip({ previewElement: '#cameraPreview' });
+await Twinkle.sharedDb.addEntry('clips', clip.asset);
+- async uploadClip({ file?, blob?, fileName?, mimeType?, requestId?, waitForReady?, timeoutMs? }) | scopes: media:write
+  - Returns: { clip: { id, status, durationMs, failureCode, asset }, mediaEnergy }
+  - Upload a generated or selected video through the same server-bounded two-second clip pipeline.
+  - Call from an explicit viewer action. Twinkle confirms each selected or generated video before upload and paid processing.
+  - Input is limited to 8 MB. The canonical output is a server-produced 480p MP4 targeting a two-second maximum, with at most a frame of encoder-boundary variance.
+  - Use a stable requestId when retrying the same user action.
+  - Example: const result = await Twinkle.media.uploadClip({ file: recordedFile });
+- async getClip(assetId) | scopes: media:read
+  - Returns: { clip: { id, status, durationMs, failureCode, asset }, mediaEnergy }
+  - Load and reconcile canonical processing state for one of the current viewer's clips.
+  - Example: const { clip } = await Twinkle.media.getClip(assetId);
+- async listClips({ cursor?, limit? } = {}) | scopes: media:read
+  - Returns: { assets, nextCursor, mediaEnergy }
+  - List the current viewer's ready short clips for this Build app.
+  - Example: const { assets } = await Twinkle.media.listClips({ limit: 20 });
+- async getUsage() | scopes: media:read
+  - Returns: { monthKey, resetsAt, global, user, build, energyPercent, energySegments, energySegmentsRemaining }
+  - Load canonical current Media Energy for this viewer and app.
+  - Replace displayed state only from this response or a newer mediaEnergy response. Never decrement or synthesize the battery locally.
+  - global.carryoverMicroUsd accounts for reservations that crossed the UTC month boundary so the global reset cannot double the budget.
+  - Example: const mediaEnergy = await Twinkle.media.getUsage();
+renderBattery(mediaEnergy.energyPercent);
+
+### Twinkle.live
+- async start({ previewElement?, facingMode?, audio?, durationSeconds?, maxViewers?, saveReplay?, requestId? } = {}) | scopes: live:write
+  - Returns: { session: { id, replayId, buildId, hostUserId, status, maxViewers, viewersGranted, durationSeconds, saveReplay, updatedAt, hardEndsAt }, mediaEnergy }
+  - Create an IVS channel, attach the camera/microphone, begin broadcasting, and optionally save a seven-day replay.
+  - Call from an explicit viewer action. Twinkle confirms each new broadcast before camera/microphone permission or paid channel creation.
+  - saveReplay defaults to false. When true, the same action confirmation says the stream will be saved, and Twinkle records it to private storage for seven days after it becomes ready.
+  - Replay storage is included in the live Media Energy reservation. Replay viewing has its own Media Energy reservation.
+  - previewElement must be a canvas element or selector because the IVS Broadcast SDK draws a composited preview.
+  - Free sessions broadcast at 854x480 and are capped server-side at 15 minutes and 10 private viewer grants. Lower durationSeconds/maxViewers values are allowed.
+  - Twinkle confirms that a platform-owned live indicator and End stream action are present before returning broadcast credentials to the app, and keeps the control until server cleanup is canonically terminal. Fullscreen and Picture-in-Picture are unavailable while hosting so that Stop control stays visible.
+  - The SDK does not include broadcast credentials in its returned value. Credentials are ephemeral, and the SDK stops local broadcasting at hardEndsAt while the API independently stops and deletes the IVS channel.
+  - Example: const { session } = await Twinkle.live.start({ previewElement: '#broadcastPreview', audio: true });
+await Twinkle.sharedDb.setKvItems('live', [{ key: 'current', value: session }]);
+- async list() | scopes: live:read
+  - Returns: Array<LiveSession>
+  - List currently available livestream sessions for this Build app.
+  - Only sessions canonically acknowledged as live are listed; channels still being prepared are never advertised to viewers.
+  - Example: const sessions = await Twinkle.live.list();
+- async get(sessionId) | scopes: live:read
+  - Returns: LiveSession | null
+  - Load canonical server status for a livestream in this Build app.
+  - Example: const session = await Twinkle.live.get(sessionId);
+- async watch(sessionId, { videoElement, requestId? }) | scopes: live:write
+  - Returns: { session, viewerGrantId, mediaEnergy, playbackStarted }
+  - Use a private single-use playback grant to attach a livestream to an HTML video element.
+  - Call from an explicit viewer action. Twinkle confirms admission before allocating the private viewer grant or using Media Energy.
+  - The first watch action consumes one of at most 10 grants for the session. Repeated watch() calls in the same page reuse the local grant until leave().
+  - Playback authorization is single-use and capped at SD. The watch() result omits the signed playback URL; bridge traffic is still app-visible and must be treated as ephemeral.
+  - playbackStarted becomes true only after IVS or the HTML video element confirms a playing state. If browser autoplay is blocked or no playing state is confirmed, it is false and the video controls remain available so the viewer can start playback explicitly.
+  - Viewers may use the video element's ordinary fullscreen and Picture-in-Picture controls.
+  - Example: await Twinkle.live.watch(session.id, { videoElement: '#liveVideo' });
+- async leave(sessionId) | scopes: live:write
+  - Returns: { success }
+  - Destroy the local player and revoke/settle its private viewer session.
+  - Example: await Twinkle.live.leave(sessionId);
+- async stop(sessionId) | scopes: live:write
+  - Returns: { session, cleanupInProgress, mediaEnergy }
+  - Stop local broadcasting and ask the server to stop and delete the host's ephemeral IVS channel.
+  - Use the returned canonical session state. Do not locally synthesize an ended status.
+  - Example: await Twinkle.live.stop(sessionId);
+- async listReplays({ limit? } = {}) | scopes: live:read
+  - Returns: Array<LiveReplay>
+  - List canonical saved replays for this Build app.
+  - Ready, unexpired replays are visible to viewers in the app. A creator can also see processing or failed state for their own opted-in stream.
+  - Replays expire seven days after becoming ready. Replace displayed state from this canonical response; do not synthesize processing or ready state locally.
+  - Example: const replays = await Twinkle.live.listReplays({ limit: 20 });
+- async getReplay(replayId) | scopes: live:read
+  - Returns: LiveReplay | null
+  - Load canonical processing, ready, or failed state for a visible replay.
+  - Only the creator can see a processing or failed replay; ready replays are visible to signed-in viewers in this app.
+  - Example: const replay = await Twinkle.live.getReplay(replayId);
+- async watchReplay(replayId, { videoElement, requestId? }) | scopes: live:write
+  - Returns: { replay, viewerGrantId, mediaEnergy, playbackStarted }
+  - Open a short-lived private playback grant and attach a saved replay to an HTML video element.
+  - Call from an explicit viewer action. Twinkle confirms each playback grant before using Media Energy.
+  - Admission reserves the replay's maximum delivery estimate; leave, page close, or playback end settles the canonical elapsed viewing window instead of charging unused playback time.
+  - The grant lasts at most 20 minutes and is settled automatically when playback ends, on leaveReplay(), when the page closes, or at server expiry.
+  - playbackStarted becomes true only after IVS or the HTML video element confirms a playing state. If browser autoplay is blocked or no playing state is confirmed, it is false and the video controls remain available so the viewer can start playback explicitly.
+  - Viewers may use the video element's ordinary fullscreen and Picture-in-Picture controls.
+  - Example: await Twinkle.live.watchReplay(replay.id, { videoElement: '#replayVideo' });
+- async leaveReplay(replayId) | scopes: live:write
+  - Returns: { success }
+  - Destroy the local replay player and canonically settle its private viewer grant.
+  - The returned canonical settlement charges the conservative elapsed playback estimate, capped by the replay duration.
+  - Example: await Twinkle.live.leaveReplay(replayId);
+- async deleteReplay(replayId, { requestId? } = {}) | scopes: live:write
+  - Returns: { replay, cleanupInProgress, mediaEnergy }
+  - Permanently remove an opted-in replay through the canonical private-storage cleanup path.
+  - Twinkle asks for an action-specific confirmation. Use the canonical returned state; cleanupInProgress means provider recording finalization or deletion is still being confirmed.
+  - Example: await Twinkle.live.deleteReplay(replayId);
+
 ### Twinkle.ai
 - async getUsagePolicy() | scopes: none
   - Returns: BuildAiUsagePolicy | null
@@ -341,7 +456,7 @@ 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 generateObject({ prompt, expectedStructure, thinkingMode, mode, model, instructions, systemPrompt, webSearch, requestId, onText, onStatus } = {}) | scopes: none
+- 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.
   - Signed-in viewers only.
@@ -353,13 +468,14 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - thinkingMode medium uses Grok 4.6 with medium reasoning and consumes normal AI Energy.
   - thinkingMode high without model uses GPT-5.6 Sol with high reasoning and consumes high AI Energy. Explicit model: 'gpt-5.6-sol' selects Sol with xhigh reasoning at the same High AI Energy tier.
   - claude-opus-5 uses Anthropic adaptive High thinking. claude-fable-5 uses Anthropic xhigh thinking and normally consumes more AI Energy for comparable token use. Both debit confirmed provider usage at the High tier.
-  - Pass onStatus and/or onText to stream progress from the same structured generation. onStatus receives high-level phases such as thinking, searching_web, responding, validating, and completed.
+  - Pass onStatus, onReasoning, and/or onText to stream progress from the same structured generation. onStatus receives high-level phases such as thinking, searching_web, responding, validating, and completed.
+  - onReasoning receives accumulated provider-supplied, app-visible reasoning summaries plus { done, delta, requestId, status }. A provider retry may replace the accumulated summary; treat each callback's first argument as the current source of truth. This callback never exposes hidden/private model chain-of-thought.
   - onText receives accumulated structured-output text plus { done, delta, requestId, status }. Partial output is intentionally incomplete and may include provider formatting; parse only when done is true, when the callback receives the canonical object serialized as JSON, and use the resolved object as the source of truth.
-  - Streaming exposes app-visible structured output and high-level phases, not private model chain-of-thought. Put a user-facing field such as producerNotes in expectedStructure when the app should display model-authored commentary from the same generation.
+  - Put a user-facing field such as producerNotes in expectedStructure when commentary must be part of the validated final object rather than transient reasoning progress.
   - When AI Energy is empty, every automatic or named model choice rejects before new provider work; there is no free fallback mode.
   - Live web search is enabled by default in Medium and High modes. Pass webSearch: false to disable it for the app. Low/Lite Mode remains tool-free; explicitly forcing webSearch: true in Low Mode returns an error.
-  - The server validates the final shape; automatic OpenAI/xAI routes can retry malformed output, while explicit Anthropic routes use native JSON Schema output. App code should still validate business-specific enum values.
-  - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'high', model: 'claude-opus-5', prompt: 'Plan the next section from: ' + currentState, expectedStructure: { producerNotes: 'string', action: 'string', confidence: 0 }, onStatus: (phase) => showPhase(phase), onText: (partialJson, meta) => showStructuredProgress(partialJson, meta) });
+  - The server validates the final shape; automatic OpenAI/xAI routes can retry malformed output, while explicit Anthropic routes use native JSON Schema output and retry one malformed or shape-invalid result. App code should still validate business-specific enum values.
+  - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'high', model: 'claude-opus-5', prompt: 'Plan the next section from: ' + currentState, expectedStructure: { producerNotes: 'string', action: 'string', confidence: 0 }, onStatus: (phase) => showPhase(phase), onReasoning: (summary, meta) => showReasoningProgress(summary, meta), onText: (partialJson, meta) => showStructuredProgress(partialJson, meta) });
 - onChatStatus(listener) | scopes: none
   - Returns: unsubscribe function
   - Listen to shared runtime AI chat stream events.
@@ -742,7 +858,8 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Signed-in player identity comes from the canonical Twinkle user record; player.profilePicUrl is only used for guests and is returned only when it is a valid absolute HTTPS URL.
   - Subscribe to session.ended and catch updatePresence/send errors. Stop using stale handles and reconnect only when Twinkle.world.isSessionEndedError(error) is true; for other Twinkle.world.isRecoverableSessionError(error) cases, drop the transient presence/action and keep the handle.
   - Use updatePresence for live avatar snapshots and send for lightweight actions such as emotes, interactions, and chat bubbles.
-  - Throttle movement updates in app code, usually 5-15 updates per second. Do not call updatePresence from every animation frame.
+  - Treat the render/input loop as local-only. Queue presence only after relevant fields change, replace any queued snapshot with the newest one, and flush on a fixed 5-15 updates-per-second schedule with at most one updatePresence request in flight. Never call or await updatePresence every animation frame, resend unchanged snapshots, overlap requests, or build a backlog.
+  - Send discrete actions only when they happen; do not poll or automatically retry them. The parent limits updatePresence and send together to protect the website connection. WORLD_EVENT_RATE_LIMITED is recoverable: drop that attempted update without an immediate retry and keep the current session.
   - Rooms are addressed by worldKey, roomKey, and instanceId so the contract can later move to sharded or dedicated game backends.
   - Example: const world = await Twinkle.world.join({ roomKey: 'town-square', presence: { x: 0, y: 0, z: 0, facing: 'south' }, player: { name: avatarName } });
 world.subscribe((event) => updateRemotePlayers(event.players));
@@ -750,8 +867,8 @@ world.updatePresence({ x, y, z, facing });
 - isRecoverableSessionError(error) | scopes: none
   - Returns: boolean
   - Return true when a world request error is expected to be handled by app code instead of crashing.
-  - Recoverable session errors include ended, missing, socket-disconnected, socket-not-ready, room-missing, preview-updating, and timed-out world session requests.
-  - Only session-ended errors prove that the current handle should be discarded. Timed-out or preview-updating presence requests can be dropped without reconnecting.
+  - Recoverable session errors include ended, missing, socket-disconnected, socket-not-ready, room-missing, rate-limited, preview-updating, and timed-out world session requests.
+  - Only session-ended errors prove that the current handle should be discarded. WORLD_EVENT_RATE_LIMITED, timed-out, or preview-updating presence/action requests must be dropped without reconnecting and without an immediate retry.
   - For durable game state, write through sharedDb/privateDb instead of relying on world presence — but LOW-frequency only (on a user action or an occasional snapshot, never per frame/tick).
   - Example: try {
   await world.updatePresence({ x, y, z, facing });
@@ -1028,59 +1145,104 @@ Keywords: multiplayer, mmo, town, presence, avatars, movement, three.js, realtim
 
 ```js
 let world = null;
+let worldConnection = null;
 let reconnectTimer = 0;
+let reconnectDelayMs = 1000;
+let latestPresence = { x: 0, y: 0, z: 0, facing: 'south', animation: 'idle' };
+let latestPresenceKey = JSON.stringify(latestPresence);
+let queuedPresence = null;
+let presenceInFlight = false;
 
 async function connectWorld() {
   if (world) return world;
-  world = await Twinkle.world.join({
-    worldKey: 'town',
-    roomKey: 'square',
-    presence: { x: 0, y: 0, z: 0, facing: 'south', animation: 'idle' },
+  if (worldConnection) return worldConnection;
+  const presenceAtJoin = latestPresence;
+  const presenceKeyAtJoin = latestPresenceKey;
+  worldConnection = Twinkle.world.join({
+    worldKey: 'town', roomKey: 'square', presence: presenceAtJoin,
     player: { name: avatarName }
   });
+  try {
+    const session = await worldConnection;
+    world = session;
+    reconnectDelayMs = 1000;
+    session.subscribe((event) => {
+      renderPlayers(event.players);
+      if (event.type === 'session.ended') handleWorldDrop(session);
+      if (event.type === 'action.received' && event.action?.type === 'emote') {
+        showEmote(event.sessionId, event.action.data.emote);
+      }
+    });
+    if (latestPresenceKey !== presenceKeyAtJoin) queuedPresence = latestPresence;
+    return session;
+  } finally {
+    worldConnection = null;
+  }
+}
 
-  world.subscribe((event) => {
-    renderPlayers(event.players);
-    if (event.type === 'session.ended') {
-      handleWorldDrop();
-    }
-    if (event.type === 'action.received' && event.action?.type === 'emote') {
-      showEmote(event.sessionId, event.action.data.emote);
-    }
-  });
-  return world;
+function handleWorldConnectError(error) {
+  if (Twinkle.world.isRecoverableSessionError(error)) {
+    scheduleReconnect();
+  } else {
+    console.error('World connection failed', error);
+  }
 }
 
-function handleWorldDrop() {
+function scheduleReconnect() {
+  if (reconnectTimer || world || worldConnection) return;
+  const delay = reconnectDelayMs;
+  reconnectDelayMs = Math.min(30000, reconnectDelayMs * 2);
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = 0;
+    connectWorld().catch(handleWorldConnectError);
+  }, delay);
+}
+
+function handleWorldDrop(session = world) {
+  if (session && world && world !== session) return;
   world = null;
-  if (!reconnectTimer) {
-    reconnectTimer = setTimeout(() => {
-      reconnectTimer = 0;
-      connectWorld().catch(handleWorldDrop);
-    }, 1000);
-  }
+  queuedPresence = null;
+  scheduleReconnect();
+}
+
+function queuePresence(next) {
+  const key = JSON.stringify(next);
+  if (key === latestPresenceKey) return;
+  latestPresenceKey = key;
+  latestPresence = next;
+  if (world) queuedPresence = next; // Coalesce to the newest unsent snapshot.
 }
 
-async function syncPresence() {
+async function flushPresence() {
+  if (presenceInFlight || !queuedPresence || !world) return;
+  const session = world;
+  const next = queuedPresence;
+  queuedPresence = null;
+  presenceInFlight = true;
   try {
-    const session = await connectWorld();
-    // Throttle this in the game loop, for example 5-15 times per second.
-    await session.updatePresence({ x: player.x, y: player.y, z: player.z, facing });
+    await session.updatePresence(next);
   } catch (error) {
     if (Twinkle.world.isSessionEndedError(error)) {
-      handleWorldDrop();
-      return;
+      handleWorldDrop(session);
+    } else if (!Twinkle.world.isRecoverableSessionError(error)) {
+      console.error('World update failed', error);
     }
-    if (Twinkle.world.isRecoverableSessionError(error)) {
-      // Drop this transient presence update and keep the current handle.
-      return;
-    }
-    throw error;
+    // Recoverable errors drop this transient snapshot without an immediate retry.
+  } finally {
+    presenceInFlight = false;
   }
 }
 
-await connectWorld();
-await syncPresence();
+// The render/input loop only queues changed local state.
+function onPlayerStateChanged() {
+  queuePresence({
+    x: player.x, y: player.y, z: player.z,
+    facing, animation: player.animation
+  });
+}
+
+connectWorld().catch(handleWorldConnectError);
+setInterval(() => { void flushPresence(); }, 100); // Fixed 10 Hz cap.
 ```
 
 ### Play chess against the computer

package/sdk/LUMINE_ADMIN.md

@@ -740,10 +740,7 @@ type AdminTodo = {
 
 type AdminTodoList = Success<{
   todos: AdminTodo[];
-  statusFilter:
-    | "pending"
-    | "all"
-    | AdminTodo["status"];
+  statusFilter: "pending" | "all" | AdminTodo["status"];
   truncated: boolean;
 }>;
 
@@ -1700,6 +1697,8 @@ A run report that skipped the conduct review is incomplete.
 ```bash
 lumine admin brief --json
 lumine admin brief --days 3 --json
+lumine admin ai-costs monthly --json
+lumine admin media-costs monthly --json
 lumine admin notable add 12647 --note "Top authored-activity kid of the window: 11 subjects, 61 comments." --json
 lumine admin notable add Minecrarft_guy --note "Helped three new builders debug their projects and gave detailed feedback on five posts." --json
 ```
@@ -1711,6 +1710,231 @@ 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.
 
+### Application AI calendar-month cost (standing duty, every run)
+
+Run `lumine admin ai-costs monthly --json` during every website-management
+run. This read-only command requires the active delegated run and returns one
+server-owned calendar summary from the canonical deduplicated application AI-
+cost ledger. It deliberately takes no `--days`: all boundaries are UTC calendar
+months, so the result is directly comparable from one run to the next.
+
+The previous month is a closed-calendar-month estimated total. Current-month
+MTD contains only completed UTC days and names its inclusive `throughDayKey`.
+The current UTC day's still-filling bucket is returned separately as
+`inProgressDay`; **never add it to MTD or either projection**. A missing daily
+aggregate inside the covered calendar is a recorded zero-cost day, not a
+reason to shrink the denominator.
+
+Two clearly different full-month projections are returned:
+
+- `allCompletedDaysPace` retains completed-day spend, then applies the average
+  across every completed calendar day (including recorded zero days) to the
+  current and remaining UTC days;
+- `recentSevenCompletedDaysPace` retains completed-day spend, then applies the
+  average of the latest seven completed UTC days to the current and remaining
+  days. It is `null` until seven days have completed.
+
+Both projections exclude the partial day's actual cost, replace every not-yet-
+completed day with their stated daily pace, and compare their projected total
+with the previous closed month. They are run-rate scenarios, not forecasts
+from a billing provider. All ledger values are pricing-based estimates rather
+than invoices and can change if canonical usage attribution or pricing is
+corrected.
+
+The stable JSON payload is `data.monthlyAiCosts`:
+
+```ts
+type MonthlyAiCosts = {
+  schemaVersion: 1;
+  generatedAt: number; // Unix seconds
+  timezone: "UTC";
+  currency: "USD";
+  source: {
+    basis: "canonical_deduplicated_ai_cost_report";
+    reportDays: number;
+    reportStartDayIndex: number;
+    reportEndDayIndex: number;
+    mtdIncludesInProgressDay: false;
+    projectionsIncludeInProgressDayActual: false;
+  };
+  previousMonth: {
+    status: "closed";
+    monthKey: string; // YYYY-MM
+    startDayKey: string;
+    endDayKeyExclusive: string;
+    calendarDayCount: number;
+    estimatedCostUsd: number;
+  };
+  currentMonth: {
+    status: "in_progress";
+    monthKey: string;
+    startDayKey: string;
+    endDayKeyExclusive: string;
+    calendarDayCount: number;
+    completed: {
+      dayCount: number;
+      throughDayKey: string | null;
+      estimatedCostUsd: number;
+      dailyAverageUsd: number | null;
+    };
+    inProgressDay: {
+      dayIndex: number;
+      dayKey: string;
+      estimatedCostUsd: number;
+      eventCount: number;
+      requestCount: number;
+    };
+    daysToEstimate: number;
+    projections: {
+      allCompletedDaysPace: MonthlyAiCostProjection | null;
+      recentSevenCompletedDaysPace: MonthlyAiCostProjection | null;
+    };
+  };
+};
+
+type MonthlyAiCostProjection = {
+  basis: "all_completed_days" | "recent_7_completed_days";
+  basisStartDayKey: string;
+  basisEndDayKey: string;
+  basisDayCount: number;
+  dailyAverageUsd: number;
+  remainingDayCount: number;
+  estimatedMonthTotalUsd: number;
+  comparisonToPreviousMonth: {
+    estimatedCostDeltaUsd: number;
+    percentChange: number | null; // null when the prior total is zero
+  };
+};
+```
+
+Release boundary: `/cli/admin/ai-costs/monthly` and all calendar math are API-
+owned. Deploy and verify the compatible `twinkle-api` route before publishing
+or installing the Lumine CLI release that invokes it; an older API will reject
+the new command instead of synthesizing figures locally.
+
+### Lumine media feature cost and cleanup watch (standing duty, every run)
+
+Run `lumine admin media-costs monthly --json` during every website-management
+run. This read-only, delegated-run-gated command reports the canonical Media
+Energy ledger for short clips, livestream input/viewer usage, and replay
+storage/viewing. Include in
+**"Insights for Mikey"** on every run:
+
+- current-month settled estimated cost, active reservations, cross-month
+  carryover, guarded total, global limit, remaining headroom, and percent used;
+- the current UTC day's reservations, settlements, cancellations, and settled
+  estimated cost;
+- the current UTC day's privacy-safe stream-attempt cohort: attempted,
+  reached-live, ended-after-live, failed, cancelled-before-live, still in
+  progress, and grouped server failure-code counts;
+- clip, live-input, live-viewer, and replay-viewer action/cost breakdowns;
+- whether the global usage row reconciles exactly with reservation rows;
+- every returned alert, plus incomplete clip jobs, cost-bearing IVS channels,
+  active-or-cleanup-pending sessions, possible orphaned sessions, overdue
+  cleanup, replay finalization/deletion state, retained replay bytes/objects,
+  and expired-active live or replay viewer grants;
+- ready image/clip storage counts and bytes as scale context.
+
+Treat `status: "critical"`, any reconciliation mismatch, overdue IVS cleanup,
+or overdue replay finalization/deletion as an operational incident to
+investigate in the same run. Treat
+`status: "attention"` as a required finding, not a decorative warning. The
+server's request-time global Media Energy guardrail defaults to **$40/month**;
+the separate AWS Budget is **$50/month**, leaving provider-billing and shared-
+infrastructure headroom. Never infer or locally decrement either value.
+
+The ledger is the immediate application source of truth and deliberately uses
+conservative provider-cost estimates. It is not an AWS invoice. Photo capture
+uses existing Build runtime file storage rather than the paid Media Energy
+ledger; `operations.runtimeStorage.readyImages` therefore reports all ready
+Build runtime images, not camera captures alone. Reconcile delayed AWS
+MediaConvert and IVS service charges every run as described below. S3 is shared
+with other Twinkle uploads, so report its service-level cost as shared context,
+not as photo-only spend.
+
+Release boundary: `/cli/admin/media-costs/monthly` owns the canonical ledger,
+reconciliation, resource-state checks, and alerts. Deploy and verify that API
+route before publishing or installing the Lumine CLI release that invokes it.
+
+`currentUtcDay.streamAttempts` is a `createdAt` cohort for that UTC day. Its
+outcomes partition every attempt into `endedCount` (reached live, then ended),
+`failedCount` (failed or cleanup-failed), `cancelledCount` (ended before ever
+reaching live), or `inProgressCount`; `reachedLiveCount` is the overlapping
+milestone count. `failureCodeCounts` contains only server-defined codes and
+counts—never usernames, Build ids, titles, viewer identities, or report
+identities. `operations.live.stillActiveOrCleanupPendingCount` and
+`possibleOrphanedCount` are current global counts, not members of the daily
+cohort.
+
+Replay storage and write cost is conservatively embedded in an opted-in
+`live-input` reservation; `replay-viewer` is a separate kind. Report
+`operations.replays` (pending, processing, ready, failed, deleting,
+delete-failed, overdue finalization/deletion, expired-ready, bytes, and object
+count) and `operations.replayViewers` on every run. A replay finalization or
+deletion alert is an operational incident because private recording cleanup is
+part of the feature contract.
+
+### AWS monthly bill expectation (standing duty, every run)
+
+Starting 2026-08-27, every website-management run must also check AWS Cost
+Explorer and include the current calendar month's expected AWS bill in
+**"Insights for Mikey"**. This is an account-level infrastructure cost check,
+not the `aiSpending` application-cost section above; never substitute one for
+the other or combine their totals.
+
+First verify the Twinkle AWS principal exactly as required by the repository
+agent guide. Use profile `mikey-iam`, pass an explicit region on every command,
+and stop rather than reading another account if the ARN is not
+`arn:aws:iam::019490893667:user/twinkle-admin`:
+
+```bash
+aws sts get-caller-identity --profile mikey-iam --region us-east-1
+```
+
+Then use UTC calendar boundaries and Cost Explorer's unblended-cost metric.
+`End` is exclusive: the month-to-date query below covers completed dates before
+`<today-UTC>`. On the first UTC day of a month, report that no completed-day MTD
+period exists instead of sending an empty interval.
+
+```bash
+aws ce get-cost-and-usage --profile mikey-iam --region us-east-1 \
+  --time-period Start=<month-start-YYYY-MM-01>,End=<today-UTC> \
+  --granularity MONTHLY --metrics UnblendedCost
+
+aws ce get-cost-and-usage --profile mikey-iam --region us-east-1 \
+  --time-period Start=<month-start-YYYY-MM-01>,End=<today-UTC> \
+  --granularity MONTHLY --metrics UnblendedCost \
+  --group-by Type=DIMENSION,Key=SERVICE
+
+aws ce get-cost-forecast --profile mikey-iam --region us-east-1 \
+  --time-period Start=<today-UTC>,End=<next-month-YYYY-MM-01> \
+  --metric UNBLENDED_COST --granularity DAILY \
+  --prediction-interval-level 80
+```
+
+Report the Cost Explorer snapshot date, currency, estimated MTD amount and its
+through-date, plus the returned **remaining-period** forecast mean and 80%
+lower/upper bounds. Verify that the first and last returned daily periods cover
+exactly the requested `Start`-inclusive, `End`-exclusive interval before doing
+any arithmetic; reject or separately explain a response with expanded or
+missing dates. Calculate the expected full-calendar-month mean and bounds by
+adding completed-day MTD to the sums of the returned daily mean, lower, and
+upper values. Do not use monthly granularity for this mid-month remainder:
+Cost Explorer can return the whole calendar month even when the requested
+start is mid-month, and adding MTD to that result would double-count. This
+split deliberately forecasts the current UTC day instead of mixing its
+incomplete actual into MTD. Label current-month actuals
+when `Estimated` is true, and describe the result as a Cost Explorer expectation
+rather than a final invoice because reporting lags and later credits, refunds,
+taxes, or adjustments can change the bill. If either the forecast or MTD query
+is unavailable, report the available component and say why a complete
+full-month expectation is unavailable instead of extrapolating it locally. A
+previous closed month may be quoted for context when the difference is
+material, but it is not a replacement for the current-month expectation.
+For the media watch, separately identify AWS Elemental MediaConvert and Amazon
+Interactive Video Service rows when present. Also report Amazon S3 as shared
+storage context, without attributing the whole S3 row to Lumine media.
+
 Ten sections (Mikey's chosen cut 2026-08-10; behavioral-insight and
 farm-signal sections added that day; AI Card summon watch added 2026-08-24):
 
@@ -1762,8 +1986,8 @@ farm-signal sections added that day; AI Card summon watch added 2026-08-24):
   every individual summon. Each group reports its maximum same-day account and
   charged-summon totals, the multi-account days, and days above the shared
   three-card limit. Review every `requiresIdentityInspection` group,
-  prioritizing `daysAboveSharedLimit > 0`, with reason-required `identity
-  inspect`. If
+  prioritizing `daysAboveSharedLimit > 0`, with reason-required
+  `identity inspect`. If
   `riskGroupsTruncated` is true, report that the bounded watch has more groups
   than it returned rather than calling the review exhaustive. Add only
   operator-confirmed exact accounts to an unbanned quota bucket with