@stage5/lumine 0.2.15 → 0.2.17

package/README.md

@@ -10,6 +10,7 @@ npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Priv
 npx @stage5/lumine@latest rename "My New Build Title"
 npx @stage5/lumine@latest rename "New Title" --target 123
 npx @stage5/lumine@latest projects
+npx @stage5/lumine@latest branches 884
 npx @stage5/lumine@latest explore --sort forks
 npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
 npx @stage5/lumine@latest fork https://www.twin-kle.com/app/123
@@ -35,6 +36,10 @@ pulling the owner's main project creates or reuses your contribution branch and
 checks out that branch locally. Saves go to your branch, so the project owner
 can merge or replace main from Twinkle.
 
+Use `lumine branches <build-url-or-id>` to list the contribution branches you
+can review, including each contributor, branch number, status, and URL. Then use
+`lumine diff <branch-url>` to inspect one branch.
+
 Use `lumine explore` to list public open-source Build apps that can be used as
 examples or starting points. It supports `--search` and `--sort forks`,
 `--sort popular`, or `--sort recent`. Use `lumine reference <build-url-or-id>`

package/lib/api.js

@@ -30,6 +30,21 @@ export async function listOpenSourceBuilds({ options, auth }) {
   return Array.isArray(result.builds) ? result.builds : [];
 }
 
