@stage5/lumine 0.3.30 → 0.3.32

package/lib/admin-receipts.js

@@ -43,6 +43,31 @@ export function receiptToKeep(operation, result) {
         note: report.reviewNote ?? null,
       });
     }
+    // AI bucket changes answer with rule matches (emails, IPs) and member
+    // names; the receipt keeps the decision: ids, modes and counts.
+    case "ai-bucket.restrict":
+    case "ai-bucket.rule.add":
+    case "ai-bucket.rule.disable": {
+      const ruleIds = (rules) =>
+        (rules || []).map((rule) => ({
+          id: rule.id ?? null,
+          kind: rule.kind ?? null,
+          scope: rule.scope ?? null,
+          effectiveRestriction: rule.effectiveRestriction ?? null,
+        }));
+      return keep({
+        bucketId: data.bucket?.id ?? null,
+        restriction: data.bucket?.restriction?.mode ?? null,
+        previousRestriction: data.previous?.mode ?? null,
+        addedRules: ruleIds(data.addedRules),
+        disabledRules: ruleIds(data.disabledRule ? [data.disabledRule] : []),
+        kickedAccountCount: (data.kickedUserIds || []).length,
+        releasedAccountCount: (data.releasedAccounts || []).length,
+        ruleCount: data.ruleCount ?? null,
+        memberCount: data.memberCount ?? null,
+        verified: data.verified === true,
+      });
+    }
     default:
       // Bridge Builder writes answer with the whole crew view: members' who-
       // are-you answers, parents' addresses and questions, held parent emails.

package/lib/admin.js

@@ -12,6 +12,11 @@ import {
 import path from "node:path";
 import { assertAuthScope, resolveAuth } from "./auth.js";
 import { requestJson } from "./http.js";
+import { commitThumbnailImage, readThumbnailFile } from "./thumbnail.js";
+import {
+  THUMBNAIL_CONTENT_TYPE_BY_EXTENSION,
+  THUMBNAIL_MAX_FILE_SIZE_BYTES,
+} from "./constants.js";
 import { receiptToKeep } from "./admin-receipts.js";
 import { prepareAdminMutationIntent } from "./admin-request-intents.js";
 import { formatBytes, parseStorageSizeBytes } from "./util.js";
@@ -202,7 +207,7 @@ const REVIEW_REQUEST_LABELS = {
   cardcraft: "AI Card crafting",
 };
 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>]. A bare id works with --type.";
