@stage5/lumine 0.3.53 → 0.3.55

package/lib/admin-nonogram.js

@@ -0,0 +1,45 @@
+import { readAdminJsonFile } from './admin-news.js';
+
+const USAGE = 'Usage: lumine admin nonogram status | add --file <pictures.json> | retire <key> | restore <key> [--confirm] [--json]';
+function invalid(message) {
+  const error = new Error(message);
+  error.code = 'CLI_ADMIN_CLI_VALIDATION';
+  throw error;
+}
+export function buildNonogramOperation({ action, target, options }) {
+  if (!action || action === 'status') return {
+    name: 'nonogram.status', method: 'GET', path: '/cli/admin/nonogram/status',
+    mutates: false, requiresRun: false
+  };
+  if (!['add', 'retire', 'restore'].includes(action)) invalid(USAGE);
+  if (options.adminConfirm !== '' && options.adminConfirm !== 'true')
+    invalid('Pass --confirm on its own, without a value.');
+  const confirm = options.adminConfirm === 'true';
+  if (action !== 'add') {
+    if (typeof target !== 'string' || !/^[a-z0-9][a-z0-9-]{2,79}$/.test(target)) invalid('Supply one exact picture key.');
+    return { name: `nonogram.${action}${confirm ? '' : '.preview'}`, method: 'POST',
+      path: '/cli/admin/nonogram/availability', body: { key: target, retire: action === 'retire', dryRun: !confirm },
+      mutates: confirm, requiresRun: false };
+  }
+  const pictures = readAdminJsonFile(options.adminFile, '--file <pictures.json>', { maxBytes: 1024 * 1024 });
+  if (!Array.isArray(pictures) || !pictures.length || pictures.length > 150)
+    invalid('The file must contain 1–150 reviewed pictures. Split larger refills.');
+  return {
+    name: confirm ? 'nonogram.add' : 'nonogram.add.preview', method: 'POST',
+    path: '/cli/admin/nonogram/add', body: { pictures, dryRun: !confirm },
+    mutates: confirm, requiresRun: false, timeoutMs: 120000
+  };
+}
+export function formatNonogramResult({ operation, data }) {
+  if (operation.name === 'nonogram.status') return (data?.sizes || []).map((s) =>
+    `${s.size}×${s.size}: ${s.total} pictures; at least ${s.leastUnseen} unseen for every learner (${s.reserveDays} days at 3/day; target ${s.targetDays}).`);
+  if (/^nonogram\.(retire|restore)/.test(operation.name)) return [
+    `${data?.dryRun ? 'Dry run: would mark' : 'Marked'} ${data?.key} ${data?.retired ? 'retired' : 'available'}. Started puzzles are preserved.`,
+    ...(data?.dryRun ? ['Nothing was written. Add --confirm to apply.'] : [])
+  ];
+  return [
+    `${data?.dryRun ? 'Dry run: would add' : 'Added'} ${data?.added?.length || 0} pictures; skipped ${data?.skipped?.length || 0} duplicates.`,
+    ...(data?.skipped || []).map((p) => `${p.key}: ${p.reason}`),
+    ...(data?.dryRun ? ['Nothing was written. Add --confirm to import this reviewed collection.'] : [])
+  ];
+}

package/lib/admin-spending.js

