@stage5/lumine 0.2.17 → 0.2.19

package/lib/constants.js

@@ -170,6 +170,16 @@ lumine save --summary "Describe the change"
   need --allow-write and mutate real app data.
 - Owned canonical builds may be published only when the user explicitly asks.
 
+## Team Suggestions
+
+- After saving contribution-branch work, use \`lumine suggest branch "Ready for review"\`
+  when the user wants to notify the project owner. Use \`lumine suggest thumbnail\`
+  when the branch's current thumbnail should be offered to the owner.
+- On an owned canonical team project, \`lumine suggestions\` lists the owner's
+  currently open branch and thumbnail suggestions. Act on the exact suggestion
+  id it prints with \`lumine suggestions merge\`, \`replace-main\`, or
+  \`adopt-thumbnail\`; do not infer an action from stale local branch state.
+
 ## Assets (Runtime Media)
 
 - Binary files are NOT project files. Never place bundled media in this
@@ -320,14 +330,18 @@ export const MAIN_CHECKOUT_READONLY_COMMANDS = new Set([
   "versions",
 ]);
 export const COMMANDS = new Set([
+  "admin",
   "workspace",
   "login",
   "logout",
   "whoami",
   "new",
   "rename",
+  "describe",
   "projects",
   "branches",
+  "suggest",
+  "suggestions",
   "explore",
   "select",
   "pull",

package/lib/http.js

@@ -20,7 +20,10 @@ export async function requestJson({
   const data = parseJson(text);
   if (!response.ok) {
     const error = new Error(
-      data?.error || data?.message || `${method} ${url} failed`,
+      data?.error?.message ||
+        (typeof data?.error === "string" ? data.error : "") ||
+        data?.message ||
+        `${method} ${url} failed`,
     );
     error.status = response.status;
     error.data = data;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "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.29.0
-Updated: 2026-07-31
-Generated: 2026-07-31T05:39:44.540Z
+Version: 1.32.0
+Updated: 2026-08-02
+Generated: 2026-08-02T03:03:30.002Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -12,7 +12,7 @@ Generated: 2026-07-31T05:39:44.540Z
 - 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.news to read the globally shared Twinkle Daily edition, browse canonical daily archives and preserved successful press runs, or let a signed-in viewer queue today's edition. The server permits only one canonical edition per Twinkle day for ordinary viewers. In the canonical Twinkle Newspaper app, its current owner may explicitly refresh today's ready edition, appending a revision while keeping the newest successful press run canonical. A model-backed edition consumes AI Energy from the signed-in viewer whose request creates, retries, or refreshes that job; deduplicated observers and quiet editions with no editorial model call do not consume 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.
@@ -306,11 +306,11 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - 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 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.
+  - thinkingMode low uses GPT-5.6 Luna and consumes the viewer's AI Energy from confirmed provider usage; its smaller model is usually cheaper than Medium or High.
+  - thinkingMode medium uses Grok 4.5 with medium reasoning and consumes normal AI Energy.
+  - thinkingMode high uses GPT-5.6 Sol with high reasoning and consumes high AI Energy.
+  - When AI Energy is empty, Low, Medium, and High all reject 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 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
@@ -351,13 +351,13 @@ const result = await Twinkle.ai.chat({ message, history: chatHistory, systemProm
   - The character route also accepts text or message fields for compatibility, but generated apps should use content.
   - The server keeps the latest 16 valid character history entries.
   - 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 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.
+  - thinkingMode low uses Lite Mode: Zero uses Grok 4.5 with low reasoning and Ciel uses Claude Haiku 4.5; confirmed provider usage consumes the viewer's AI Energy and is usually cheaper than Medium or High.
+  - thinkingMode medium consumes normal AI Energy: Zero uses Grok 4.5 with medium reasoning and Ciel uses Claude Sonnet 5.
+  - thinkingMode high consumes high AI Energy: Zero uses Grok 4.5 with high reasoning and Ciel uses Claude Opus 5 with extended thinking.
+  - When AI Energy is empty, Low, Medium, and High all reject before new provider work; there is no free fallback mode.
   - 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.
+  - 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.
   - 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.
@@ -529,19 +529,35 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
 
 ### Twinkle.news
 - async getCurrentEdition() | scopes: none
-  - Returns: { dayIndex, nextEditionAt, generationStatus, edition: { id, dayIndex, status, coverageStartedAt, coverageEndedAt, sourceEventCount, edition, model, provider, generatedAt } | null, pendingEdition }
+  - Returns: { dayIndex, nextEditionAt, generationStatus, edition: { id, dayIndex, status, coverageStartedAt, coverageEndedAt, sourceEventCount, edition, model, provider, generatedAt, revisionNumber, revisionCount } | 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.
+  - While today's first edition is pending, edition remains the latest ready shared edition. During an owner refresh, edition remains the earlier same-day edition. pendingEdition describes the canonical queued work in both cases.
   - Poll gently while generation is pending; once every 5-10 seconds is sufficient.
-- async generateCurrentEdition() | scopes: none
+- async listEditions({ limit = 12, cursor } = {}) | scopes: none
+  - Returns: { editions: [{ id, dayIndex, dateKey, headline, deck, coverageStartedAt, coverageEndedAt, sourceEventCount, generatedAt, revisionNumber, revisionCount }], cursor, hasMore }
+  - List the canonical daily newspaper archive newest-first.
+  - Works for signed-in viewers and public-build guests.
+  - Returns compact publication summaries rather than full newspaper JSON.
+  - limit defaults to 12 and is capped at 30. Pass cursor from the previous response to load older editions.
+  - Each item describes the latest canonical revision for that Twinkle day.
+- async getEdition({ dayIndex, revisionNumber } = {}) | scopes: none
+  - Returns: { edition: { id, revisionId?, dayIndex, status, coverageStartedAt, coverageEndedAt, sourceEventCount, edition, model, provider, generatedAt, revisionNumber, revisionCount }, revisions: [{ revisionId, revisionNumber, coverageStartedAt, coverageEndedAt, sourceEventCount, model, provider, generatedAt, createdAt }], selectedRevisionNumber, canonicalRevisionNumber }
+  - Read one canonical daily edition or an exact preserved successful press run.
+  - Works for signed-in viewers and public-build guests.
+  - dayIndex is required. Omit revisionNumber to read that day's latest canonical edition.
+  - Pass a revisionNumber returned in revisions to read that exact successful press run.
+  - Historical revisions remain subject to canonical privacy and deletion redactions.
+- async generateCurrentEdition({ refresh = false } = {}) | 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.
+  - The first request for a Twinkle day creates the canonical pending edition; concurrent and later ordinary requests return that same server state.
+  - In the canonical Twinkle Newspaper app, its current owner may pass { refresh: true } to revise an already-ready same-day edition using the latest canonical events. Every successful refresh is appended as a preserved press run and becomes that day's canonical revision. Ownership is checked by the server at request time and therefore follows an app transfer.
+  - When this request creates, retries, or refreshes a model-backed edition, confirmed provider usage consumes AI Energy from this requesting viewer. Concurrent or later callers that deduplicate onto the same pending or ready edition are not charged.
+  - A quiet edition with no editorial events does not call an AI provider and does not consume AI Energy.
+  - A failed attempt may be queued again on the same day. A ready edition is immutable for ordinary viewers.
 
 ### Twinkle.leaderboards
 - async get({ boardKey = 'default', limit, cursor } = {}) | scopes: none