@stage5/lumine 0.3.74 → 0.3.76

package/lib/admin-arena.js

@@ -112,6 +112,13 @@ export function buildArenaOperation({ action, options }) {
   }
   if (action === "import") {
     const additive = Boolean(options.adminArenaAdditive);
+    if (!options.adminFile && !options.adminDir) {
+      throw validationError(
+        additive
+          ? "--additive needs --file <reviewed-items.json> or --dir <folder>; it never reads the current folder."
+          : ARENA_USAGE,
+      );
+    }
     if ((options.adminFile && options.adminDir) || (options.adminFile && !additive)) {
       throw validationError("Use --dir for a complete paper, or --additive with exactly one of --file or --dir for a refill.");
     }

package/lib/admin.js

@@ -3063,9 +3063,15 @@ export function parseAdminOperation(options) {
       const raw = readAdminJsonFile(target, "<reviewed-definitions.json>", { maxBytes: 512 * 1024 });
       const items = Array.isArray(raw) ? raw : raw?.items;
       if (!Array.isArray(items) || !items.length || items.length > 100) throw cliValidationError("Review 1 to 100 Korean definitions, keeping exported word IDs, revisions and source hashes.");
-      return writeOperation("dictionary.korean-review", "POST", "/cli/admin/dictionary/korean/review", { items, dryRun: Boolean(options.adminDryRun) }, { requiresRun: false, mutates: !options.adminDryRun, timeoutMs: 120000 });
+      // A preview (dry run) unless --confirm, like arena import and today-import.
+      if (options.adminConfirm && options.adminConfirm !== "true") {
+        throw cliValidationError("Pass --confirm on its own, without a value.");
+      }
+      const confirm = options.adminConfirm === "true";
+      if (confirm && options.adminDryRun) throw cliValidationError("Choose --confirm or --dry-run, not both.");
+      return writeOperation("dictionary.korean-review", "POST", "/cli/admin/dictionary/korean/review", { items, dryRun: !confirm }, { requiresRun: false, mutates: confirm, timeoutMs: 120000 });
     }
-    throw cliValidationError("Use: lumine admin dictionary korean-status | korean-pending [--cursor <time:id>] [--limit <1-100>] | korean-review <reviewed-definitions.json> [--dry-run]");
+    throw cliValidationError("Use: lumine admin dictionary korean-status | korean-pending [--cursor <time:id>] [--limit <1-100>] | korean-review <reviewed-definitions.json> [--confirm]");
   }
   if (namespace === "word-games") {
     if (action === "status") return readOperation("word-games.status", "/cli/admin/word-games/status", { requiresRun: false });
@@ -3173,7 +3179,7 @@ export function parseAdminOperation(options) {
     // as the website. Check-ins provide evidence; every meetup completion
     // waits for Mikey's decision (2026-10-22).
     const usage =
-      "Usage: lumine admin meetup list [--status review|active|completed|all] | show <crewId> | review-completion <crewId> --decision approve|reject --fingerprint <review fingerprint> | info <crewId> <userId> --decision ask|accept|ask-again|withdraw [--note <text>] | set-branch <crewId> <userId> --branch <name> [--note <text>] | branches [list|show|approve|reject|merge] | emails [list|send <id> [--fingerprint <revision>]|discard <id>|review on|off] | friends [status|on|off] | funnel [--days <1-90>] | story ... | announce-checkins [--send] [--as zero|ciel].";
+      "Usage: lumine admin meetup list [--status review|active|completed|all] | show <crewId> | review-completion <crewId> --decision approve|reject --fingerprint <review fingerprint> | info <crewId> <userId> --decision ask|accept|ask-again|withdraw [--note <text>] | set-branch <crewId> <userId> --branch <name> [--note <text>] | branches [list|show|approve|reject|merge] | emails [list|send <id> --fingerprint <revision>|discard <id>|review on|off] | friends [status|on|off] | funnel [--days <1-90>] | story ... | announce-checkins [--send] [--as zero|ciel].";
     const note = String(options.note || "").trim();
     if (note.length > 1000) {
       throw cliValidationError("--note must be at most 1000 characters.");
@@ -3279,11 +3285,18 @@ export function parseAdminOperation(options) {
       }
       if (sub === "send" || sub === "discard") {
         const id = parseRequiredInteger(extra, "Email ID", 1);
-        const revision = sub === "send" ? String(options.adminFingerprint || "").trim() : "";
+        // A send names the exact draft the admin reviewed, so a draft that
+        // changed after review is never sent unseen.
+        const revision = sub === "send" ? String(options.adminFingerprint || "").trim().toLowerCase() : "";
+        if (sub === "send" && !revision) {
+          throw cliValidationError(
+            "Sending a parent email needs --fingerprint <revision>. Run lumine admin meetup emails list, review the draft, then send it with the fingerprint printed beside it.",
+          );
+        }
         if (revision && !/^[0-9a-f]{64}$/.test(revision)) throw cliValidationError("Use --fingerprint from the reviewed email in meetup emails list.");
         return writeOperation("meetup.emails", "POST", `/cli/admin/meetup-quest/emails/${id}/${sub}`, revision ? { revision } : {}, { requiresRun: false });
       }
-      throw cliValidationError("lumine admin meetup emails [list | send <id> | discard <id> | review on|off]");
+      throw cliValidationError("lumine admin meetup emails [list | send <id> --fingerprint <revision> | discard <id> | review on|off]");
     }
     if (action === "friends") {
       const sub = target || "status";

package/lib/commands.js

@@ -2545,6 +2545,17 @@ export function parseArgs(args) {
           ? `${raw.branch},${inlineValue}`
           : inlineValue;
     } else if (booleanFlags.has(camelKey)) {
+      // A switch never takes a spaced value, so `--live false` would turn the
+      // switch on and leave "false" behind. Refuse it rather than guess.
+      const nextValue = rest[i + 1];
+      if (
+        nextValue !== undefined &&
+        ["false", "no", "off", "0"].includes(nextValue.trim().toLowerCase())
+      ) {
+        throw new Error(
+          `--${key} is a switch and does not take "${nextValue}" after a space. Leave --${key} out (or write --${key}=false) to turn it off.`,
+        );
+      }
       raw[camelKey] = true;
     } else if (
       optionalValueFlags.has(camelKey) &&
@@ -2683,7 +2694,7 @@ export function parseArgs(args) {
     adminSinceRun: Boolean(raw.sinceRun),
     adminSince: raw.since ? String(raw.since) : "",
     adminUntil: raw.until ? String(raw.until) : "",
-    adminIncludeSynthetic: Boolean(raw.includeSynthetic),
+    adminIncludeSynthetic: parseBoolean(raw.includeSynthetic, false),
     adminPath: raw.path ? String(raw.path) : "",
     adminPerf: Boolean(raw.perf),
     adminWake: Boolean(raw.wake),
@@ -3319,7 +3330,7 @@ export function printHelp() {
   lumine admin teachers audit [--limit <1-100>] [--cursor <c>] [--all] | revoke <userId> --reason <text>   (approved teachers, a page at a time or --all: new flags first, then changed since your review; revoke removes the status cleanly)
   lumine admin teachers branches suggest | networks | confirm <networkId> --branch <name> [--branch <name>] [--note <text>] | unconfirm <networkId> | set <userId|username> --branch <name> [--note <text>] | clear <userId|username> | apply | list [--branch <name>|none]   (which branch each teacher works at, confirmed by you through the academy networks they use: suggest finds the networks, confirm names their branch (repeat --branch for a building branches share), apply gives teachers the branch most of their actions there point at and lists the unclear ones; set wins over networks)
   lumine admin teachers review <userId> --decision legit|revoke --note <text> [--fingerprint <fp>, required for revoke] | review --all-flagged --expect <id[:fp],...> --note <text>   (record your review of the facts shown; --all-flagged records only the --expect teachers; nothing is recorded if they changed since. A reviewed teacher comes back when its flags or linked accounts change; accounts sharing a network count only when they change a network flag)
-  lumine admin dictionary korean-status | korean-pending [--cursor <time:id>] [--limit <1-100>] | korean-review <reviewed-definitions.json> [--dry-run]   (shared Korean word-bank definitions; daily review, no paid generation)
+  lumine admin dictionary korean-status | korean-pending [--cursor <time:id>] [--limit <1-100>] | korean-review <reviewed-definitions.json> [--confirm]   (shared Korean word-bank definitions; daily review, no paid generation; a preview unless --confirm)
   lumine admin english import <verdicts.json> --pass a|b | adjudicate <file> | add-questions <file> | relevel <file> | mastery <userId> --reason <why> | backfill-distractors | summary | review [--limit <n>] | accept|retire <questionId> | retag <questionId> --skill <code>   (English skill tags and bank upkeep for Grammarbles; content written by Claude Code agents)
   lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] [--json]
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]

package/lib/workspace.js

@@ -8,9 +8,11 @@ import {
   EXCLUDED_UPLOAD_FILES,
   LUMINE_AGENT_INSTRUCTIONS,
   LUMINE_AGENT_INSTRUCTIONS_MARKER,
+  LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER,
   LUMINE_REFERENCE_INSTRUCTIONS,
   LUMINE_REFERENCE_INSTRUCTIONS_MARKER,
   LUMINE_SDK_REFERENCE_MARKER,
+  LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER,
   PROJECT_EFFECTIVE_LINE_MAX_COLUMNS,
   PROJECT_MAX_EFFECTIVE_FILE_LINES,
   PROJECT_MAX_FILES,
@@ -39,14 +41,23 @@ export async function writeReferenceInstructions({ dir }) {
   });
 }
 
-// Write AGENTS.md/CLAUDE.md, but never clobber a file the user customized:
-// only (re)write when the file is absent or still carries our marker.
+// All checkout modes generate these same two files. A previous mode's header
+// still identifies a CLI-managed guide and must change with the checkout.
+// Custom guides omit the generated header; quoting a marker later is not ownership.
 export async function writeInstructionFiles({ dir, marker, content }) {
+  const managedHeaders = new Set([
+    marker,
+    LUMINE_AGENT_INSTRUCTIONS_MARKER,
+    LUMINE_REFERENCE_INSTRUCTIONS_MARKER,
+    LUMINE_MAIN_CHECKOUT_INSTRUCTIONS_MARKER,
+    LUMINE_VERSION_CHECKOUT_INSTRUCTIONS_MARKER,
+  ]);
   for (const fileName of AGENT_INSTRUCTION_FILES) {
     const filePath = path.join(dir, fileName);
     try {
       const existing = await fs.readFile(filePath, "utf8");
-      if (!existing.includes(marker)) {
+      const header = existing.replace(/^\uFEFF/, "").split(/\r?\n/, 1)[0];
+      if (!managedHeaders.has(header)) {
         continue;
       }
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.74",
+  "version": "0.3.76",
   "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.74.0
-Updated: 2026-10-29
-Generated: 2026-10-28T20:08:43.889Z
+Version: 1.75.0
+Updated: 2026-10-31
+Generated: 2026-10-31T07:54:50.319Z
 
 ## Platform rules
 Each rule below is a way an app breaks once it runs inside Twinkle's sandboxed frame, even when the code itself is correct. They outrank every other guideline: follow them in every change, including small ones, and fix any break of them you see in code you touch.
@@ -32,6 +32,7 @@ Features every app needs whenever they apply. When you build a new app or make a
 - Reward is part of completion: a reward-paying run must stay pending until awarded:true and its canonical receipt (or getReceipt status awarded). Do not show final solved/completed status, advance rewarded progress, or discard finished proof before that. Preserve the exact challenge/proof and acknowledged progress in a durable per-viewer outbox; reconcile getReceipt after a lost reply and retry the same challenge, never inventing a payment. Explain explicit practice, already collected, exhausted approved limits, preview and disclosed zero-value retry outcomes. Use the start response as a conservative elapsed-time reference, and test delayed start, network failure, lost claim reply, reload, day/viewer change and duplicate recovery.
 - This SDK is injected into Build iframes via the Build preview/runtime.
 - Widgets call SDK methods; the parent proxies to the API.
+- When an SDK request never got a reply from Twinkle's server (the device went offline, the network dropped, or the connection was cut first), its rejected error has error.details.isTransportError === true. Its error.status is 500 for older apps, so check this flag before treating a 500 as a server failure. The request may or may not have been applied: retry a write only with the same operationId or requestId, and only after a later user action or decision point, never in a loop. Errors that came back from the server never carry the flag.
 - Data API methods require scoped tokens handled by the parent; some namespaces include write methods.
 - Use Twinkle.privateDb for LOW-frequency durable private per-user state such as preferences, drafts, settings, inventory checkpoints, and saved progress. It is NOT for high-frequency or per-frame/per-tick writes; the server rate-limits writes and returns 429.
 - 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.
@@ -1403,17 +1404,18 @@ const result = await Twinkle.characters.chat({ character: 'zero', thinkingMode:
   - For oldest-first chronological reads, pass order: 'asc' or order: 'oldest'. sort and direction are accepted as aliases.
   - Supports cursor-based pagination. Newest-first cursors page toward older entries; oldest-first cursors page toward newer entries.
 - async queryEntries(topicName, { limit, pageSize, cursor, order, authorUserId, fields, where, countBy, includeAuthor } = {}) | scopes: sharedDb:read
-  - Returns: { entries?, groups?, cursor, hasMore, queryVersion: 1 }
+  - Returns: { entries?, groups?, cursor, hasMore, queryVersion: 1, truncated? }
   - Read selected shared data fields with server-side creator filtering, scalar matching and grouped counts.
   - Returns the same paginated entries as getEntries, plus queryVersion: 1.
   - authorUserId filters to one entry creator on the server. It does not change read or write permissions.
   - fields selects at most 24 top-level data field names; missing selected fields are null. Omit fields for complete data; [] returns only row metadata.
   - where: { field, equals } filters one top-level data field by exact JSON scalar equality (string, number, boolean or null).
   - Alternatively where: { field, truthy: true } requires a present JSON value other than null, false, zero or an empty string.
-  - countBy groups matching entries by one top-level data field and returns { groups: [{ value, count }], cursor, hasMore, queryVersion: 1 } instead of entries. This avoids transferring documents just to count comments. Groups page in first-entry order; use the returned cursor with the same query. Per-viewer hidden entries are excluded before counting.
+  - countBy groups matching entries by one top-level data field and returns { groups: [{ value, count }], cursor, hasMore, queryVersion: 1 } instead of entries. This avoids transferring documents just to count comments. Groups page in first-entry order; use the returned cursor with the same query. Per-viewer hidden entries are excluded before counting. Counts cover at most the newest 4000 entries of the topic (or of authorUserId's entries in it); when the topic is larger the result has truncated: true, so keep a running tally field instead of recounting a huge topic.
   - includeAuthor: false skips username/profile-photo enrichment for count/index reads; id, topicId, userId and timestamps remain available.
   - Field names use letters, digits and underscores, starting with a letter or underscore, at most 64 characters. No SQL or nested paths.
-  - Keep the same filters/fields/order when passing a cursor. Reads retain app/topic boundaries, published guest opt-ins and per-viewer content visibility. Signed-in queries read canonical writer state.
+  - Keep the same filters/fields/order when passing a cursor. Reads retain app/topic boundaries, published guest opt-ins and per-viewer content visibility. Signed-in entry queries read canonical writer state; grouped counts may trail a just-saved entry by a moment.
+  - queryEntries calls are limited to 60 a minute per viewer (per IP for guests) and 600 a minute per app; a busy app gets HTTP 429 and should retry later rather than loop.
   - Use metadata lists for browsing and getEntriesByIds only when a member opens a full recording/document.
 - async loadMoreEntries(topicName, { limit, pageSize, cursor, order, sort, direction } = {}) | scopes: sharedDb:read
   - Returns: { entries: [{ id, topicId, userId, username, profilePicUrl, data, createdAt, updatedAt }], cursor?, hasMore }

package/sdk/LUMINE_ADMIN.md

@@ -3176,6 +3176,9 @@ unrelated release authority. Keep release evidence and private diagnostics out
 of the public article. Follow the repository's daily website-code update
 procedure and the existing dated-revision contract for an approved correction.
 
+**Plain words (Mikey, 2026-10-30):** write the article for 10-15-year-olds with no technical background. Describe what members can now do or what feels better in everyday words; avoid developer terms and internal names (API, SDK, frame rate, memory, cache, deploy, version numbers, counterproposal and the like). The same applies to the newspaper's front-page piece about it. A published update Subject cannot be edited through the CLI, so check the wording before `--confirm`.
+Model to follow (Mikey, 2026-10-30): the Subject 37274 form in `agent-guides/daily-update-post-template.md`: short headline, one-line greeting from the duty bot, the biggest change first in bold with a link, a short bold-labelled paragraph for each other change, and a closing question.
+
 Use the scoped posting command after composing and reviewing the article:
 
 ```bash
@@ -5568,7 +5571,7 @@ Bridge Builder qualifies from QR check-ins: 7 different people, or one meetup a
   - The private note and the change history are admin-only; nobody is messaged.
   - It refuses members who left and crews that are not active.
 - `lumine admin meetup funnel [--days <1-90>]` shows views, crews by stage, and check-ins: pairs, how many were on one network or at an academy, and refusals by reason.
-- `lumine admin meetup emails` lists parent emails held for review. Kind `witness` is a child asking a parent to be the grown-up.
+- `lumine admin meetup emails` lists parent emails held for review. Kind `witness` is a child asking a parent to be the grown-up. `lumine admin meetup emails send <id> --fingerprint <revision>` sends one; the fingerprint is the reviewed draft's revision that `emails list` prints, and a send without it is refused. If the draft changed after review, list and review it again. `emails discard <id>` drops one.
 - `lumine admin meetup announce-checkins [--send] [--as zero|ciel]` is about the one-time announcement of the check-in rework in each crew chat. It posts itself when the website with check-ins is out. The messages are pre-written; without `--send` this only shows them. `--send` retries a crew whose post failed. Each crew gets it once.
 - **Held unlocks:** every physical-meetup qualification gets a `meetup` approval item (`lumine admin approvals list --type meetup`). `approvals show <id> --json` includes `meetupEvidence` for all participants. After Mikey decides, use `approvals approve|reject <id> --fingerprint <meetupEvidence.fingerprint>`. Proximity never bypasses review.
 - **Crew completions:** `meetup show <crewId> --json` includes the same owner-only scan packet. After Mikey decides, use `meetup review-completion <crewId> --decision approve|reject --fingerprint <meetupEvidence.fingerprint>`. The decision fails if the shown evidence or proposed attendance changed. New attendees and tier upgrades need a new decision.
@@ -5621,6 +5624,6 @@ Every full management run includes this dedicated review, requested by Mikey Oct
 
 - `lumine admin dictionary korean-status --json`: current generated/reviewed/pending coverage, oldest pending time, outstanding jobs and recent failures.
 - `lumine admin dictionary korean-pending --limit 100 [--cursor <time:id>] --json`: full text, English reference meanings, exact IDs/revisions/source hashes. Continue through `nextCursor` until null. Read and assess every entry; collection alone is not review.
-- `lumine admin dictionary korean-review <reviewed.json> --dry-run --json`, then omit `--dry-run` to apply the same reviewed payload within authorized content-maintenance scope. Accepts an array or `{ "items": [...] }`, 1–100 entries, each `{ "wordId": 123, "word": "example", "expectedRevision": 1, "expectedSourceHash": "<exported SHA-256>", "koreanDefinition": "<checked Korean meaning>", "reason": "<what was checked or corrected>" }`. Keep exact exported identity/version fields; supply a reason even when accepting unchanged text. All entries commit together with a mutation audit. Conflicts require re-export and re-review, never blind retry with new revisions.
+- `lumine admin dictionary korean-review <reviewed.json> --json` previews (validation only, nothing written); then add `--confirm` to apply the same reviewed payload within authorized content-maintenance scope. Accepts an array or `{ "items": [...] }`, 1–100 entries, each `{ "wordId": 123, "word": "example", "expectedRevision": 1, "expectedSourceHash": "<exported SHA-256>", "koreanDefinition": "<checked Korean meaning>", "reason": "<what was checked or corrected>" }`. Keep exact exported identity/version fields; supply a reason even when accepting unchanged text. All entries commit together with a mutation audit. Conflicts require re-export and re-review, never blind retry with new revisions.
 
 Assess common senses, part of speech and inflections, precision and natural Korean for learners. Use your own language judgment and source checks where needed; no paid batch-generation calls. Corrections update the shared word-bank field for all apps; successful reviews mark it reviewed and advance its revision. Future paid generation never overwrites existing text. The final run report includes reviewed/corrected/remaining counts, oldest waiting age, generation/Battery recovery failures, pagination coverage and carryovers. Re-read status after applying. Missing tables/endpoints mean the release is unavailable, not an empty healthy queue.