@@ -0,0 +1,472 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const round = (value) => {
+  if (!Number.isFinite(value))
+    throw new Error("Invalid computed spending amount.");
+  return Number(value.toFixed(8));
+};
+const USAGE =
+  "lumine admin spending [--month YYYY-MM | --from YYYY-MM --to YYYY-MM] [--aws-profile <profile>] [--json]";
+
+function invalid(message) {
+  return Object.assign(new Error(message), {
+    code: "CLI_ADMIN_CLI_VALIDATION",
+  });
+}
+
+export function buildSpendingOperation(options) {
+  if (
+    (options.positional || []).length !== 1 ||
+    options.adminDays ||
+    options.adminDate ||
+    options.adminAll ||
+    options.adminResume
+  ) {
+    throw invalid(`Usage: ${USAGE}.`);
+  }
+  const query = new URLSearchParams();
+  const values = {
+    month: options.adminSpendingMonth,
+    from: options.adminSpendingFrom,
+    to: options.adminSpendingTo,
+  };
+  for (const [key, value] of Object.entries(values)) {
+    if (value === undefined) continue;
+    if (typeof value !== "string" || !/^20\d{2}-(0[1-9]|1[0-2])$/.test(value))
+      throw invalid(`--${key} must use YYYY-MM format.`);
+    query.set(key, value);
+  }
+  if (query.has("month") && (query.has("from") || query.has("to")))
+    throw invalid("Use --month or --from/--to, not both.");
+  if (query.has("from") !== query.has("to"))
+    throw invalid("Provide both --from and --to.");
+  if (query.has("from") && query.get("from") > query.get("to"))
+    throw invalid("--from must not follow --to.");
+  const qs = query.toString();
+  return {
+    name: "spending.report",
+    method: "GET",
+    path: `/cli/admin/spending${qs ? `?${qs}` : ""}`,
+    mutates: false,
+    requiresRun: false,
+    timeoutMs: 60000,
+  };
+}
+
+async function runAws(args, { profile, region, timeoutMs }) {
+  try {
+    const { stdout } = await execFileAsync(
+      "aws",
+      [
+        ...args,
+        "--profile",
+        profile,
+        "--region",
+        region,
+        "--output",
+        "json",
+        "--no-cli-pager",
+      ],
+      {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        maxBuffer: 8 * 1024 * 1024,
+        env: { ...process.env, AWS_PAGER: "", AWS_CLI_AUTO_PROMPT: "off" },
+      },
+    );
+    return JSON.parse(stdout);
+  } catch (error) {
+    // Do not expose subprocess stdout, credentials or arbitrary provider error
+    // payloads in a saved financial report.
+    throw new Error(
+      error.code === "ENOENT"
+        ? "AWS CLI is not installed. Install it and configure the requested profile."
+        : `AWS billing could not be read with profile ${profile}; check its authentication and Cost Explorer access.`,
+    );
+  }
+}
+
+function amount(metric) {
+  if (
+    metric?.Unit !== "USD" ||
+    metric.Amount === "" ||
+    metric.Amount == null ||
+    !Number.isFinite(Number(metric.Amount))
+  ) {
+    throw new Error(
+      "AWS returned an invalid amount or a currency other than USD.",
+    );
+  }
+  return Number(metric.Amount);
+}
+
+export function normalizeAwsSpending(pages, months) {
+  const expected = new Map(
+    months
+      .filter((m) => m.startDayKey < m.endDayKeyExclusive)
+      .map((m) => [m.startDayKey, m]),
+  );
+  const found = new Map();
+  for (const page of pages) {
+    if (!Array.isArray(page?.ResultsByTime))
+      throw new Error("AWS returned no billing periods.");
+    for (const period of page.ResultsByTime) {
+      const start = period.TimePeriod?.Start;
+      const requested = expected.get(start);
+      if (
+        !requested ||
+        period.TimePeriod?.End !== requested.endDayKeyExclusive ||
+        typeof period.Estimated !== "boolean"
+      ) {
+        throw new Error(
+          "AWS billing periods do not match the requested UTC months.",
+        );
+      }
+      let target = found.get(start);
+      if (!target) {
+        target = {
+          status: "available",
+          costUsd: 0,
+          estimated: period.Estimated,
+          services: [],
+          startDayKey: start,
+          endDayKeyExclusive: period.TimePeriod.End,
+        };
+        found.set(start, target);
+      }
+      if (
+        target.estimated !== period.Estimated ||
+        !Array.isArray(period.Groups)
+      )
+        throw new Error("Inconsistent AWS billing page.");
+      if (
+        period.Groups.length === 0 &&
+        period.Total?.UnblendedCost &&
+        amount(period.Total.UnblendedCost) !== 0
+      ) {
+        throw new Error("AWS omitted the requested service breakdown.");
+      }
+      for (const group of period.Groups) {
+        if (
+          !Array.isArray(group.Keys) ||
+          group.Keys.length !== 1 ||
+          typeof group.Keys[0] !== "string" ||
+          target.services.some((s) => s.service === group.Keys[0])
+        )
+          throw new Error("Duplicate or invalid AWS service row.");
+        const costUsd = amount(group.Metrics?.UnblendedCost);
+        target.services.push({ service: group.Keys[0], costUsd });
+        target.costUsd += costUsd;
+      }
+    }
+  }
+  if (found.size !== expected.size)
+    throw new Error("AWS billing is missing a requested month.");
+  return months.map((month) => {
+    if (month.startDayKey === month.endDayKeyExclusive)
+      return {
+        status: "no_completed_days",
+        costUsd: 0,
+        estimated: true,
+        services: [],
+        startDayKey: month.startDayKey,
+        endDayKeyExclusive: month.endDayKeyExclusive,
+      };
+    const value = found.get(month.startDayKey);
+    return {
+      ...value,
+      costUsd: round(value.costUsd),
+      services: value.services.sort((a, b) => b.costUsd - a.costUsd),
+    };
+  });
+}
+
+function validateReport(report) {
+  if (
+    report?.schemaVersion !== 1 ||
+    report.currency !== "USD" ||
+    report.timezone !== "UTC" ||
+    !Array.isArray(report.months) ||
+    !report.months.length ||
+    report.months.length > 12 ||
+    !report.sources?.aws ||
+    report.range?.includesInProgressDay !== false
+  ) {
+    throw new Error(
+      "The API did not return a supported spending report; deploy the matching API release.",
+    );
+  }
+  let expectedStart = report.range.startDayKey;
+  for (const month of report.months) {
+    const nextMonth = new Date(
+      Date.UTC(
+        Number(month.monthKey?.slice(0, 4)),
+        Number(month.monthKey?.slice(5, 7)),
+        1,
+      ),
+    )
+      .toISOString()
+      .slice(0, 10);
+    if (
+      !/^20\d{2}-(0[1-9]|1[0-2])$/.test(month.monthKey) ||
+      month.startDayKey !== `${month.monthKey}-01` ||
+      month.startDayKey !== expectedStart ||
+      !/^20\d{2}-\d{2}-\d{2}$/.test(month.endDayKeyExclusive) ||
+      month.endDayKeyExclusive < month.startDayKey ||
+      month.endDayKeyExclusive > nextMonth ||
+      (month.status === "closed" && month.endDayKeyExclusive !== nextMonth) ||
+      (month !== report.months.at(-1) &&
+        month.endDayKeyExclusive !== nextMonth) ||
+      new Date(`${month.endDayKeyExclusive}T00:00:00Z`)
+        .toISOString()
+        .slice(0, 10) !== month.endDayKeyExclusive
+    ) {
+      throw new Error("The API spending report has invalid month boundaries.");
+    }
+    expectedStart = nextMonth;
+    // An available source must supply its amounts. In particular, null paid
+    // totals must never be coerced to zero when combined with operating costs.
+    const required = [
+      ...(month.ai ? [month.ai.grossUsd] : []),
+      ...(month.reimbursements
+        ? [
+            month.reimbursements.aiServiceUsd,
+            month.reimbursements.infrastructureUsd,
+            month.reimbursements.totalUsd,
+          ]
+        : []),
+    ];
+    if (
+      required.some(
+        (value) => typeof value !== "number" || !Number.isFinite(value),
+      )
+    )
+      throw new Error("The API spending report has incomplete source amounts.");
+    for (const value of [
+      month.ai?.grossUsd,
+      month.ai?.creditUsd,
+      month.ai?.estimatedCashUsd,
+      month.reimbursements?.aiServiceUsd,
+      month.reimbursements?.infrastructureUsd,
+      month.reimbursements?.totalUsd,
+    ]) {
+      if (
+        value != null &&
+        (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+      )
+        throw new Error("Invalid spending source amount.");
+    }
+  }
+  if (
+    report.months.at(-1).endDayKeyExclusive !== report.range.endDayKeyExclusive
+  )
+    throw new Error("The API spending report has incomplete month coverage.");
+}
+
+export async function completeSpendingReport(receipt, options, aws = runAws) {
+  if (receipt?.ok !== true) return receipt;
+  const report = receipt.data?.spending;
+  validateReport(report);
+  const warnings = [...(report.warnings || [])];
+  const source = report.sources.aws;
+  const profile = options.adminAwsProfile || source.defaultProfile;
+  if (typeof profile !== "string" || !profile.trim())
+    throw invalid("--aws-profile must name an AWS CLI profile.");
+  let awsMonths = null;
+  let awsError = null;
+  try {
+    const settings = {
+      profile,
+      region: source.region,
+      timeoutMs: Math.max(
+        1000,
+        Math.min(60000, Number(options.timeoutMs) || 30000),
+      ),
+    };
+    const hasCompletedDays =
+      report.range.startDayKey < report.range.endDayKeyExclusive;
+    const pages = [];
+    if (hasCompletedDays) {
+      const identity = await aws(["sts", "get-caller-identity"], settings);
+      if (
+        identity?.Account !== source.accountId ||
+        identity?.Arn !== source.principalArn
+      ) {
+        throw new Error(
+          "AWS identity does not match the Twinkle billing principal. No Cost Explorer query was sent.",
+        );
+      }
+      let token;
+      const seen = new Set();
+      do {
+        if (pages.length >= 100)
+          throw new Error("AWS billing exceeded the pagination limit.");
+        const page = await aws(
+          [
+            "ce",
+            "get-cost-and-usage",
+            "--time-period",
+            `Start=${report.range.startDayKey},End=${report.range.endDayKeyExclusive}`,
+            "--granularity",
+            "MONTHLY",
+            "--metrics",
+            "UnblendedCost",
+            "--group-by",
+            "Type=DIMENSION,Key=SERVICE",
+            "--no-paginate",
+            ...(token ? ["--next-page-token", token] : []),
+          ],
+          settings,
+        );
+        pages.push(page);
+        token = page.NextPageToken;
+        if (token && (typeof token !== "string" || seen.has(token)))
+          throw new Error("AWS billing pagination did not advance.");
+        if (token) seen.add(token);
+      } while (token);
+    }
+    awsMonths = normalizeAwsSpending(pages, report.months);
+  } catch (error) {
+    awsError = error.message;
+    warnings.push(awsError);
+  }
+  const months = report.months.map((month, i) => {
+    const billing = awsMonths?.[i] ?? null;
+    const overlap = month.ai?.awsOverlapDetected === true;
+    if (overlap)
+      warnings.push(
+        `${month.monthKey}: AWS-billed AI detected; combined totals require overlap reconciliation.`,
+      );
+    const operating =
+      month.ai?.estimatedCashUsd != null && billing && !overlap
+        ? round(month.ai.estimatedCashUsd + billing.costUsd)
+        : null;
+    return {
+      ...month,
+      aws: billing,
+      providerOperatingCostUsd: operating,
+      totalIncludingReimbursementsUsd:
+        operating !== null && month.reimbursements
+          ? round(operating + month.reimbursements.totalUsd)
+          : null,
+    };
+  });
+  const complete = months.every(
+    (m) => m.totalIncludingReimbursementsUsd !== null,
+  );
+  const sum = (select) =>
+    months.every((m) => select(m) != null)
+      ? round(months.reduce((n, m) => n + select(m), 0))
+      : null;
+  return {
+    ...receipt,
+    status: complete ? "success" : "partial",
+    data: {
+      ...receipt.data,
+      spending: {
+        ...report,
+        complete,
+        months,
+        warnings,
+        sources: {
+          ...report.sources,
+          aws: {
+            ...source,
+            profile,
+            status: awsMonths ? "available" : "unavailable",
+            error: awsError,
+          },
+        },
+        totals: {
+          aiEstimatedCashUsd: sum((m) => m.ai?.estimatedCashUsd),
+          awsUsd: sum((m) => m.aws?.costUsd),
+          reimbursementsUsd: sum((m) => m.reimbursements?.totalUsd),
+          totalIncludingReimbursementsUsd: sum(
+            (m) => m.totalIncludingReimbursementsUsd,
+          ),
+        },
+      },
+    },
+  };
+}
+
+export function formatSpending(report) {
+  const money = (value) =>
+    value == null
+      ? "Unavailable"
+      : `$${value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+  const lines = [
+    `Twinkle spending · USD · UTC · ${report.complete ? "complete sources" : "INCOMPLETE SOURCES"}`,
+  ];
+  const rows = [
+    ["Category", ...report.months.map((m) => m.monthKey)],
+    [
+      "AI after credits",
+      ...report.months.map((m) => money(m.ai?.estimatedCashUsd)),
+    ],
+    ["AWS (including tax)", ...report.months.map((m) => money(m.aws?.costUsd))],
+    [
+      "Reimbursements",
+      ...report.months.map((m) => money(m.reimbursements?.totalUsd)),
+    ],
+    [
+      "TOTAL incl. reimbursements",
+      ...report.months.map((m) => money(m.totalIncludingReimbursementsUsd)),
+    ],
+    ["", ...report.months.map(() => "")],
+    ["AI before credits", ...report.months.map((m) => money(m.ai?.grossUsd))],
+    ["Promotional credit", ...report.months.map((m) => money(m.ai?.creditUsd))],
+    [
+      "Reimbursement: AI service",
+      ...report.months.map((m) => money(m.reimbursements?.aiServiceUsd)),
+    ],
+    [
+      "Reimbursement: infrastructure",
+      ...report.months.map((m) => money(m.reimbursements?.infrastructureUsd)),
+    ],
+  ];
+  const widths = rows[0].map((_, i) =>
+    Math.max(...rows.map((row) => row[i].length)),
+  );
+  lines.push(
+    ...rows.map((row) =>
+      row
+        .map((cell, i) =>
+          i ? cell.padStart(widths[i]) : cell.padEnd(widths[i]),
+        )
+        .join(" | "),
+    ),
+  );
+  for (const month of report.months) {
+    if (month.status === "in_progress")
+      lines.push(
+        `${month.monthKey} AI/AWS: ${month.throughDayKey ? `through ${month.throughDayKey} UTC` : "no completed UTC days"}; current usage day excluded.`,
+      );
+    if (month.aws?.estimated)
+      lines.push(
+        `${month.monthKey} AWS is provisional and may change with billing updates.`,
+      );
+  }
+  lines.push(
+    `Selected-period total: ${money(report.totals.totalIncludingReimbursementsUsd)}`,
+  );
+  lines.push(
+    "AI is a usage-based estimate after credits. AWS estimated flags and service details are in JSON.",
+  );
+  lines.push(
+    "Reimbursements are gross paid amounts by payment date, before refunds/fees; included once in the total above.",
+  );
+  if (report.sources.reimbursements?.includesCurrentDay)
+    lines.push(
+      `Reimbursements include today's settled payments through ${new Date((report.sources.reimbursements.endAtExclusive - 1) * 1000).toISOString()}.`,
+    );
+  if (report.inProgressDay)
+    lines.push(
+      `${report.inProgressDay.dayKey} partial AI usage: ${money(report.inProgressDay.ai?.grossUsd)} before credits, excluded.`,
+    );
+  for (const warning of report.warnings || [])
+    lines.push(`Unavailable: ${warning}`);
+  return lines.join("\n");
+}