+  "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.";
 
 function parseReviewRequestType(value) {
   const key = String(value || "")
@@ -370,7 +375,7 @@ function buildApprovalOperation({ action, target, options }) {
 // Code agent passes wrote (no model is called), then review what they could
 // not settle (Mikey 2026-10-06: bulk AI work runs on Claude Code agents).
 const ENGLISH_USAGE =
-  "Use: lumine admin english import <verdicts.json> --pass a|b | adjudicate <verdicts.json> | add-questions <questions.json> | relevel <moves.json> | mastery <userId> --reason <why> | backfill-distractors | summary | review [--limit <n>] | accept|retire <questionId> [--reason <text>] [--fault] | retag <questionId> --skill <code> [--reason <text>] | build-candidates [--after <questionId>] [--limit <n>] | build-import <verdicts.json> | check-candidates [--after <questionId>] [--limit <n>] | check-import <verdicts.json> | check-broken [--after <questionId>] [--limit <n>] | check-apply <fixes.json> | check-verify <checked.json> | check-follow-faulty [--after <next>] [--limit <n>]";
+  "Use: lumine admin english import <verdicts.json> --pass a|b | adjudicate <verdicts.json> | add-questions <questions.json> | relevel <moves.json> | mastery <userId> --reason <why> | backfill-distractors | summary | review [--limit <n>] | accept|retire <questionId> [--reason <text>] [--fault] | retag <questionId> --skill <code> [--reason <text>] | build-candidates [--after <questionId>] [--limit <n>] | build-import <verdicts.json> | check-candidates [--after <questionId>] [--limit <n>] | check-import <verdicts.json> | check-broken [--after <questionId>] [--limit <n>] | check-apply <fixes.json> | check-verify <checked.json> | check-follow-faulty [--after <next>] [--limit <n>] | lesson-candidates [--after <skillCode>] [--limit <n>] | lesson-import <lessons.json> | lesson-approve <approvals.json> | lessons [--status draft|approved]";
 const ENGLISH_IMPORT_MAX = 500;
 
 function buildEnglishOperation({ action, target, options }) {
@@ -452,6 +457,26 @@ function buildEnglishOperation({ action, target, options }) {
     if (after && !/^(?:[ufc]:)?\d+:\d+$/.test(after)) throw cliValidationError("--after takes the last reply's next (<phase:id:version>).");
     return writeOperation("english.check_follow_faulty", "POST", "/cli/admin/english/item-checks/follow-faulty", { after, limit: limitOf(200, 100) }, { requiresRun: false, timeoutMs: 300000 });
   }
+  // Grammar Quest lessons (Mikey 2026-10-11): what the writing pass draws on
+  // (each rule-first point with live sound questions on it), importing
+  // drafts, approving reviewed versions [{ skillCode, version }], the list
+  if (action === "lesson-candidates") {
+    const after = options.adminAfter ? String(options.adminAfter) : "";
+    return readOperation("english.lesson_candidates", withQuery("/cli/admin/english/lessons/candidates", { after, limit: limitOf(64, 20) }), { requiresRun: false });
+  }
+  if (action === "lesson-import" || action === "lesson-approve") {
+    if (!target) throw cliValidationError(ENGLISH_USAGE);
+    const raw = readAdminJsonFile(target, "<file.json>", { maxBytes: 2 * 1024 * 1024 });
+    const items = Array.isArray(raw) ? raw : Array.isArray(raw?.items) ? raw.items : null;
+    if (!items || !items.length || items.length > 100) throw cliValidationError("The file must hold 1 to 100 entries (an array, or { items: [...] }).");
+    const path = action === "lesson-import" ? "/cli/admin/english/lessons/import" : "/cli/admin/english/lessons/approve";
+    return writeOperation(action === "lesson-import" ? "english.lesson_import" : "english.lesson_approve", "POST", path, { items }, { requiresRun: false, timeoutMs: 180000 });
+  }
+  if (action === "lessons") {
+    const status = options.adminStatus || "";
+    if (status && !["draft", "approved"].includes(status)) throw cliValidationError("--status is draft or approved.");
+    return readOperation("english.lessons", withQuery("/cli/admin/english/lessons", status ? { status } : {}), { requiresRun: false });
+  }
   if (action === "check-apply") {
     if (!target) throw cliValidationError(ENGLISH_USAGE);
     const raw = readAdminJsonFile(target, "<fixes.json>", { maxBytes: 4 * 1024 * 1024 });
@@ -925,6 +950,20 @@ function buildRewardProposalOperation(reviewId, options) {
     );
   }
   const files = readRewardProposalDirectory(options.dir);
+  // --title proposes a new app name; --thumbnail <file> a new thumbnail (set
+  // on your proposal workspace copy first), or --thumbnail workspace to offer
+  // the one already set on that copy (e.g. from the website).
+  const title = String(options.title || "").trim();
+  if (title.length > 100) {
+    throw cliValidationError("--title must be at most 100 characters.");
+  }
+  const thumbnail = String(options.adminThumbnail || "").trim();
+  // Checked before signing in or opening the copy; its hash makes a retry
+  // with a different picture a new request rather than a replay.
+  const thumbnailSha256 =
+    thumbnail && thumbnail !== "workspace"
+      ? hashProposalThumbnailFile(thumbnail)
+      : "";
   return writeOperation(
     "reward-review.propose",
     "POST",
@@ -933,11 +972,78 @@ function buildRewardProposalOperation(reviewId, options) {
       files,
       config: readRewardConfigFile(options.adminConfigFile),
       reason,
+      ...(title ? { title } : {}),
+      ...(thumbnail ? { thumbnailFrom: "workspace" } : {}),
+      ...(thumbnailSha256 ? { thumbnailSha256 } : {}),
+    },
+    {
+      requiresRun: false,
+      reviewId,
+      fileCount: files.length,
+      ...(thumbnail && thumbnail !== "workspace"
+        ? {
+            prepare: ({ options: runOptions, auth }) =>
+              setProposalWorkspaceThumbnail({
+                options: runOptions,
+                auth,
+                reviewId,
+                filePath: thumbnail,
+              }),
+          }
+        : {}),
     },
-    { requiresRun: false, reviewId, fileCount: files.length },
   );
 }
 
+// Puts a proposed thumbnail on the reviewer's proposal workspace copy (opened
+// on first use), the copy the offer's thumbnailFrom 'workspace' reads.
+async function setProposalWorkspaceThumbnail({
+  options,
+  auth,
+  reviewId,
+  filePath,
+}) {
+  const { buffer, contentType } = await readThumbnailFile(filePath);
+  const receipt = await requestJson({
+    method: "POST",
+    url: `${options.apiUrl}/cli/admin/reward-reviews/${reviewId}/workspace`,
+    authToken: auth.token,
+    body: {},
+    headers: { "x-lumine-idempotency-key": `cli:${randomUUID()}` },
+    timeoutMs: options.timeoutMs,
+  });
+  const buildId = Number(receipt?.data?.workspace?.buildId || 0);
+  if (!receipt?.ok || !buildId) {
+    throw new Error(
+      receipt?.error || "Could not open the proposal workspace copy.",
+    );
+  }
+  await commitThumbnailImage({ options, auth, buildId, buffer, contentType });
+  // stderr: --json output stays one parseable receipt.
+  console.error(`Proposed thumbnail set on workspace copy (Build #${buildId}).`);
+}
+
+function hashProposalThumbnailFile(filePath) {
+  const extension = path.extname(filePath).toLowerCase();
+  if (!THUMBNAIL_CONTENT_TYPE_BY_EXTENSION[extension]) {
+    throw cliValidationError(
+      `--thumbnail must be a ${Object.keys(THUMBNAIL_CONTENT_TYPE_BY_EXTENSION).join(", ")} file, or "workspace".`,
+    );
+  }
+  let buffer;
+  try {
+    buffer = readFileSync(path.resolve(filePath));
+  } catch {
+    throw cliValidationError(`Thumbnail file does not exist: ${filePath}`);
+  }
+  if (!buffer.length || buffer.length > THUMBNAIL_MAX_FILE_SIZE_BYTES) {
+    throw cliValidationError(
+      `Thumbnail file must be between 1 byte and ${formatBytes(THUMBNAIL_MAX_FILE_SIZE_BYTES)}.`,
+    );
+  }
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
 const REWARD_PROPOSAL_MAX_FILES = 500;
 const REWARD_PROPOSAL_MAX_BYTES = 5 * 1024 * 1024;
 const REWARD_PROPOSAL_SKIPPED_DIRS = new Set([
@@ -1344,6 +1450,12 @@ export async function adminCommand(options) {
     (operation.mutates ? `cli:${randomUUID()}` : "");
   let result;
   try {
+    // A step that must land before the request (e.g. a proposed thumbnail
+    // uploaded to the reviewer's workspace copy); its failure is reported
+    // like the request's own.
+    if (typeof operation.prepare === "function") {
+      await operation.prepare({ options, auth });
+    }
     const fetchOperation = async (requestPath = operation.path, signal) => {
       const receipt = await requestJson({
         method: operation.method,
@@ -1556,6 +1668,9 @@ export async function adminCommand(options) {
   if (operation.name === "ai-email-policy.set") {
     assertAiEmailPolicySetResult({ operation, result });
   }
+  if (AI_BUCKET_CHANGE_OPERATIONS.has(operation.name)) {
+    assertAiBucketChangeResult({ operation, result });
+  }
   if (operation.name === "daily-run.start") {
     assertAdminTodoHandoffResult(result, operation.body.scope);
   }
@@ -2025,6 +2140,42 @@ export function assertAiEmailPolicySetResult({ operation, result }) {
   throw error;
 }
 
+const AI_BUCKET_CHANGE_OPERATIONS = new Set([
+  "ai-bucket.restrict",
+  "ai-bucket.rule.add",
+  "ai-bucket.rule.disable",
+]);
+
+// A bucket change is done only when the API re-read the canonical bucket and
+// confirmed it (verified), and a restriction reads back as the requested mode.
+export function assertAiBucketChangeResult({ operation, result }) {
+  const data = result?.data || {};
+  const requestedMode =
+    operation?.name === "ai-bucket.restrict" ? operation.body?.mode : null;
+  if (
+    result?.ok === true &&
+    data.verified === true &&
+    Number(data.bucket?.id) > 0 &&
+    (!requestedMode || data.bucket?.restriction?.mode === requestedMode)
+  ) {
+    return;
+  }
+  const error = new Error(
+    "The API did not confirm the canonical AI bucket state after this change. Inspect the bucket before retrying.",
+  );
+  error.code = "LUMINE_ADMIN_AI_BUCKET_NOT_VERIFIED";
+  error.data = {
+    ok: false,
+    status: "partial_failure",
+    error: {
+      code: error.code,
+      message: error.message,
+      details: { requestedMode, canonical: result?.data || null },
+    },
+  };
+  throw error;
+}
+
 const RECOMMENDATION_CONTENT_TYPES = new Map([
   ["comment", "comment"],
   ["aistory", "aiStory"],
@@ -2640,6 +2791,78 @@ export function parseAdminOperation(options) {
         },
       );
     }
+    if (action === "inspect") {
+      const reason = String(options.adminReason || "").trim();
+      if (!reason) {
+        throw cliValidationError(
+          "Say why with --reason <management reason>; the inspection is audited.",
+        );
+      }
+      if (reason.length > MAX_IDENTITY_INSPECTION_REASON_LENGTH) {
+        throw cliValidationError(
+          `An inspection reason must be at most ${MAX_IDENTITY_INSPECTION_REASON_LENGTH} characters.`,
+        );
+      }
+      // A read like identity inspect: private evidence is printed, never
+      // kept on disk; the server records who looked, when and why.
+      return bodyReadOperation(
+        "ai-bucket.inspect",
+        "POST",
+        `/cli/admin/ai-buckets/${bucketId}/inspect`,
+        {
+          reason,
+          includePrivateEvidence: options.adminIncludePrivateEvidence === true,
+        },
+      );
+    }
+    if (action === "restrict") {
+      const mode = String(options.adminMode || "");
+      if (!["none", "signup", "full"].includes(mode)) {
+        throw cliValidationError("Pass --mode none, signup or full.");
+      }
+      const body = { mode };
+      if (options.adminMessage !== undefined) {
+        const message = String(options.adminMessage).trim();
+        if (message.length > 500) {
+          throw cliValidationError("--message must be at most 500 characters.");
+        }
+        body.message = message;
+      }
+      return aiBucketChangeOperation({
+        options,
+        name: "ai-bucket.restrict",
+        method: "PUT",
+        path: `/cli/admin/ai-buckets/${bucketId}/restriction`,
+        body,
+        // a restriction changes only on an explicit instruction
+        confirmRequired: true,
+      });
+    }
+    if (action === "rule" && target === "add") {
+      return aiBucketChangeOperation({
+        options,
+        name: "ai-bucket.rule.add",
+        method: "POST",
+        path: `/cli/admin/ai-buckets/${bucketId}/rules`,
+        body: parseAiBucketRuleBody(options),
+        confirmRequired: true,
+      });
+    }
+    if (action === "rule" && target === "disable") {
+      const ruleId = parseRequiredInteger(options.adminRuleId, "--rule-id", 1);
+      const note = String(options.note || "").trim();
+      if (note.length > 180) {
+        throw cliValidationError("--note must be at most 180 characters.");
+      }
+      return aiBucketChangeOperation({
+        options,
+        name: "ai-bucket.rule.disable",
+        method: "POST",
+        path: `/cli/admin/ai-buckets/${bucketId}/rules/${ruleId}/disable`,
+        body: note ? { note } : {},
+        confirmRequired: true,
+      });
+    }
     if (action === "note" && target === "set") {
       return writeOperation(
         "ai-bucket.note.set",
@@ -2728,7 +2951,7 @@ export function parseAdminOperation(options) {
     });
     if (operation) return operation;
     throw cliValidationError(
-      "Usage: lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] | show <id> [--dir <path>] | approve <id> [--config <rules.json>] [--reason <text>] | propose <id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] | reject <id> --reason <text> | revoke <id> --reason <text>.",
+      "Usage: lumine admin reward-review list [--status pending|approved|all] [--cursor <id>] | show <id> [--dir <path>] | approve <id> [--config <rules.json>] [--reason <text>] | propose <id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--title <new app name>] [--thumbnail <image|workspace>] | reject <id> --reason <text> | revoke <id> --reason <text>.",
     );
   }
 
@@ -5065,6 +5288,108 @@ export function assertAdminTodoHandoffResult(result, expectedRunScope = null) {
   return handoff;
 }
 
+// --dry-run is a read (no receipt, nothing changes); a real run is a write
+// that needs --confirm, checked here and again by the server.
+function aiBucketChangeOperation({ options, name, method, path, body, confirmRequired }) {
+  // --allow-shared-network lets a rule reach a shared network (an academy,
+  // a school); it is sent, and printed, only when given
+  if (options.adminAllowSharedNetwork) {
+    if (!["ai-bucket.restrict", "ai-bucket.rule.add"].includes(name)) {
+      throw cliValidationError("--allow-shared-network applies only to restrict and rule add.");
+    }
+    body = { ...body, allowSharedNetwork: true };
+  }
+  if (options.adminDryRun) {
+    return bodyReadOperation(`${name}.preview`, method, path, {
+      ...body,
+      dryRun: true,
+    });
+  }
+  const confirm = options.adminConfirm;
+  if (confirm !== "" && confirm !== "true") {
+    throw cliValidationError("Pass --confirm on its own, without a value.");
+  }
+  if (confirmRequired && confirm !== "true") {
+    throw cliValidationError(
+      "Every bucket change needs --confirm (a rule changes who shares AI Energy, and on a restricted bucket who is blocked). Run it with --dry-run first to see what it changes.",
+    );
+  }
+  return writeOperation(name, method, path, {
+    ...body,
+    ...(confirm === "true" ? { confirm: true } : {}),
+  });
+}
+
+function parseAiBucketRuleBody(options) {
+  const type = String(options.adminType || "");
+  const note = String(options.note || "").trim();
+  if (note.length > 180) {
+    throw cliValidationError("--note must be at most 180 characters.");
+  }
+  const withNote = (body) => (note ? { ...body, note } : body);
+  const scope = () => {
+    const value = String(options.adminScope || "");
+    if (!["signup", "full"].includes(value)) {
+      throw cliValidationError(
+        "Pass --scope signup or full for an IP or device rule.",
+      );
+    }
+    return value;
+  };
+  if (type === "user") {
+    return withNote({
+      type,
+      userId: parseRequiredInteger(options.adminUser, "--user", 1),
+    });
+  }
+  if (type === "email") {
+    const email = String(options.adminEmail || "").trim().toLowerCase();
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      throw cliValidationError("Pass a valid --email <address>.");
+    }
+    if (!options.adminDryRun && !options.adminConfirmEmailRule) {
+      throw cliValidationError(
+        "An email rule covers every account with that verified address. Pass --confirm-email-rule (run --dry-run first to see them).",
+      );
+    }
+    return withNote({
+      type,
+      email,
+      ...(options.adminConfirmEmailRule ? { confirmEmailRule: true } : {}),
+    });
+  }
+  if (type === "ip") {
+    const ip = String(options.adminIp || "").trim();
+    if (!ip) throw cliValidationError("Pass --ip <address>.");
+    return withNote({
+      type,
+      ip,
+      scope: scope(),
+      ...(options.adminIncludePrefix ? { includePrefix: true } : {}),
+    });
+  }
+  if (type === "device") {
+    if (!/^[a-f0-9]{16}$/.test(options.adminDeviceKey || "")) {
+      throw cliValidationError(
+        "Pass --device-key with the exact key from ai-bucket inspect or identity inspect.",
+      );
+    }
+    if (!options.adminDryRun && !note) {
+      throw cliValidationError("Say why with --note <reason> for a device rule.");
+    }
+    return withNote({
+      type,
+      sourceUserId: parseRequiredInteger(options.adminUser, "--user", 1),
+      deviceKey: options.adminDeviceKey,
+      scope: scope(),
+      ...(options.adminUserIds || !options.adminDryRun
+        ? { expectedUserIds: parseAiBucketUserIds(options.adminUserIds) }
+        : {}),
+    });
+  }
+  throw cliValidationError("Pass --type user, email, ip or device.");
+}
+
 function readOperation(name, path, extra = {}) {
   return {
     name,
@@ -5749,6 +6074,10 @@ function printRewardReviewResult({ operation, data }) {
     );
     for (const file of review.proposal.changedFiles || [])
       console.log(`  ${file.status}: ${file.path}`);
+    if (review.proposal.title)
+      console.log(`  new name: ${review.proposal.title}`);
+    if (review.proposal.thumbnailUrl)
+      console.log(`  new thumbnail: ${review.proposal.thumbnailUrl}`);
   }
   if (review.status === "rejected" && review.declinedByCreator) {
     console.log(
@@ -6826,6 +7155,174 @@ function printRewardBankReport(data) {
   }
 }
 
+function aiBucketRestrictionLabel(restriction) {
+  const mode = restriction?.mode || "none";
+  const label = mode === "none" ? "unrestricted" : mode === "signup" ? "signup-only" : "full";
+  return restriction?.message ? `${label} — "${restriction.message}"` : label;
+}
+
+function formatAiBucketAccounts(accounts) {
+  return (accounts || []).length
+    ? accounts.map((a) => `${a.username || "?"} (#${a.userId})`).join(", ")
+    : "none";
+}
+
+function printAiBucketNetworkRuleChanges(changes) {
+  if (!changes?.length) return;
+  console.log("Network/device rules whose restriction changes:");
+  for (const c of changes) {
+    const r = c.reach;
+    const reach = !c.strengthens
+      ? "loosens"
+      : !r?.measured
+        ? "reach NOT MEASURED"
+        : `${r.accountCount}${r.lowerBound ? "+" : ""} account(s)${r.sharedNetwork ? " — SHARED NETWORK" : ""}`;
+    console.log(`  #${c.ruleId} ${c.kind} ${c.match}: ${c.from} → ${c.to} · ${reach}`);
+  }
+}
+
+function printAiBucketBlockers(blockers, overrideGiven) {
+  for (const blocker of blockers || []) {
+    if (blocker.overridable && overrideGiven) {
+      console.log(`OVERRIDDEN by --allow-shared-network (${blocker.code}): ${blocker.message}`);
+    } else {
+      console.log(`BLOCKED (${blocker.code}): ${blocker.message}${blocker.overridable ? " Only --allow-shared-network, on Mikey's explicit word, lifts this." : ""}`);
+    }
+  }
+}
+
+function printAiBucketRules(rules, indent = "  ") {
+  for (const rule of rules || []) {
+    console.log(
+      `${indent}#${rule.id} ${rule.kind} ${rule.match} · scope ${rule.scope} · effective ${rule.effectiveRestriction}${rule.note ? ` · ${rule.note}` : ""}`,
+    );
+  }
+}
+
+// The bucket commands of todo 79 (inspect, restrict, rule add/disable and
+// their --dry-run previews). Returns false for the older ai-bucket commands.
+function printAiBucketRuleResult({ operation, data }) {
+  const name = operation.name;
+  const head = (bucket) =>
+    `AI bucket #${bucket.id} (${bucket.label}): ${aiBucketRestrictionLabel(bucket.restriction)}`;
+  if (name === "ai-bucket.inspect") {
+    console.log(`${head(data.bucket)}; ${data.rules.length} active rule(s), ${data.memberCount} member account(s).`);
+    if (data.bucket.note) console.log(`Note: ${data.bucket.note}`);
+    console.log("Rules:");
+    printAiBucketRules(data.rules);
+    console.log(
+      `Members: ${(data.members || []).map((m) => `${m.username || "?"} (#${m.userId}${m.viaEmailRule ? ", via email rule" : ""})`).join(", ") || "none"}`,
+    );
+    for (const account of data.evidence?.accounts || []) {
+      console.log(`Evidence for ${account.username || "?"} (#${account.userId})${account.canonicalBucketId && account.canonicalBucketId !== data.bucket.id ? ` · resolves to bucket #${account.canonicalBucketId}` : ""}:`);
+      if (!account.devices.length) console.log("    Devices: none recorded");
+      for (const device of account.devices) {
+        const rule = device.ruleId ? ` · rule #${device.ruleId}` : "";
+        if (device.sharedDevice) {
+          console.log(`    Device ${device.key}: shared by ${device.accountCount} accounts (not listed; not family evidence)${rule}`);
+          continue;
+        }
+        const others = device.otherAccounts.length
+          ? device.otherAccounts.map((a) => `${a.username || "?"} (#${a.userId})${a.inBucket ? "" : " OUTSIDE bucket"}`).join(", ")
+          : "no other account";
+        console.log(`    Device ${device.key}: ${device.accountCount} account(s); others: ${others}${device.accountsTruncated ? " (more not listed)" : ""}${device.status !== "complete" ? ` · ${device.status}` : ""}${rule}`);
+      }
+      printNetwork(account.network, "    ");
+      const ruled = (account.network?.addresses || []).filter((a) => a.ruleId);
+      if (ruled.length) {
+        console.log(`    IP rules matching these addresses: ${ruled.map((a) => `#${a.ruleId} [${a.addressId}]`).join(", ")}`);
+      }
+    }
+    if (data.evidence?.membersNotInspected) {
+      console.log(`Evidence covers the first ${data.evidence.membersInspected} members; ${data.evidence.membersNotInspected} not inspected.`);
+    }
+    console.log(data.interpretation);
+    return true;
+  }
+  if (name === "ai-bucket.restrict.preview") {
+    const p = data.preview;
+    console.log(`DRY RUN ${head(data.bucket)} → ${aiBucketRestrictionLabel(p.to)}${p.changed ? "" : " (no change)"}.`);
+    console.log(`Accounts it reaches: ${formatAiBucketAccounts(p.memberAccounts)}`);
+    console.log(`Sessions dropped: ${p.sessionsKickedUserIds.length ? p.sessionsKickedUserIds.map((id) => `#${id}`).join(", ") : "none"}; existing logins ${p.existingLoginsPreserved ? "kept" : "ended"}; existing bans kept.`);
+    if (p.fullBlockLiftedUserIds.length) console.log(`Full block lifted for: ${p.fullBlockLiftedUserIds.map((id) => `#${id}`).join(", ")} (unless another restriction still applies).`);
+    if (p.adminConflictUserIds.length) console.log(`BLOCKED: admin account(s) ${p.adminConflictUserIds.map((id) => `#${id}`).join(", ")} cannot be fully restricted.`);
+    printAiBucketNetworkRuleChanges(p.networkRuleChanges);
+    printAiBucketBlockers(p.blockers, data.sharedNetworkOverride);
+    console.log("Nothing was changed. Run again with --confirm to apply.");
+    return true;
+  }
+  if (name === "ai-bucket.restrict") {
+    console.log(`${head(data.bucket)} (was ${aiBucketRestrictionLabel(data.previous)}); verified.`);
+    printAiBucketNetworkRuleChanges(data.networkRuleChanges);
+    if (data.sharedNetworkOverride) console.log("OVERRIDE USED: --allow-shared-network — a shared network or unmeasured rule is now restricted.");
+    console.log(`Sessions dropped: ${data.kickedUserIds.length ? data.kickedUserIds.map((id) => `#${id}`).join(", ") : "none"}; existing logins ${data.existingLoginsPreserved ? "kept" : "ended"}; existing bans kept.`);
+    return true;
+  }
+  if (name === "ai-bucket.rule.add.preview") {
+    console.log(`DRY RUN ${head(data.bucket)} (the real run needs --confirm).`);
+    if (data.device) {
+      const d = data.device;
+      if (d.sharedDevice) {
+        console.log(`Shared device: ${d.observedAccountCount} accounts (${d.outsideBucketCount} outside this bucket); not listed, not family evidence.`);
+      } else {
+        console.log(`Device ${d.key} (${d.scope}) from #${d.sourceUserId}: seen on ${d.observedUserIds.map((id) => `#${id}`).join(", ") || "no account"} in ${d.lookbackDays} days; effective ${data.effectiveRestriction}.`);
+        if (d.outsideBucketUserIds.length) console.log(`Outside this bucket: ${d.outsideBucketUserIds.map((id) => `#${id}`).join(", ")}`);
+      }
+      if (d.existingRuleId) console.log(`Existing rule #${d.existingRuleId} in bucket #${d.existingRuleBucketId}.`);
+      if (!(data.blockers || []).length) console.log(`Pass the reviewed accounts with --user-ids ${d.observedUserIds.join(",")} on the real run.`);
+    } else {
+      const p = data.preview;
+      const r = p.rule;
+      console.log(`Rule: ${r.type} ${r.userId ? `#${r.userId}` : r.email || r.ip}${r.scope ? ` · scope ${r.scope}` : ""}${r.prefixRuleTypes?.length ? ` + prefix rules ${r.prefixRuleTypes.join(", ")}` : ""}; effective ${p.effectiveRestriction}.`);
+      if (p.existingRule) console.log(`Existing rule #${p.existingRule.ruleId} in bucket #${p.existingRule.bucketId} (${p.existingRule.bucketLabel}).`);
+      if (p.affectedAccounts) console.log(`Accounts it names: ${formatAiBucketAccounts(p.affectedAccounts)}`);
+      if (p.exactAddress) {
+        const a = p.exactAddress;
+        console.log(a.kind === "shared_network"
+          ? `Address [${a.addressId}]: shared network, ${a.accountCount} accounts (not listed; not family evidence).`
+          : `Address [${a.addressId}]: ${a.accountCount} account(s): ${formatAiBucketAccounts(a.accounts)}${a.olderHistoryNotRead ? " · older history not read" : ""}`);
+      }
+      if (p.prefixReach) {
+        const r = p.prefixReach;
+        console.log(r.measured
+          ? `Prefix: at least ${r.accountCount} account(s) used AI from it${r.sharedNetwork ? " — shared network" : ""}${r.olderHistoryNotRead ? " · older history not read" : ""} (accounts that never used AI there are not counted).`
+          : "Prefix: reach could not be measured.");
+      }
+      for (const existing of p.existingPrefixRules || []) {
+        if (existing) console.log(`Existing prefix rule #${existing.ruleId} in bucket #${existing.bucketId} (${existing.scope}).`);
+      }
+      if (p.sessionsKickedUserIds.length) console.log(`Sessions dropped: ${p.sessionsKickedUserIds.map((id) => `#${id}`).join(", ")}`);
+    }
+    printAiBucketBlockers(data.blockers || data.preview?.blockers || [], data.sharedNetworkOverride);
+    console.log(`Would change: ${data.wouldChange ? "yes" : "no"}. Nothing was changed.`);
+    return true;
+  }
+  if (name === "ai-bucket.rule.add") {
+    console.log(`${head(data.bucket)}; rule saved; ${data.ruleCount} active rule(s), ${data.memberCount} member(s); verified.`);
+    printAiBucketRules(data.addedRules);
+    if (data.sharedNetworkOverride) console.log("OVERRIDE USED: --allow-shared-network — this rule reaches a shared network.");
+    if (data.kickedUserIds?.length) console.log(`Sessions dropped: ${data.kickedUserIds.map((id) => `#${id}`).join(", ")}`);
+    return true;
+  }
+  if (name === "ai-bucket.rule.disable.preview") {
+    const p = data.preview;
+    console.log(`DRY RUN ${head(data.bucket)} (the real run needs --confirm).`);
+    printAiBucketRules([p.rule]);
+    console.log(p.alreadyDisabled ? "Already disabled." : `Released accounts: ${formatAiBucketAccounts(p.releasedAccounts)}${p.liftsRestriction ? " (each keeps any other restriction that still applies)" : ""}.`);
+    if (p.prefixRulesRemainActive) {
+      console.log(`${p.prefixNote}${p.companionPrefixRuleIds?.length ? ` Its prefix rules here: ${p.companionPrefixRuleIds.map((id) => `#${id}`).join(", ")}.` : ""}`);
+    }
+    console.log(`Would change: ${data.wouldChange ? "yes" : "no"}. Nothing was changed.`);
+    return true;
+  }
+  if (name === "ai-bucket.rule.disable") {
+    console.log(`${head(data.bucket)}; rule #${data.disabledRule.id} disabled; ${data.ruleCount} active rule(s), ${data.memberCount} member(s); verified.`);
+    console.log(`Released accounts: ${formatAiBucketAccounts(data.releasedAccounts)}`);
+    return true;
+  }
+  return false;
+}
+
 function printAdminResult({ operation, result }) {
   const data = result?.data || {};
   if (printChatSafetyResult({ operation, data })) return;
@@ -6838,6 +7335,9 @@ function printAdminResult({ operation, result }) {
     for (const line of formatProfileReview(data)) console.log(line);
     return;
   }
+  if (operation.name.startsWith("ai-bucket.") && printAiBucketRuleResult({ operation, data })) {
+    return;
+  }
   if (operation.name === "reward-activity.report") {
     printRewardActivity(data);
     return;

package/lib/commands.js

@@ -2478,7 +2478,14 @@ export function parseArgs(args) {
     "show",
     "foreground",
     "open",
+    "dryRun",
+    "confirmEmailRule",
+    "includePrefix",
+    "allowSharedNetwork",
   ]);
+  // A flag that may stand alone (true) or carry a value: `--confirm` confirms
+  // an AI bucket change; `meetup slot <crewId> --confirm <slotIndex>` picks a slot.
+  const optionalValueFlags = new Set(["confirm"]);
 
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];
@@ -2499,6 +2506,12 @@ export function parseArgs(args) {
           : inlineValue;
     } else if (booleanFlags.has(camelKey)) {
       raw[camelKey] = true;
+    } else if (
+      optionalValueFlags.has(camelKey) &&
+      // a following flag (`--json`, `-h`) is never taken as the value
+      (rest[i + 1] === undefined || rest[i + 1].startsWith("-"))
+    ) {
+      raw[camelKey] = true;
     } else {
       const nextValue = rest[i + 1];
       if (
@@ -2732,6 +2745,13 @@ export function parseArgs(args) {
         : "",
     adminBucketId: raw.bucketId ? String(raw.bucketId) : "",
     adminDeviceKey: raw.deviceKey ? String(raw.deviceKey) : "",
+    adminRuleId: raw.ruleId ? String(raw.ruleId) : "",
+    adminIp: raw.ip ? String(raw.ip) : "",
+    adminMessage: raw.message === undefined ? undefined : String(raw.message),
+    adminDryRun: Boolean(raw.dryRun),
+    adminConfirmEmailRule: Boolean(raw.confirmEmailRule),
+    adminIncludePrefix: Boolean(raw.includePrefix),
+    adminAllowSharedNetwork: Boolean(raw.allowSharedNetwork),
     adminLabel: raw.label ? String(raw.label) : "",
     adminUserIds: raw.userIds ? String(raw.userIds) : "",
     adminUser: raw.user ? String(raw.user) : "",
@@ -2786,6 +2806,8 @@ export function parseArgs(args) {
     adminForeground: Boolean(raw.foreground),
     adminOpen: Boolean(raw.open),
     adminConfigFile: raw.config ? String(raw.config) : "",
+    // admin review propose --thumbnail <image|workspace>
+    adminThumbnail: raw.thumbnail ? String(raw.thumbnail) : "",
     adminReviewedBuildVersion: raw.reviewedVersion
       ? String(raw.reviewedVersion)
       : "",
@@ -3177,6 +3199,15 @@ export function printHelp() {
   lumine admin ai-bucket accounts add --bucket-id <id> --user-ids <id,id,...> [--note <text>] [--json]
   lumine admin ai-bucket device block-signup --bucket-id <id> --user <source-user-id> --device-key <inspection-key> --user-ids <reviewed-device-users> --note <reason> [--json]
   lumine admin ai-bucket note set --bucket-id <id> --note <text> [--json]
+  lumine admin ai-bucket inspect --bucket-id <id> --reason <management reason> [--include-private-evidence] [--json]
+  lumine admin ai-bucket restrict --bucket-id <id> --mode none|signup|full [--message <text>] [--allow-shared-network] (--dry-run | --confirm) [--json]
+  lumine admin ai-bucket rule add --bucket-id <id> --type user --user <id> [--note <text>] (--dry-run | --confirm) [--json]
+  lumine admin ai-bucket rule add --bucket-id <id> --type email --email <address> [--note <text>] (--dry-run | --confirm-email-rule --confirm) [--json]
+  lumine admin ai-bucket rule add --bucket-id <id> --type ip --ip <address> --scope signup|full [--include-prefix] [--allow-shared-network] [--note <text>] (--dry-run | --confirm) [--json]
+  lumine admin ai-bucket rule add --bucket-id <id> --type device --user <source-user-id> --device-key <inspect-key> --scope signup|full --user-ids <reviewed-device-users> --note <reason> (--dry-run | --confirm) [--json]
+  lumine admin ai-bucket rule disable --bucket-id <id> --rule-id <id> [--note <text>] (--dry-run | --confirm) [--json]
+      (every real change needs --confirm; --dry-run shows exactly what would change and writes nothing;
+       a shared network (academy, school) or an unmeasured prefix is refused unless --allow-shared-network, only on Mikey's explicit word)
   lumine admin ai-email-policy get --email <address> [--json]
   lumine admin ai-email-policy set --email <address> --mode <automatic|separate_accounts> --note <text> [--json]
   lumine admin daily-run start [--scope full|featured|newspaper] [--identity zero|ciel|auto] [--comment-mode off|draft|post] [--run-key <key>] [--json]
@@ -3216,7 +3247,7 @@ export function printHelp() {
   lumine admin chat-reports suspend --user <id> --note <why> [--json]   (full ban: signs them out)
   lumine admin reward-review show <review-id> [--dir <path>] [--json]
   lumine admin reward-review approve <review-id> [--config <rules.json>] [--reason <text>] [--json]   (approval publishes the approved version)
-  lumine admin reward-review propose <review-id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--json]
+  lumine admin reward-review propose <review-id> --dir <edited-snapshot> --config <rules.json> [--reason <text>] [--title <new app name>] [--thumbnail <image|workspace>] [--json]
   lumine admin reward-review reject|revoke <review-id> --reason <text> [--json]
   lumine admin recommendations list [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin builds candidates [--since-run|--after <date>|--include-legacy] [--all --checkpoint <file> [--resume]] [--cursor <cursor>] [--limit <number>] [--json]

package/lib/thumbnail.js

@@ -134,6 +134,27 @@ export async function thumbnailSet(options) {
   if (!filePath) {
     throw new Error("Usage: lumine thumbnail set <file> (jpg, png, or webp)");
   }
+  const { buffer, contentType } = await readThumbnailFile(filePath);
+
+  const { buildId, auth, build } = await resolveThumbnailContext(options);
+  const proceed = await confirmThumbnailOverwrite({ options, build, buildId });
+  if (!proceed) return;
+
+  const { thumbnailUrl } = await commitThumbnailImage({
+    options,
+    auth,
+    buildId,
+    buffer,
+    contentType,
+  });
+  console.log(`Thumbnail set for Build #${buildId}:`);
+  console.log(`  ${thumbnailUrl}`);
+  console.log("Tip: thumbnails display ~16:9; the image was uploaded uncropped.");
+}
+
+// A local jpg/png/webp checked against the thumbnail limits, ready for
+// commitThumbnailImage (also used by `lumine admin review propose --thumbnail`).
+export async function readThumbnailFile(filePath) {
   const absolutePath = path.resolve(filePath);
   const extension = path.extname(absolutePath).toLowerCase();
   const contentType = THUMBNAIL_CONTENT_TYPE_BY_EXTENSION[extension];
@@ -159,21 +180,7 @@ export async function thumbnailSet(options) {
       `Thumbnail file is too big (${formatBytes(buffer.length)}; max ${formatBytes(THUMBNAIL_MAX_FILE_SIZE_BYTES)}).`,
     );
   }
-
-  const { buildId, auth, build } = await resolveThumbnailContext(options);
-  const proceed = await confirmThumbnailOverwrite({ options, build, buildId });
-  if (!proceed) return;
-
-  const { thumbnailUrl } = await commitThumbnailImage({
-    options,
-    auth,
-    buildId,
-    buffer,
-    contentType,
-  });
-  console.log(`Thumbnail set for Build #${buildId}:`);
-  console.log(`  ${thumbnailUrl}`);
-  console.log("Tip: thumbnails display ~16:9; the image was uploaded uncropped.");
+  return { buffer, contentType };
 }
 
 function decodeImageDataUrl(dataUrl) {

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -131,7 +131,8 @@ canonical bucket. Use it to distinguish quota bookkeeping from moderation;
 the note itself changes no access, ban, or identity rules.
 
 The commands above are quota bookkeeping only. They cannot ban accounts, block signup,
-add IP/device/risk-key rules, or infer an account family. Identification
+add IP/device/risk-key rules, or infer an account family (the explicit
+restricted-bucket commands below can, on Mikey's instruction). Identification
 remains a human/LLM evidence judgment and must be explicitly requested by
 Mikey; routine administrator runs still escalate suspected alternate accounts
 and never auto-enforce. `accounts add` and `note set` still accept only an
@@ -159,6 +160,85 @@ raw device ID. The private audit records the request before evidence is read
 and records successful completion separately. Routine reviews still never
 auto-enforce; this action requires Mikey's explicit instruction for the device.
 
+### Restricted buckets: inspect, rules and restrictions
+
+These are the operator path for buckets with a restriction (and for adding
+email, IP and device rules to any bucket). They use the same shared operations
+as the Management page, so each change has the same side effects there
+(current-day usage re-attribution, ban cache, member notification and kicks,
+live quota updates). Use them only on Mikey's explicit instruction for that
+bucket, rule or restriction.
+
+```bash
+lumine admin ai-bucket inspect --bucket-id 4 --reason "todo 79 review" --json
+lumine admin ai-bucket restrict --bucket-id 4 --mode signup --dry-run
+lumine admin ai-bucket restrict --bucket-id 4 --mode signup --confirm
+lumine admin ai-bucket rule add --bucket-id 4 --type user --user 18559 --dry-run
+lumine admin ai-bucket rule add --bucket-id 4 --type user --user 18559 --confirm
+lumine admin ai-bucket rule add --bucket-id 4 --type email \
+  --email family@example.com --confirm-email-rule --confirm
+lumine admin ai-bucket rule add --bucket-id 4 --type ip --ip 58.151.12.59 \
+  --scope signup [--include-prefix] --confirm
+lumine admin ai-bucket rule add --bucket-id 4 --type device --user 18559 \
+  --device-key 0123456789abcdef --scope signup --user-ids 18559,20001 \
+  --note "Mikey approved this reviewed device" --confirm
+lumine admin ai-bucket rule disable --bucket-id 4 --rule-id 77 --dry-run
+```
+
+`inspect` works for unrestricted and restricted buckets. It returns the
+canonical bucket (label, note, restriction `none|signup|full`, message), every
+active rule (id, kind, scope, effective restriction, match), the canonical
+members, every account a full restriction would reach, and for each member
+(first 25) their devices (inspection keys, never raw IDs) and network
+addresses with how many accounts share each. A device or address used by many
+accounts (an academy, a school) is counted, marked shared and never listed or
+treated as family evidence. Addresses and email-rule addresses (in evidence, rules and rule notes)
+are masked unless `--include-private-evidence`; every other output, and the
+audit, keeps them masked (with a keyed hash in the audit). `--reason` is required; the API commits an
+access receipt before reading evidence.
+
+`--dry-run` on `restrict`, `rule add` and `rule disable` is a read: it returns
+the current and resulting restriction, the accounts newly affected or released,
+the accounts whose sessions a full restriction drops, admin conflicts and any
+blocker, and changes nothing. Device, IP and email previews read private
+evidence, so they record an access receipt; the others record nothing.
+
+A real run is audited (request receipt with the idempotency key and payload
+fingerprint, then the completed result) and returns the bucket read back from
+the database and checked (`verified: true`); the CLI refuses a result that
+does not confirm the requested state. A failure after the change started is
+recorded as failed; a replay with the same idempotency key returns the stored
+result instead of running again.
+
+- `restrict` always needs `--confirm`. `signup` blocks only new accounts:
+  existing logins and existing bans (`users.banned`) stay as they are. `full`
+  drops members' sessions and is refused while any member is an admin. `none`
+  lifts the restriction; each member gets its effective ban state pushed again.
+  Without `--message` the current message is kept. The preview and the
+  result list every IP, prefix and device rule whose effective restriction
+  changes, with how many accounts it reaches (exact IPs from site activity;
+  prefixes and devices from a year of AI usage, a lower bound). A rule that
+  gets stronger on a shared network (more than 8 accounts) or whose reach
+  can't be measured refuses the change unless `--allow-shared-network` is
+  passed; use it only on Mikey's explicit word. The CLI prints the override.
+  Saving a full bucket again (even only a new message) re-kicks its members,
+  as on the Management page; the preview lists them.
+- `rule add` / `rule disable` always need `--confirm` too: on an unrestricted
+  bucket a rule still pools AI Energy, on a restricted one it changes who is
+  blocked. On a fully restricted bucket an account or email rule re-kicks every
+  account the bucket reaches (as on the Management page); the preview lists them.
+  Email rules cover every account with that verified address and also need
+  `--confirm-email-rule`. IP and device rules need `--scope`; IP prefix rules
+  (`--include-prefix`, the whole /24 or /64) are opt-in, their reach measured
+  as above. A shared exact address or prefix, or an unmeasured prefix under a
+  full restriction, is refused unless `--allow-shared-network`. An address or
+  prefix rule held by another bucket is refused, never moved. Device rules
+  keep the `device block-signup` guards: the reviewed `--user-ids` must equal
+  the accounts seen on the device, all inside the bucket; a device more than
+  9 accounts used is shared (counted, not listed, refused). Disabling an exact
+  IP rule leaves its prefix rules active (the preview names them).
+  `rule disable` keeps `--note` in the audit receipt only.
+
 ### Shared verified-email policies
 
 A verified address proves that an account can use that mailbox; it does not
@@ -1320,10 +1400,19 @@ lumine admin reward-review approve 2 --config rules.json \
 lumine admin reward-review show 2 --dir /private/tmp/reward-review-2 --json   # then edit that directory…
 lumine admin reward-review propose 2 --dir /private/tmp/reward-review-2 \
   --config rules.json --reason "Moved the claim after the stage clears" --json  # …and offer it
+lumine admin reward-review propose 2 --dir /private/tmp/reward-review-2 --config rules.json \
+  --title "Word Forge" --thumbnail cover.png --json         # …also offering a new name and thumbnail
 lumine admin reward-review reject 2 --reason "Rewards fire on game over; nothing is earned" --json
 lumine admin reward-review revoke 2 --reason "Farmable; pausing until redesigned" --json
 ```
 
+A proposal can also offer the app a new name (`--title`, at most 100
+characters) and a new thumbnail (`--thumbnail <jpg|png|webp>`, uploaded to your
+proposal workspace copy first; `--thumbnail workspace` offers the one already
+set on that copy, e.g. from the website). Both are frozen with the offer and
+applied together with the files and rules when the creator accepts. An offer
+may change only the name or thumbnail; the files can then stay as submitted.
+
 `show --dir` writes the exact reviewed snapshot (private files, including the
 app's own `rewards.json`) so the agent can read it like a pulled workspace. The
 result's `config` is the proposal: the declared economy with the sheet's