+export async function listContributionBranches({
+  options,
+  auth,
+  buildId,
+  limit,
+}) {
+  const url = new URL(`${options.apiUrl}/build/${buildId}/contributions`);
+  url.searchParams.set("limit", String(limit));
+  return await requestJson({
+    url: url.toString(),
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
 export async function loadBuildMetadata({ options, auth, buildId }) {
   const result = await loadBuildFiles({
     options,

package/lib/commands.js

@@ -31,6 +31,7 @@ import {
   loadBuildVersionFiles,
   loadBuildVersions,
   loadContributionDiff,
+  listContributionBranches,
   loadLumineCliVersionInfo,
   loadOpenSourceBuildFiles,
   maybeCheckForLumineCliUpdate,
@@ -76,6 +77,7 @@ import {
   collectProjectLimitFindings,
   findLocalProjectMetadata,
   isIndexHtmlPath,
+  isReadOnlyProjectMetadata,
   isReadOnlyReferenceMetadata,
   removeLocalProjectFilesNotIn,
   stashLocalProjectFilesBeforePull,
@@ -130,6 +132,10 @@ export async function main() {
     await projects(options);
     return;
   }
+  if (options.command === "branches") {
+    await branches(options);
+    return;
+  }
   if (options.command === "explore") {
     await explore(options);
     return;
@@ -263,7 +269,8 @@ export async function renameBuild(options) {
   await saveSelectedBuild({ options, auth, build: updatedBuild });
   if (
     localProject?.rootDir &&
-    Number(localProject.metadata?.buildId || 0) === buildId
+    Number(localProject.metadata?.buildId || 0) === buildId &&
+    !isReadOnlyProjectMetadata(localProject.metadata)
   ) {
     await writeProjectMetadata({
       dir: localProject.rootDir,
@@ -303,6 +310,33 @@ export async function projects(options) {
   printBuildList(builds);
 }
 
+export async function branches(options) {
+  const auth = await resolveAuth(options);
+  const requestedBuildId = await resolveRequiredBuildIdOrSelected(
+    options,
+    auth,
+  );
+  const requestedBuild = await loadBuildMetadata({
+    options,
+    auth,
+    buildId: requestedBuildId,
+  });
+  const rootBuildId =
+    Number(requestedBuild.contributionRootBuildId || 0) ||
+    Number(requestedBuild.id || 0);
+  const rootBuild =
+    rootBuildId === Number(requestedBuild.id || 0)
+      ? requestedBuild
+      : await loadBuildMetadata({ options, auth, buildId: rootBuildId });
+  const result = await listContributionBranches({
+    options,
+    auth,
+    buildId: rootBuildId,
+    limit: options.limit,
+  });
+  printContributionBranches({ result, rootBuild, options });
+}
+
 export async function explore(options) {
   const auth = await resolveAuth(options);
   const builds = await listOpenSourceBuilds({ options, auth });
@@ -1618,6 +1652,34 @@ export function printContributionDiff({ result, build }) {
   }
 }
 
+export function printContributionBranches({ result, rootBuild, options }) {
+  const contributions = Array.isArray(result?.contributions)
+    ? result.contributions
+    : [];
+  console.log(`Branches for ${formatBuildTitle(rootBuild)}:`);
+  if (!contributions.length) {
+    console.log("No contribution branches.");
+    return;
+  }
+  for (const [index, contribution] of contributions.entries()) {
+    const branchNumber = Number(contribution.contributionBranchNumber || 0);
+    const branchLabel = branchNumber
+      ? `branch ${branchNumber}`
+      : `branch #${contribution.id}`;
+    const title = String(contribution.title || "Untitled branch").trim();
+    const contributor = String(contribution.username || "unknown").trim();
+    const status = String(contribution.contributionStatus || "draft").trim();
+    console.log(
+      `${index + 1}. ${title} - ${contributor} - ${branchLabel} (${status})`,
+    );
+    if (branchNumber) {
+      console.log(
+        `   ${options.siteUrl}/build/${Number(rootBuild.id)}/${branchNumber}`,
+      );
+    }
+  }
+}
+
 export function printUpdateFromMainResult({ result, build, dir, mergedFiles }) {
   const branchNumber = Number(build?.contributionBranchNumber || 0) || 0;
   const branchLabel = branchNumber
@@ -1981,6 +2043,7 @@ export function printHelp() {
   lumine new [title]
   lumine rename [title] [--target <twinkle-build-url-or-id>]
   lumine projects
+  lumine branches [twinkle-build-url-or-id] [--limit <n>]
   lumine explore [search terms]
   lumine select [twinkle-build-url]
   lumine pull [twinkle-build-url]
@@ -2016,6 +2079,7 @@ Examples:
   npx @stage5/lumine@latest rename "My New Build Title"
   npx @stage5/lumine@latest rename "New Title" --target 123
   npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Private journal with streaks"
+  npx @stage5/lumine@latest branches 884
   npx @stage5/lumine@latest explore --sort forks
   npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
   npx @stage5/lumine@latest fork https://www.twin-kle.com/app/123

package/lib/constants.js

@@ -118,7 +118,7 @@ Use these current source-of-truth rules:
 - Use Twinkle.sharedDb for shared multi-user JSON data.
 - Use Twinkle.aiCards.list/search/get for existing public AI Card words, exampleText sentence material, and word levels.
 - 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 }.
+- 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.
 - Prefer existing documented Twinkle.* methods over guessing names from old code.
 `;
@@ -308,6 +308,7 @@ export const AGENT_INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md"];
 export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
   "pull",
   "check",
+  "branches",
   "diff",
   "sdk",
   "select",
@@ -326,6 +327,7 @@ export const COMMANDS = new Set([
   "new",
   "rename",
   "projects",
+  "branches",
   "explore",
   "select",
   "pull",

package/lib/workspace.js

@@ -779,14 +779,15 @@ export function resolveProjectDirForSave({ options, localProject }) {
 export function assertLocalProjectCanBeSaved(localProject) {
   const metadata = localProject?.metadata;
   if (!metadata) return;
-  if (metadata.mainCheckout === true) {
+  const readOnlyKind = readOnlyProjectMetadataKind(metadata);
+  if (readOnlyKind === "main") {
     const rootBuildId =
       Number(metadata.buildId || 0) || Number(metadata.build?.id || 0) || 0;
     throw new Error(
       `This is a read-only checkout of main${rootBuildId ? ` for Build ${rootBuildId}` : ""}. Make edits in your branch workspace (\`lumine pull${rootBuildId ? ` ${rootBuildId}` : ""}\`), and run \`lumine update-from-main\` there to bring main's changes into it.`,
     );
   }
-  if (metadata.versionCheckout === true) {
+  if (readOnlyKind === "version") {
     const checkoutBuildId =
       Number(metadata.buildId || 0) || Number(metadata.build?.id || 0) || 0;
     const checkoutVersion = Number(metadata.checkoutVersion || 0) || 0;
@@ -794,7 +795,7 @@ export function assertLocalProjectCanBeSaved(localProject) {
       `This is a read-only checkout of a previous save${checkoutVersion ? ` (v${checkoutVersion})` : ""}${checkoutBuildId ? ` for Build ${checkoutBuildId}` : ""}. To bring this save back, run \`lumine restore${checkoutVersion ? ` ${checkoutVersion}` : " <n>"}\` from the editable workspace, then \`lumine save\`.`,
     );
   }
-  if (isReadOnlyReferenceMetadata(metadata)) {
+  if (readOnlyKind === "reference") {
     const sourceBuildId =
       Number(metadata.reference?.sourceBuildId || 0) ||
       Number(metadata.buildId || 0) ||
@@ -804,7 +805,7 @@ export function assertLocalProjectCanBeSaved(localProject) {
       `This is a read-only Lumine reference${sourceBuildId ? ` for Build ${sourceBuildId}` : ""}. Run \`lumine fork${sourceBuildId ? ` ${sourceBuildId}` : ""}\` to create an editable workspace.`,
     );
   }
-  if (metadata.build?.canWrite === false) {
+  if (readOnlyKind === "server") {
     throw new Error(
       "This Lumine checkout is read-only for the current CLI login. Pull or diff it for review; project-owner branch edits must go through merge or replace-main.",
     );
@@ -819,6 +820,18 @@ export function isReadOnlyReferenceMetadata(metadata) {
   );
 }
 
+export function isReadOnlyProjectMetadata(metadata) {
+  return readOnlyProjectMetadataKind(metadata) !== null;
+}
+
+export function readOnlyProjectMetadataKind(metadata) {
+  if (metadata?.mainCheckout === true) return "main";
+  if (metadata?.versionCheckout === true) return "version";
+  if (isReadOnlyReferenceMetadata(metadata)) return "reference";
+  if (metadata?.build?.canWrite === false) return "server";
+  return null;
+}
+
 export function resolveLocalProjectFilePath({ rootDir, projectPath }) {
   const relativePath = projectPathToRelativePath(projectPath);
   const root = path.resolve(rootDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "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.27.0
-Updated: 2026-07-21
-Generated: 2026-07-23T05:57:27.486Z
+Version: 1.29.0
+Updated: 2026-07-31
+Generated: 2026-07-31T05:39:44.540Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -12,6 +12,7 @@ Generated: 2026-07-23T05:57:27.486Z
 - Match storage to update frequency: privateDb and sharedDb are for LOW-frequency durable state that changes on a user action. NEVER write per-frame/per-tick state to them (camera or cursor position, animation, live movement, presence, autosave every frame/tick). Keep live state in client memory, broadcast realtime/presence via Twinkle.world, and flush only occasional durable snapshots (on an interval or on exit, never per frame). The server enforces per-key write rate limits and returns 429 on excess; never retry-loop a 429.
 - Use Twinkle.userDb only for advanced private SQLite needs such as tables, indexes, many rows, filtered queries, or aggregates.
 - Use Twinkle.leaderboards for public Build scoreboards. Signed-in viewers are ranked by Twinkle username; guests can submit with a display name.
+- Use Twinkle.news to read the globally shared Twinkle Daily edition or let a signed-in viewer queue today's edition. The server permits only one ready edition per Twinkle day and generation does not spend the requesting viewer's AI Energy.
 - Use Twinkle.sharedDb for LOW-frequency durable shared multi-user state such as guestbooks, votes, room settings, submitted records, and append-only run history. It is NOT for high-frequency or per-frame/per-tick writes; keep live/realtime state in Twinkle.world or client memory. The server rate-limits writes and returns 429.
 - Use Twinkle.subjects.search for in-app subject pickers. Twinkle.mount remains an optional host-provided preselection/context shortcut, not a data API.
 - Use Twinkle.aiCards for read-only existing public AI Card words and example texts, including word levels for typing games.
@@ -21,6 +22,7 @@ Generated: 2026-07-23T05:57:27.486Z
 - Use Twinkle.world for realtime multiplayer rooms, avatar presence, movement, emotes, and lightweight actions; world sessions are disposable and durable MMO state belongs in sharedDb/privateDb.
 - Use Twinkle.characters.chat for real Zero/Ciel NPC dialogue with shared room context and AI Energy-aware thinking modes.
 - Twinkle.ai.chat history entries must use { role, content }; map local message.text fields to content before passing history.
+- 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.
 
@@ -281,31 +283,34 @@ console.log(analysis.bestMove, analysis.evaluation, analysis.mate);
 - async listPrompts() | scopes: none
   - Returns: Array<{ id, title, description }>
   - Legacy helper. Twinkle.ai.chat does not require promptId for default runtime text generation.
-- async chat({ promptId, message, history, systemPrompt, requestId, onText, onStatus } = {}) | scopes: none
-  - Returns: { text, response, model, aiUsagePolicy }
-  - Generate text with the default Lumine text model, optionally streaming text updates through onText.
+- async chat({ promptId, message, history, systemPrompt, webSearch, requestId, onText, onStatus } = {}) | scopes: none
+  - Returns: { text, response, model, webSearch, aiUsagePolicy }
+  - Generate text with the default Lumine text model, optionally using live web search and streaming text updates through onText.
   - Signed-in viewers only.
   - Uses Grok 4.5 by default.
   - Each successful text generation consumes AI Energy from the signed-in viewer.
   - history must be an array of { role: 'user' | 'assistant', content: string }. Twinkle.ai.chat does not read a text field.
   - The server keeps the latest 12 valid history entries.
   - Pass systemPrompt to define the app AI's personality, tone, role, or response rules.
+  - Live web search is enabled by default, and the model decides whether searching is useful. Pass webSearch: false to disable it for the app.
+  - When streaming, onStatus may receive searching_web while the provider is searching.
   - Pass onText to receive streaming accumulated text before the final result resolves.
-  - AI Energy is recorded after provider success when final token usage is available.
+  - AI Energy is recorded after provider success when final token and web-search tool usage are available.
   - 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, instructions, systemPrompt } = {}) | scopes: none
-  - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, aiUsagePolicy }
-  - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic.
+- async generateObject({ prompt, expectedStructure, thinkingMode, mode, instructions, systemPrompt, webSearch } = {}) | scopes: none
+  - Returns: { object, result, model, provider, thinkingMode, requestedThinkingMode, webSearch, aiUsagePolicy }
+  - Generate a validated structured JSON object for app decisions, routing, grading, and game-state logic, optionally using live web search.
   - Signed-in viewers only.
   - Use this instead of asking Twinkle.ai.chat to return JSON.
   - expectedStructure must be a JSON object that describes the exact returned object shape.
   - mode is accepted as an alias for thinkingMode, and mid is accepted as an alias for medium.
   - thinkingMode low uses GPT-5.6 Luna and records free low-energy usage.
-  - thinkingMode medium uses GPT-5.6 Luna and normal AI Energy while AI Energy remains.
-  - thinkingMode high uses Grok 4.5 with high reasoning and high AI Energy while AI Energy remains.
+  - thinkingMode medium uses Grok 4.5 with medium reasoning and normal AI Energy while AI Energy remains.
+  - thinkingMode high uses GPT-5.6 Sol with high reasoning and high AI Energy while AI Energy remains.
   - If medium or high is requested after AI Energy is empty, the server falls back to low and returns thinkingMode: low.
+  - Live web search is enabled by default in Medium and High modes. Pass webSearch: false to disable it for the app. Omitted/default search turns off automatically when the request falls back to tool-free Lite Mode; explicitly forcing webSearch: true in Lite Mode returns an error.
   - The SDK validates shape and retries malformed JSON, but app code should still validate business-specific enum values.
   - Example: const { object } = await Twinkle.ai.generateObject({ thinkingMode: 'medium', prompt: 'Classify the player intent from: ' + playerText, expectedStructure: { action: 'string', targetCharacter: 'string', confidence: 0, shouldAskFollowUp: false } });
 - onChatStatus(listener) | scopes: none
@@ -337,9 +342,9 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Example: const unsubscribe = Twinkle.ai.onImageGenerationStatus((status) => console.log(status.stage));
 
 ### Twinkle.characters
-- async chat({ character, thinkingMode, message, history, roomContext, scene, systemPrompt, instructions, includeWebsiteContext, requestId, onText, onStatus } = {}) | scopes: none
-  - Returns: { text, response, character, aiUsername, thinkingMode, requestedThinkingMode, includeWebsiteContext, model, provider, aiUsagePolicy }
-  - Talk to Zero or Ciel from a Build app, either as a final-response call or streaming RPG-style dialogue text with onText/onStatus.
+- async chat({ character, thinkingMode, message, history, roomContext, scene, systemPrompt, instructions, includeWebsiteContext, webSearch, requestId, onText, onStatus } = {}) | scopes: none
+  - Returns: { text, response, character, aiUsername, thinkingMode, requestedThinkingMode, includeWebsiteContext, webSearch, model, provider, aiUsagePolicy }
+  - Talk to Zero or Ciel from a Build app, optionally using live web search and streaming RPG-style dialogue text with onText/onStatus.
   - Signed-in viewers only.
   - character must be zero or ciel.
   - Recommended history shape is { role: 'user' | 'assistant', content: string, speaker?: string }; content is the canonical text field.
@@ -348,10 +353,13 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - Pass onText/onStatus for streaming dialogue. Omit callbacks for non-streaming dialogue where the promise resolves with the final response.
   - thinkingMode low uses Lite Mode: Zero uses Grok 4.5 with low reasoning and Ciel uses Claude Haiku 4.5; usage is recorded as free low-energy usage.
   - thinkingMode medium uses normal AI Energy: Zero uses Grok 4.5 with medium reasoning and Ciel uses Claude Sonnet 5 while AI Energy remains.
-  - thinkingMode high uses high AI Energy: Zero uses Grok 4.5 with high reasoning and Ciel uses Claude Opus 4.8 with extended thinking while AI Energy remains.
+  - thinkingMode high uses high AI Energy: Zero uses Grok 4.5 with high reasoning and Ciel uses Claude Opus 5 with extended thinking while AI Energy remains.
   - If medium or high is requested after AI Energy is empty, the server falls back to low and returns thinkingMode: low.
   - Pass roomContext as a short shared scene transcript so Zero and Ciel can know what happened in the same room.
   - includeWebsiteContext defaults to true. Set includeWebsiteContext: false for in-world NPC dialogue that should only use Zero/Ciel's basic character identity plus your scene/instructions.
+  - Live web search is enabled by default in Medium and High modes. Pass webSearch: false to disable it for the app. Omitted/default search turns off automatically when the request falls back to tool-free Lite Mode; explicitly forcing webSearch: true in Lite Mode returns an error.
+  - includeWebsiteContext controls Twinkle persona context and is unrelated to webSearch.
+  - When streaming, onStatus may receive searching_web while the provider is searching.
   - Use this for real Zero/Ciel NPCs instead of pretending with Twinkle.ai.chat systemPrompt.
   - Example: const dialogueHistory = recentTurns.slice(-16).map((entry) => ({ role: entry.role === 'assistant' ? 'assistant' : 'user', content: entry.text, speaker: entry.speaker }));
 const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode: thinkHard ? 'high' : 'medium', message: playerText, history: dialogueHistory, roomContext, scene: { location: 'classroom', nearbyCharacters: ['zero', 'ciel'] }, includeWebsiteContext: false, onText: (text) => renderDialogue(text) });
@@ -519,6 +527,22 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - Atomic step 3: fetches likes/replies aggregates for provided IDs.
   - Accepts either an array of IDs or an object like { ids: [...] }.
 
+### Twinkle.news
+- async getCurrentEdition() | scopes: none
+  - Returns: { dayIndex, nextEditionAt, generationStatus, edition: { id, dayIndex, status, coverageStartedAt, coverageEndedAt, sourceEventCount, edition, model, provider, generatedAt } | null, pendingEdition }
+  - Read today's shared Twinkle newspaper, or the latest ready edition while today's is being generated.
+  - Works for signed-in viewers and public-build guests.
+  - generationStatus is available, pending, generating, ready, or failed.
+  - While today's edition is pending, edition remains the latest ready shared edition and pendingEdition describes today's queued work.
+  - Poll gently while generation is pending; once every 5-10 seconds is sufficient.
+- async generateCurrentEdition() | scopes: none
+  - Returns: { dayIndex, nextEditionAt, generationStatus, edition, pendingEdition }
+  - Atomically queue the current Twinkle day's globally shared edition.
+  - Requires a signed-in viewer.
+  - The first request for a Twinkle day creates the canonical pending edition; concurrent and later requests return that same server state.
+  - Generation is platform-sponsored and does not consume the requesting viewer's AI Energy.
+  - A failed attempt may be queued again on the same day. A ready edition is immutable until the next Twinkle day.
+
 ### Twinkle.leaderboards
 - async get({ boardKey = 'default', limit, cursor } = {}) | scopes: none
   - Returns: { entries: [{ rank, id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt }], scores, cursor, hasMore, personalBest: { id, buildId, boardKey, viewerKind, userId, displayName, score, meta, achievedAt, createdAt, updatedAt } | null }