package/lib/admin.js

@@ -44,7 +44,9 @@ import {
   printOwnerTrace,
 } from "./admin-owner-trace.js";
 import { buildRolesOperation, printRoles } from "./admin-roles.js";
+import { buildSpendingOperation, completeSpendingReport, formatSpending } from "./admin-spending.js";
 import { buildCraftOperation, formatCraftResult } from "./admin-craft.js";
+import { buildNonogramOperation, formatNonogramResult } from './admin-nonogram.js';
 import {
   buildSlidingBlockOperation,
   formatSlidingBlockResult,
@@ -1544,7 +1546,10 @@ export async function adminCommand(options) {
         recommendationContentTypes,
         viewFilter,
       });
-    if (operation.featuredWorkflow) {
+    if (operation.name === "spending.report") {
+      result = await completeSpendingReport(await fetchOperation(), options);
+      if (result.status === "partial") process.exitCode = 1;
+    } else if (operation.featuredWorkflow) {
       result = await runFeaturedWorkflow({
         options,
         operation,
@@ -1623,6 +1628,11 @@ export async function adminCommand(options) {
     // private evidence is printed, never kept in the receipt file
     mutationIntent?.confirm(receiptToKeep(operation, result));
   } catch (error) {
+    if (operation.name === "spending.report" && error.status === 404) {
+      error.message = "The spending report API is not deployed yet. Deploy the matching API before using this CLI command.";
+      error.code = "CLI_ADMIN_SPENDING_NOT_DEPLOYED";
+      error.data = { ok: false, status: "unavailable", error: { code: error.code, message: error.message, details: null } };
+    }
     if (operation.name === "runtime.evidence" && error.status === 404) {
       error.code = "CLI_ADMIN_RUNTIME_EVIDENCE_NOT_DEPLOYED";
       error.message =
@@ -2650,6 +2660,7 @@ export function parseAdminOperation(options) {
   if (namespace === "sliding-block") {
     return buildSlidingBlockOperation({ action, options });
   }
+  if (namespace === 'nonogram') return buildNonogramOperation({ action, target, options });
   // Stuck Lumine Build plans and their free recheck (admin-build-plans.js).
   if (namespace === "build-plans") {
     return buildBuildPlansOperation({ action, options });
@@ -4472,6 +4483,8 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "spending") return buildSpendingOperation(options);
+
   if (namespace === "ai-costs") {
     if (action === "monthly" && !target && !extra) {
       if (options.adminDays) {
@@ -7358,6 +7371,10 @@ function printAiBucketRuleResult({ operation, data }) {
 
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
+  if (operation.name === "spending.report" && data.spending) {
+    console.log(formatSpending(data.spending));
+    return;
+  }
   if (operation.name === "math-lab.queue") {
     console.log(`Math Lab: published artifact ${data.publishedArtifactVersionId}, review ${data.reviewId}, day ${data.dayKey} UTC.`);
     for (const grade of data.grades || []) console.log(grade.available
@@ -7400,6 +7417,10 @@ function printAdminResult({ operation, result }) {
       console.log(line);
     return;
   }
+  if (operation.name.startsWith('nonogram.')) {
+    for (const line of formatNonogramResult({ operation, data })) console.log(line);
+    return;
+  }
   if (operation.name.startsWith("build-plans.")) {
     for (const line of formatBuildPlansResult({ operation, data }))
       console.log(line);

package/lib/commands.js

@@ -2562,6 +2562,13 @@ export function parseArgs(args) {
         );
     }
   }
+  if (command === "admin" && positional[0] === "spending") {
+    const allowed = new Set(["help", "month", "from", "to", "awsProfile", "output", "json",
+      "apiUrl", "siteUrl", "authFile", "authToken", "clientName", "timeoutMs", "noUpdateCheck"]);
+    for (const key of Object.keys(raw)) {
+      if (!allowed.has(key)) throw new Error(`Unsupported spending option --${key.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)}.`);
+    }
+  }
   const suggestionInboxActions = new Set([
     "list",
     "merge",
@@ -2805,6 +2812,10 @@ export function parseArgs(args) {
     adminActions: raw.actions ? String(raw.actions) : "",
     adminDate: raw.date ? String(raw.date) : "",
     adminDays: raw.days ? String(raw.days) : "",
+    adminSpendingMonth: raw.month,
+    adminSpendingFrom: raw.from,
+    adminSpendingTo: raw.to,
+    adminAwsProfile: raw.awsProfile,
     adminMaxStep: raw.maxStep ? String(raw.maxStep) : "",
     adminBuild: raw.build ? String(raw.build) : "",
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
@@ -3263,6 +3274,7 @@ export function printHelp() {
   lumine admin cardcraft-review list [--status pending|approved|all] [--cursor <id>] | show <id> | approve|reject|revoke <id> [--reason <text>]
   lumine admin craft seed --build <id> --file <pairs.json> [--confirm] | stats --build <id> [--limit <1-100>] | revise --build <id> --item <id|name> [--why <text>] [--emoji <emoji>] [--category <field>] [--confirm] | revise --build <id> --pair <pairId|a+b> --why <text> [--confirm] | retire --build <id> --item <id|name> --reason <text> [--confirm] | unfizzle --build <id> [--since <iso>] [--pair <a+b>] [--confirm]   (Twinkle.craft curation: dry run without --confirm)
   lumine admin sliding-block status | add --file <levels.json> [--confirm]   (sliding-block-v1 campaign refills, RushHour: dry run without --confirm; the server solves each board and appends it)
+  lumine admin nonogram status | add --file <pictures.json> | retire <key> | restore <key> [--confirm]   (private reviewed pictures; changes are dry runs without --confirm)
   lumine admin build-plans stuck [--days <1-90>] [--all] | recheck <buildId> [<buildId> ...] [--confirm]   (Lumine Build plans stuck on one milestone: runs, Energy vs estimate, gradings, loop-guard state; recheck re-grades the current milestone with today's evaluator, free for the creator, dry run without --confirm)
   lumine admin storage list [--status pending|approved|rejected|all] [--cursor <id>] | show <user-id-or-username> | approve <request-id> [--size <500MB|1GB|2GB|n MB>] [--reason <text>] | reject <request-id> [--reason <text>] | grant <user-id-or-username> --size <500MB|1GB|2GB|n MB> [--reason <text>]
   lumine admin meetup list [--status review|active|completed|all] | show <crewId> | info <crewId> <userId> --decision ask|accept|ask-again|withdraw [--note <text>] | set-branch <crewId> <userId> --branch "<name>" [--note <text>] | branches [list [--status pending|official|rejected|all] | show <id> | approve <id> | reject <id> [--note <text>] | merge <id> --into <officialId>] | emails [list|send <id>|discard <id>|review on|off] | friends [status|on|off] | funnel [--days <1-90>] | announce-checkins [--send] [--as zero|ciel]   (Bridge Builder crews and check-ins)
@@ -3324,6 +3336,7 @@ export function printHelp() {
     (with both a comment session and a daily run active, comment draft/reply/post/edit need --via session|run)
   lumine admin comment edit <comment-id> --file <comment.md> [--review-receipt <review.json> | --reviewed-version <id> --reviewed-via runtime|code] [--review-context <context.json>] [--json]
   lumine admin brief [--days <1..30>] [--json]
+  lumine admin spending [--month YYYY-MM | --from YYYY-MM --to YYYY-MM] [--aws-profile <profile>] [--output <file.json>] [--json] (owner spending: AI, AWS, reimbursements; no active run required)
   lumine admin ai-costs monthly [--output <file.json>] [--json] (no active run required)
   lumine admin ai-costs day <YYYY-MM-DD> [--json]
   lumine admin media-costs monthly [--json]

package/package.json

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

package/sdk/BUILD_SDK_INDEX.md

@@ -2,7 +2,7 @@
 
 Version: 1.68.0
 Updated: 2026-10-16
-Generated: 2026-10-21T05:16:33.397Z
+Generated: 2026-10-22T03:03:30.790Z
 
 ## Notes
 - This SDK is injected into Build iframes via the Build preview/runtime.
@@ -1569,10 +1569,12 @@ world.updatePresence({ x, y, z, facing });
   - Rules may set maxLifetimeClaims, a per-learner limit for that rule across days and releases. rules[].lifetime contains the server-confirmed limit and remaining claims. App storage never enforces this limit.
   - howTo is the rule's optional plain-words steps from rewards.json (up to 300 characters, e.g. "Save a new design of at least 64 blocks in Designs"). The Earn page shows it under the title; show it in the app's own rewards list too so players always know exactly what earns each reward.
   - category and series are optional rewards.json labels for a long list. category is a short section header (up to 40 characters, e.g. "Bring friends"); series is a short lowercase key (e.g. "new-friend") tying repeat rules like vigil-friend-1/2/3 together, and rules in one series must share category, verifier, XP and Coins. The Earn page groups rules by category and shows each series as one row ("up to 3 a day", "1 of 3 today"); group the app's own rewards list the same way.
+  - nonogram-picture-v1 uses Twinkle’s private, editorially reviewed picture bank. Set pictureSize to 5, 10 or 15 on each completion rule. Do not bundle daily solutions or a fixed answer catalog in app files. The collection is maintained through lumine admin nonogram; the reward amounts and daily limits still come from the approved rules.
 - await Twinkle.rewards.getReceipt({ challengeId }) | scopes: rewards:claim
   - Returns: { mode: "live", status: "awarded" | "pending" | "expired" | "not_found", receipt: { id, challengeId, ruleId, reviewId, artifactVersionId, dayKey, xp, coins, attempt, createdAt } | null, balances: { xp, coins } } | { mode: "preview", status: "not_found", receipt: null, message }
   - Read an existing receipt for this app and signed-in viewer by server-issued challengeId, including previous UTC days and previous approved versions. Requires the current approved published release and runtime grant; a stale frame must reload first. Never awards, retries a claim, returns answer keys, or restores removed rewards permission.
   - Reconcile a durable local reward outbox after a lost claim reply: awarded confirms the exact payment; pending means no receipt yet for a current unexpired challenge, so retry the same challengeId. expired or not_found confirms no paid receipt and no claim possible for that ID under the current release. Never refund app items just because getStatus history omitted an older claim or a network request failed. Preview has no durable paid receipts; keep it separate from live recovery.
+  - For a paid nonogram-picture-v1 receipt, picture { title, category } may also be returned so the app can recover the reveal after a lost response. It contains no solution cells.
 - await Twinkle.rewards.start({ ruleId, levelIndex?, completionToken? }) | scopes: rewards:claim
   - Returns: { mode: "live", challengeId, questions: [{ prompt, hint?, guide? }], setKey, reward: { xp, coins }, retryReward: { xp, coins }, attempts, maxAttempts, attemptsRemaining, firstTryAvailable, expiresAt }
   - Creates or resumes a server-issued challenge for the signed-in viewer. Render its questions (prompt and optional hint) and collect numeric answers in the same order. One daily challenge per rule/review; repeat starts cannot reset attempts. A challenge stays open until the site's daily reset (UTC midnight, 9:00 AM in Korea) (expiresAt). Resuming after a wrong answer includes each question's guide.
@@ -1580,6 +1582,7 @@ world.updatePresence({ x, y, z, facing });
   - For a completion rule call start when the activity begins (the moment the stage starts); the challenge's age is what the claim is measured against. In preview mode start also works for the owner (a stateless simulation).
   - For completionProof: classic-tower-v1, start also returns completion { profile, token, maxFrames, completed, failed }. A new start resets only the simulated climb to its canonical spawn; it cannot reset daily or lifetime rewards. Record inputs from the first physics frame. The completion token is bound to the viewer, challenge, rule and published release.
   - For breadface-v1, breadface-v2 and breadface-v3, pass the zero-based canonical levelIndex. Record [dt, inputBits] from the first physics frame; start returns its server token and maxFrames. For study-record-v1, start returns completion { profile, usesAiEnergy: true }; there is no client-authored proof token. For groove-lab-song-v1, groove-lab-heard-v1, vigil-guest-coplay-v1, minecraft-first-link-v1 and writing-words-v1, start returns completion { profile }; there is no progress step. For groove-lab-listen-v1 and groove-lab-own-listen-v1, call start({ ruleId, completionToken: <published song entry id> }) when that song starts playing; it returns completion { profile, songEntryId, durationSeconds, listenSeconds } and refuses with a plain reason (not published, whose song, too short, already earned for this song today). Starting a different song re-binds the rule's unpaid challenge and restarts its clock. For reading-quiz-v1, call progress({ challengeId, completionToken: <chapter commentId>, record: 'open' }) when the reader opens the chapter (returns readyInSeconds, readingSeconds, alreadyEarned, attemptedToday), then progress({ ..., record: 'quiz' }) once readyInSeconds has passed to get questions [{ question, options[4] }] (never answers). getStatus returns reading { chaptersEarnedToday, readersToday } when the app uses a reading proof. For writing-words-v1, getStatus also returns writing { countedWords, checkingChapters, chapters: [{ commentId, words, countedWords, status: counted|not-counted|checking|duplicate|too-short, english, reason }] } for today. For sliding-block-v1, start deals the board (completion.board, positions, minMoves); render it, record each real slide as [ms, carIndex, newPosition], send moves with progress (frames up to maxFrames per call), then claim with the latest token. For app-check-v1, start returns completion { profile, puzzle }: show that puzzle (a repeat start of the same challenge returns the same one); there is no progress step.
+  - For nonogram-picture-v1, start returns completion { profile, completed: false, readyInSeconds, puzzle: { size, rows: number[][], cols: number[][] } }. Render those row and column clues; there is no progress call. Live readyInSeconds is the remaining approved minimum wait, so reopening a puzzle does not restart its clock. The private picture is durably bound to this exact viewer, app, release, rule, challenge and expiry. Reopening returns the same clues even after a refill. New challenges use unseen pictures; build_reward_picture_collection_complete means this size needs a refill. Offer practice/community puzzles while waiting.
 - await Twinkle.rewards.progress({ challengeId, completionToken?, frames?, record?, requestId? }) | scopes: rewards:claim
   - Returns: { mode: "live" | "preview", completion: { profile, token?, completed, failed?, decision?, message?, maxFrames? }, aiUsagePolicy? }
   - Verify a bounded batch of inputs for an approved server-simulated climb.
@@ -1599,6 +1602,7 @@ world.updatePresence({ x, y, z, facing });
   - For study-record-v1, the server verifies the settled private review row and its viewer, app, exact release, challenge and day binding. It never trusts the client’s decision, requested award amount or AI answer. Each successful daily study record is claimable once; display only canonical receipt/balances. For groove-lab-song-v1, pass completionToken as the published song's sharedDb entry id; for groove-lab-heard-v1, pass none; for vigil-guest-coplay-v1, pass the guest's world guestId (from world events) or the co-play record id; for minecraft-first-link-v1, pass nothing or the Minecraft UUID to use; for reading-quiz-v1, pass completionToken as the chapter commentId and answers as the three chosen option indexes (all three must be right; a wrong attempt cannot be retried that day); for groove-lab-listen-v1 and groove-lab-own-listen-v1, pass the same song entry id after listenSeconds of foreground playback; for reading-readers-v1, pass nothing; for writing-words-v1, pass nothing (the server counts today's chapters itself and refuses with a plain reason, e.g. "320 of 500 counted words today" or "still being checked"). The server reads the app's own groove-lab-songs, groove-lab-song-parts and groove-lab-listens rows and refuses with build_reward_completion_proof_required and a plain reason when the song or listeners do not qualify.
   - For app-check-v1, pass completionToken as JSON.stringify(record), the record your check reads (at most 64 KB); the server deals the challenge again and runs the approved file's check before paying. A refused record returns { awarded: false, reason, attemptsRemaining } and uses a try; claim only when the app itself sees a finished solve.
   - For craft-target-v1 and craft-par-v1, pass completionToken as JSON.stringify({ v: 1, merges: [[a, b], ...] }): the item ids of the run's successful merges in order, starting from the starters (at most 300 merges, 32 KB). The server replays it against this app's known pairs, needs today's target (Twinkle.craft.getState().today) to appear, every result to be in the learner's collection, and at least one second per merge since start; it refuses an unknown pair, an item the run had not made yet, an over-par run (par rule), a par claim on a day the learner revealed a Twinkle.craft.hint (the target rule still pays) or a run on another day. For craft-discovery-v1, pass nothing: the server pays the oldest unpaid World First (receipt slot craft:<itemId>) and puts its name on the bounty story ("discovered <item>"). With tiers, a rule pays only World Firsts of its own tier (refused with a plain reason when the learner has none).
+  - For nonogram-picture-v1, pass completionToken: JSON.stringify({ rows: ["01010", ...] }) with the filled grid. Wrong grids consume a try and never reveal answer cells. A correct grid returns picture { title, category } alongside the ordinary canonical reward receipt, including duplicate receipt recovery. Show the title with the solved pixel picture. The approved minimum time, retry throttle, daily limits and release binding all still apply. Preview validates the same private catalog using separate assignments and never pays rewards.
 - await Twinkle.rewards.getLeaderboard({ metric?: "xp" | "coins", period?: "day" | "week" | "all", limit? }) | scopes: rewards:claim
   - Returns: { mode: "live", metric, period, limit, dayKey, from, available: { xp, coins }, entries: [{ rank, userId, username, profilePicUrl, xp, coins, claims, lastAt }], me: { rank, xp, coins, claims } | null } | { mode: "preview", metric, period, available, entries: [], me: null, message }
   - Standings of who earned the most XP or Coins in THIS app, computed by Twinkle from its own receipts (never from anything the app submits). period 'day' is today (site day, UTC), 'week' the last 7 site days, 'all' (default) every day since approval. limit defaults to 20, max 100.

package/sdk/LUMINE_ADMIN.md

@@ -3886,6 +3886,61 @@ input snapshots as described below.
 See `twinkle-api/JEV_PILOT.md` for configuration,
 the synthetic evaluation step and release checks.
 
+### Spending by calendar month
+
+```bash
+lumine admin spending --from 2026-08 --to 2026-10
+lumine admin spending --month 2026-09 --json --output work/spending-september.json
+lumine admin spending --aws-profile <profile> --json
+```
+
+This owner-only read needs no delegated run. With no dates, it reports the
+previous and current UTC calendar months. Use `--month` for one month, or both
+`--from` and `--to` for an inclusive range of up to 12 months. Future months
+are refused. Current-month AI and AWS usage ends at today's UTC midnight;
+today's partial AI usage is returned separately and excluded from totals.
+Paid reimbursements include today's settled payments through the report time.
+Their separate cutoff is explicit in the table and JSON.
+
+The default output is a table separating AI costs after promotional credits,
+AWS infrastructure including tax, and reimbursements, with a combined total.
+It also shows gross AI usage, credits, and AI-service versus infrastructure
+reimbursements. JSON includes provider and AWS-service details and the paid
+invoice references and dates. AI is a usage-based estimate. Credits follow
+the server's private billing policy and account for usage earlier in the same
+credit cycle, even when that usage predates the requested calendar month.
+
+The API supplies the canonical AI ledger and paid reimbursement history.
+Reimbursements use settlement dates, including old invoices paid later, and
+include all known subscription histories and invoice pages. They are gross
+paid amounts, not Stripe fee/refund or bank-payout reconciliation. Failed,
+expired and pending attempts are excluded; no payment or subscription action
+is performed. Reimbursements are a separate category included in the total;
+`providerOperatingCostUsd` also provides AI plus AWS without reimbursements.
+
+AWS reads use the installed AWS CLI and the existing billing profile, or
+`--aws-profile`. The command checks the required account and principal before
+querying Cost Explorer, paginates service groups, validates exact UTC periods
+and USD currency, and preserves provisional billing status. It never changes
+AWS credentials or infrastructure. Cost Explorer's ordinary query fees apply.
+AWS authentication stays local; it is not uploaded to Twinkle.
+
+`data.spending` is versioned with `schemaVersion: 1`. `months` contains each
+month's `ai`, `aws`, `reimbursements`, `providerOperatingCostUsd`, and
+`totalIncludingReimbursementsUsd`; `totals` sums the selected period. Missing
+sources are `null`, never zero. A partial report preserves available data,
+sets `complete: false` and receipt `status: "partial"`, saves with `--output`,
+and exits nonzero. Unknown provider attribution or AWS-billed AI can make a
+combined total unavailable until the credit/overlap is reconciled. Zero usage
+on the first UTC day means no completed days, not a full-month forecast;
+reimbursements paid on that day still contribute to the total.
+
+This report does not replace the existing AI run-rate projections or AWS
+remaining-period forecast required for a full daily-management review.
+Release dependency: deploy the owner-authorized `/cli/admin/spending` API
+before publishing the CLI that calls it. No new database migration, npm
+dependency or server-side AWS permission is required.
+
 ### Application AI calendar-month cost (standing duty, every full daily review)
 
 Run `lumine admin ai-costs monthly --json` during every full daily management
@@ -5402,6 +5457,36 @@ Since 2026-10-17 Bridge Builder unlocks from QR check-ins: 7 different people, o
 Every decision requires Mikey's authorization for that crew and action. Mutations are audited and idempotent; `--output <path>` is an explicit request to retain the canonical JSON. General write receipts omit private crew details.
 
 
+## Nonogram picture collection
+
+Nonogram's `nonogram-picture-v1` proof uses a private, reviewed picture bank.
+During full daily management, inspect artwork quality and the least unseen
+supply at each size; the target reserve is 14 days at three pictures per size
+per day. This is content maintenance under Mikey's standing daily scope, not
+permission to change reward amounts or publish a creator's app.
+
+```
+lumine admin nonogram status --json
+lumine admin nonogram add --file <pictures.json> --json
+lumine admin nonogram add --file <pictures.json> --confirm --json
+lumine admin nonogram retire <key> [--confirm]
+lumine admin nonogram restore <key> [--confirm]
+```
+
+An import file is an array of 1–150 pictures: `{ key, title, category, rows,
+artReview, difficultyReview }`. `rows` is a 5×5, 10×10 or 15×15 array of binary
+strings. Titles are plain text, at most 80 characters. Draw recognizable art
+first, verify its unique no-guess solve, and visually review it at play size
+before importing. Record actual visual features and the deduction/difficulty
+review, not just a pass count. Never pad the reserve with weak art or variants.
+The server rejects ambiguous puzzles, skips mirror/rotation duplicates, and
+refuses changing the solution under an existing key. Default operations are
+dry runs; confirmed writes are audited. Retirement affects future assignments
+only, preserving started puzzles and receipt recovery. Status separates total
+active pictures from the least unseen supply for the leading live learners.
+Previews have separate assignments. Solutions stay private; catalog refills
+need no app update. Keep prepared inventory distinct from verified live stock.
+
 ## Word Search vocabulary upkeep
 
 Every full daily website-management run adds reviewed Word Master words across all five difficulty bands, with accurate definitions and natural example sentences. Use `lumine admin word-games status`, `candidates <1-5> --after <id> --limit 100`, and `import <reviewed-words.json> --dry-run` followed by the reviewed import. File shape: `{items:[{wordId,word,wordLevel,definition,example}]}` (up to 100). Candidate exports are unreviewed; use agent judgment and check the current censor table before importing. No paid batch APIs. The import is audited and preserves active generation and today's existing puzzles; future banks include the additions. The app receives all five ready banks in its normal HTML and has a bundled checked fallback, so word selection never creates a loading screen or separate word request. Report additions per difficulty and text corrections. Repository agents follow `agent-guides/word-search-vocabulary.md` for the full procedure. A scoped management request does not start this full-run duty.