@stage5/lumine 0.3.36 → 0.3.38

package/lib/admin.js

@@ -179,6 +179,7 @@ const REVIEW_REQUEST_TYPES = [
   "project-limit",
   "storage-limit",
   "cardcraft",
+  "soundtrack",
 ];
 const REVIEW_REQUEST_TYPE_ALIASES = {
   rewards: "rewards",
@@ -192,6 +193,8 @@ const REVIEW_REQUEST_TYPE_ALIASES = {
   cardcraft: "cardcraft",
   "card-craft": "cardcraft",
   crafting: "cardcraft",
+  soundtrack: "soundtrack",
+  "song-tag": "soundtrack",
 };
 const REVIEW_REQUEST_LIST_STATUSES = [
   "queue",
@@ -206,9 +209,10 @@ const REVIEW_REQUEST_LABELS = {
   "project-limit": "Project room",
   "storage-limit": "Lumine file storage",
   cardcraft: "AI Card crafting",
+  soundtrack: "Song app tag",
 };
 const REVIEW_REQUEST_USAGE =
-  "Usage: lumine admin review list [--type rewards|project|storage|cardcraft] [--status queue|pending|approved|rejected|all] [--cursor <c>] | show <type:id> [--dir <path>] | approve <type:id> [--config <rules.json>] [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <type:id> [--reason <text>] | revoke <type:id> --reason <text> | propose rewards:<id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--title <new app name>] [--thumbnail <image|workspace>]. A bare id works with --type.";
+  "Usage: lumine admin review list [--type rewards|project|storage|cardcraft|soundtrack] [--status queue|pending|approved|rejected|all] [--cursor <c>] | show <type:id> [--dir <path>] | approve <type:id> [--config <rules.json>] [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <type:id> [--reason <text>] | revoke <type:id> --reason <text> | propose rewards:<id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--title <new app name>] [--thumbnail <image|workspace>]. A bare id works with --type.";
 
 function parseReviewRequestType(value) {
   const key = String(value || "")
@@ -217,7 +221,7 @@ function parseReviewRequestType(value) {
   const type = REVIEW_REQUEST_TYPE_ALIASES[key];
   if (!type) {
     throw cliValidationError(
-      `Unknown request type "${key}". Use rewards, project, storage or cardcraft.`,
+      `Unknown request type "${key}". Use rewards, project, storage, cardcraft or soundtrack.`,
     );
   }
   return type;
@@ -882,13 +886,13 @@ function buildReviewRequestOperation({
   if (!REWARD_REVIEW_DECISIONS.includes(action)) {
     return null;
   }
-  if (action === "revoke" && !["rewards", "cardcraft"].includes(ref.type)) {
+  if (action === "revoke" && !["rewards", "cardcraft", "soundtrack"].includes(ref.type)) {
     throw cliValidationError(
       `${REVIEW_REQUEST_LABELS[ref.type]} approvals are not revoked; change the limit instead${ref.type === "storage-limit" ? " (lumine admin storage grant)" : ""}.`,
     );
   }
   if (
-    ["rewards", "cardcraft"].includes(ref.type) &&
+    ["rewards", "cardcraft", "soundtrack"].includes(ref.type) &&
     action !== "approve" &&
     !reason
   ) {
@@ -3509,7 +3513,7 @@ export function parseAdminOperation(options) {
     // long as two GPT-6.1 Sol calls, so it gets its own timeout. The daily
     // website management run calls it in a bounded loop (Mikey, 2026-09-28).
     const usage =
-      "Usage: lumine admin reward-bank coverage <buildId> [--max-step 3] | seed <buildId> [--max-step 3] [--identity zero|ciel|auto] | report <buildId> [--days 1].";
+      "Usage: lumine admin reward-bank coverage <buildId> [--max-step 3] | seed <buildId> [--max-step 3] [--identity zero|ciel|auto] | report <buildId> [--days 1] | question <buildId> --question-id <id> | repair <buildId> --file <repair.json> [--dry-run].";
     const buildId = parseRequiredInteger(
       target || options.adminBuild,
       "Build ID",
@@ -3519,6 +3523,59 @@ export function parseAdminOperation(options) {
       ? parseRequiredInteger(options.adminMaxStep, "--max-step", 1)
       : 3;
     if (maxStep > 10) throw cliValidationError("--max-step must be at most 10.");
+    if (action === "question") {
+      const questionId = parseRequiredInteger(
+        options.adminQuestionId,
+        "--question-id",
+        1,
+      );
+      return readOperation(
+        "reward-bank.question",
+        withQuery("/cli/admin/reward-bank/question", {
+          buildId: String(buildId),
+          questionId: String(questionId),
+        }),
+        { requiresRun: false },
+      );
+    }
+    if (action === "repair") {
+      const repair = readAdminJsonFile(
+        options.adminFile,
+        "--file <repair.json>",
+        { maxBytes: 16 * 1024 },
+      );
+      const fields = ["questionId", "expectedFingerprint", "answer", "reason"];
+      if (
+        !repair ||
+        typeof repair !== "object" ||
+        Array.isArray(repair) ||
+        Object.keys(repair).some((key) => !fields.includes(key)) ||
+        !Number.isSafeInteger(repair.questionId) ||
+        repair.questionId <= 0 ||
+        typeof repair.answer !== "number" ||
+        !Number.isFinite(repair.answer) ||
+        typeof repair.expectedFingerprint !== "string" ||
+        !/^[a-f0-9]{64}$/.test(repair.expectedFingerprint) ||
+        typeof repair.reason !== "string" ||
+        !repair.reason.trim() ||
+        repair.reason.length > 2000
+      ) {
+        throw cliValidationError(
+          "Repair JSON needs questionId, the inspected expectedFingerprint, a finite numeric answer and a reason (1–2000 characters); no other fields.",
+        );
+      }
+      return writeOperation(
+        "reward-bank.repair",
+        "POST",
+        "/cli/admin/reward-bank/repair",
+        {
+          buildId,
+          repair,
+          dryRun: Boolean(options.adminDryRun),
+        },
+        { requiresRun: false, mutates: !options.adminDryRun },
+      );
+    }
     if (action === "report") {
       const days = options.adminDays
         ? parseRequiredInteger(options.adminDays, "--days", 1)
@@ -7385,6 +7442,26 @@ function printAdminResult({ operation, result }) {
     }
   }
   if (operation.name.startsWith("reward-bank.")) {
+    if (
+      ["reward-bank.question", "reward-bank.repair"].includes(operation.name)
+    ) {
+      const question = data.question;
+      console.log(
+        `Question #${question.id} · Build ${question.buildId} · ${question.mode} · ${question.status}`,
+      );
+      console.log(question.prompt);
+      console.log(`Stored answer: ${question.answer}`);
+      if (question.hint) console.log(`Hint: ${question.hint}`);
+      if (question.guide) console.log(`Guide: ${question.guide}`);
+      console.log(`Fingerprint: ${data.fingerprint}`);
+      console.log(`History: ${JSON.stringify(data.impact)}`);
+      if (Object.hasOwn(data, "proposedAnswer"))
+        console.log(
+          `Proposed answer: ${data.proposedAnswer} · would change: ${data.wouldChange}`,
+        );
+      console.log(data.historyPolicy);
+      return;
+    }
     if (operation.name === "reward-bank.seed") {
       console.log(
         data.seeded

package/lib/commands.js

@@ -2803,6 +2803,7 @@ export function parseArgs(args) {
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
     adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
     adminFile: raw.file ? String(raw.file) : "",
+    adminQuestionId: raw.questionId ? String(raw.questionId) : "",
     rewardPreflight: Boolean(raw.preflight),
     rewardApprovalFile: raw.approvalFile ? String(raw.approvalFile) : "",
     // admin craft revise --item <id|name> [--why] [--emoji] [--category]

package/lib/sdk.js

@@ -13,6 +13,11 @@ import { findLocalProjectMetadata } from "./workspace.js";
 // TWINKLE_BUILD_SDK.md. Methods that mutate data require --allow-write.
 // Anything not listed can be called with --path api/<endpoint>.
 export const SDK_CLI_METHODS = {
+  "soundtracks.searchSources": { path: "api/soundtracks/sources", scopes: ["sharedDb:read"] },
+  "soundtracks.getTags": { path: "api/soundtracks/tags", scopes: ["sharedDb:read"] },
+  "soundtracks.getRecommendations": { path: "api/soundtracks/recommendations", scopes: ["sharedDb:read"] },
+  "soundtracks.requestTag": { path: "api/soundtracks/request-tag", scopes: ["sharedDb:write"], write: true },
+  "soundtracks.removeTag": { path: "api/soundtracks/remove-tag", scopes: ["sharedDb:write"], write: true },
   "network.getHome": { path: "api/network/home", scopes: ["sharedDb:read"] },
   "network.getFeed": { path: "api/network/feed", scopes: ["sharedDb:read"] },
   "network.getThread": { path: "api/network/thread", scopes: ["sharedDb:read"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.3.36",
+  "version": "0.3.38",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {

package/sdk/BUILD_SDK_INDEX.md

@@ -1738,6 +1738,32 @@ if (result.status === 'ok') showCard(result.item, result.why, result.worldFirst)
   - Network owner only: dismiss a report, remove content, suspend an agent, or restore it.
   - Lumine Network Build 2742 only. Replace UI state from confirmed server responses.
 
+### Twinkle.soundtracks
+- async searchSources({ query } = {}) | scopes: sharedDb:read
+  - Returns: { sources: [{ kind, appId?, title, href, thumbnailUrl? }] }
+  - Find a public app or Grammarbles Quest for a song tag.
+  - Use a simple searchable picker. Send the returned kind/appId, never a title as an identifier.
+- async getTags({ entryIds }) | scopes: sharedDb:read
+  - Returns: { tags: [{ id, entryId, status, source, reviewReason, revision, eventTimeMs, canRemove }] }
+  - Read approved tags and the current creator’s requests for up to 50 songs.
+  - Pending, declined, closed and revoked requests are visible only to their creator. Replace state only with the canonical response.
+- async requestTag({ entryId, source, note?, expectedUserId }) | scopes: sharedDb:write
+  - Returns: { tag }
+  - Ask Mikey to link your published song to an app.
+  - source is { kind: "app", appId } or { kind: "grammarbles-quest" }. expectedUserId must be the current viewer.id.
+  - Only the song’s creator can request a tag. Up to three active tags per song and ten pending requests per creator. Same pending/approved request retries are idempotent.
+  - Uses the shared Build approvals queue and chat card. Nothing influences discovery until Mikey approves. Updating the song or any of its music parts closes the request/approval and requires a fresh review.
+- async removeTag({ tagId, expectedUserId }) | scopes: sharedDb:write
+  - Returns: { tag }
+  - Withdraw your own app tag, including a live approval.
+  - Stops recommendations immediately. Show the returned status; do not optimistically remove server-owned approval state.
+- async getRecommendations({ limit } = {}) | scopes: sharedDb:read
+  - Returns: { picks: [{ entry, source, reason }] }
+  - Suggest approved soundtrack songs from apps the current viewer used.
+  - limit is 1–12 (default 6). Guests and viewers without matching history get an empty list. Hide the shelf when empty.
+  - Matches recorded public-app use and actual Grammarbles Quest answers. Private/deleted apps, missing songs and unapproved/revoked tags never qualify. Returns no activity history or raw progress.
+  - Full Circle and Starlight music and covers stay locked for listeners until the current viewer reaches their Red Square milestones. A locked entry has songLocked, coverLocked and coverUnlockHint, with listing metadata only: no music, manifest or details.cover. Direct part reads follow the same gate. Disable playback, remix and queue actions and offer a link to /app/2. Creators retain editing access to their own songs.
+
 ## Examples
 
 ### Daily reflection feed

package/sdk/LUMINE_ADMIN.md

@@ -1714,8 +1714,32 @@ them so the first learner on a unit never waits or pays.
 lumine admin reward-bank coverage <buildId> [--max-step 3] [--json]   # read-only, no run
 lumine admin reward-bank seed <buildId> [--max-step 3] [--json]       # delegated full run
 lumine admin reward-bank report <buildId> [--days 1] [--json]         # read-only telemetry
+lumine admin reward-bank question <buildId> --question-id <id> [--json]
+lumine admin reward-bank repair <buildId> --file <repair.json> --dry-run [--json]
+lumine admin reward-bank repair <buildId> --file <repair.json> [--json]
 ```
 
+`question` returns the complete prompt, answer, hint and guide, question
+statistics, a canonical `fingerprint`, and aggregate challenge history. It is
+owner-only and does not need a daily run. A report excerpt is not an exact
+question inspection.
+
+`repair` accepts exactly `{ "questionId": 41, "expectedFingerprint": "<hash
+from inspection>", "answer": 0.5, "reason": "Verified explanation and arithmetic" }`.
+Inspect and verify the mathematics before preparing a repair. `--dry-run`
+checks the same guard without writing. The real command locks and rechecks the
+question, changes only its numeric answer, returns canonical readback and
+records an idempotent transaction audit. A stale fingerprint is rejected;
+inspect again instead of guessing a new hash. Unknown plan fields are rejected.
+No model call or AI Energy charge is involved.
+
+The repaired answer governs subsequent attempts, including already-issued
+unsolved challenges. Past attempts, grades, ladders, question statistics and
+rewards stay unchanged; the receipt states this explicitly. The history counts
+are observations, not a lock over every learner's activity. If the old answer
+affected a learner, inspect that history and prepare a separate, exact remedy;
+this command never guesses compensating rewards or rewrites past grades.
+
 `report` covers the last `--days` (1-31): generation rounds by source
 (learner or seed) with outcomes (`accepted`, `off_brief`: the checker judged
 the question outside the brief's language, level or LaTeX rule;