@stage5/lumine 0.2.33 → 0.2.34

package/README.md

@@ -169,6 +169,7 @@ lumine admin daily-run start --identity auto --comment-mode off --json
 lumine admin recommendations list --cursor '<cursor>' --json
 lumine admin subjects candidates --after 2026-08-01T00:00:00Z --json
 lumine admin subjects candidates --effort unassigned --json
+lumine admin builds candidates --cursor '<cursor>' --json
 lumine admin subject get 123 --include-comments --json
 lumine admin post get https://www.twin-kle.com/ai-stories/88 --json
 lumine admin post comments dailyReflection:99 --json
@@ -184,6 +185,9 @@ lumine admin brief --days 3 --json
 lumine admin notable add Minecrarft_guy --note "Created 8 thoughtful subjects and helped peers in 23 comments this window." --json
 lumine admin post recommend comment:456 --anyone-can-reward --reward-twinkles 3 --json
 lumine admin post reward comment:456 --twinkles 3 --json
+lumine admin comment draft build:884 --file comment.md \
+  --reviewed-version 4512 --reviewed-via runtime --json
+lumine admin comment post --draft-id 77 --json
 lumine admin daily-run complete --json
 ```
 
@@ -195,6 +199,13 @@ and posts use the selected bot's server-owned canonical persona; a later human
 reply is handled by Twinkle's existing autonomous Zero/Ciel responder without
 Lumine remaining active.
 
+Management agents also inspect recent public Build candidates during each run.
+A direct Build comment is never server-generated: first open and try the
+published app or pull and read its code, then compose with `--file` and bind
+the draft to the exact `publishedArtifactVersionId` using
+`--reviewed-version` and `--reviewed-via runtime|code`. The server rejects
+missing or stale review evidence and any app/thread change before publication.
+
 Every operation is noninteractive when its required arguments are present.
 `--json` prints exactly one uncolored JSON value and returns a nonzero status
 for forbidden, not-found, validation, and partial-failure responses. Pass a

package/lib/admin.js

@@ -125,6 +125,12 @@ export async function adminCommand(options) {
       },
       timeoutMs: options.timeoutMs,
     });
+    if (operation.name === "builds.candidates") {
+      result = normalizeAdminBuildCandidatesResult({
+        result,
+        siteUrl: options.siteUrl,
+      });
+    }
     if (recommendationContentTypes) {
       result = filterRecommendationQueueResult({
         result,
@@ -179,6 +185,38 @@ export async function adminCommand(options) {
   return result;
 }
 
+export function normalizeAdminBuildCandidatesResult({ result, siteUrl }) {
+  const builds = Array.isArray(result?.builds) ? result.builds : [];
+  const nextCursor = String(result?.cursor || "").trim() || null;
+  return {
+    ok: true,
+    status: "success",
+    data: {
+      builds: builds.map((build) => {
+        const id = Number(build?.id || 0);
+        return {
+          ...build,
+          url:
+            id > 0
+              ? `${String(siteUrl || "").replace(/\/$/, "")}/app/${id}`
+              : null,
+          review: {
+            publishedArtifactVersionId:
+              Number(build?.publishedArtifactVersionId || 0) || null,
+            codePullAvailable: build?.collaborationMode === "open_source",
+            requiredBeforeComment: true,
+          },
+        };
+      }),
+      pagination: {
+        nextCursor,
+        hasMore: Boolean(nextCursor),
+        exhausted: !nextCursor,
+      },
+    },
+  };
+}
+
 export function assertComposedCommentDraftResult({ result, expectedContent }) {
   const draft = result?.data?.draft;
   if (
@@ -385,6 +423,25 @@ export function parseAdminOperation(options) {
         },
       );
     }
+    if (action === "note" && target === "set") {
+      const note = String(options.note || "").trim();
+      if (!note) {
+        throw cliValidationError(
+          "Pass the quota-only context with --note <text>.",
+        );
+      }
+      if (note.length > 255) {
+        throw cliValidationError(
+          "An AI bucket note can be at most 255 characters.",
+        );
+      }
+      return writeOperation(
+        "ai-bucket.note.set",
+        "PUT",
+        `/cli/admin/ai-buckets/${bucketId}/note`,
+        { note },
+      );
+    }
   }
 
   if (namespace === "daily-run") {
@@ -434,6 +491,18 @@ export function parseAdminOperation(options) {
     );
   }
 
+  if (namespace === "builds" && action === "candidates") {
+    return readOperation(
+      "builds.candidates",
+      withQuery("/build/public/list", {
+        sort: "recent",
+        scope: "all",
+        cursor: options.adminCursor,
+        limit: options.limit,
+      }),
+    );
+  }
+
   if (
     namespace === "subjects" &&
     (action === "list" || action === "candidates")
@@ -671,7 +740,7 @@ export function parseAdminOperation(options) {
   }
 
   if (namespace === "bot-output" && !action) {
-    if (options.adminDays !== undefined) {
+    if (options.adminDays) {
       const days = Number(options.adminDays);
       if (!Number.isInteger(days) || days < 1 || days > 30) {
         throw cliValidationError("--days must be an integer between 1 and 30.");
@@ -703,7 +772,7 @@ export function parseAdminOperation(options) {
 
   if (namespace === "comment") {
     if (action === "draft" || action === "reply") {
-      const parsedTarget = parseRecommendationTarget({
+      const parsedTarget = parseAdminCommentTarget({
         target,
         explicitType: options.adminType,
       });
@@ -712,6 +781,35 @@ export function parseAdminOperation(options) {
           "comment reply targets a comment: lumine admin comment reply comment:<id>.",
         );
       }
+      const reviewedBuildVersionId = options.adminReviewedBuildVersion
+        ? parseRequiredInteger(
+            options.adminReviewedBuildVersion,
+            "--reviewed-version",
+            1,
+          )
+        : undefined;
+      const buildReviewMethod = options.adminBuildReviewMethod
+        ? parseAdminBuildReviewMethod(options.adminBuildReviewMethod)
+        : undefined;
+      if (parsedTarget.type === "build") {
+        if (!options.adminFile) {
+          throw cliValidationError(
+            "Build comments are management-agent composed only; pass --file <comment.md> after reviewing the project.",
+          );
+        }
+        if (!reviewedBuildVersionId || !buildReviewMethod) {
+          throw cliValidationError(
+            "After reviewing the project, pass both --reviewed-version <published-artifact-id> and --reviewed-via runtime|code.",
+          );
+        }
+      } else if (
+        parsedTarget.type !== "comment" &&
+        (reviewedBuildVersionId || buildReviewMethod)
+      ) {
+        throw cliValidationError(
+          "Build review evidence applies only to build:<id> or a comment:<id> inside a Build.",
+        );
+      }
       return writeOperation(
         "comment.draft",
         "POST",
@@ -725,6 +823,8 @@ export function parseAdminOperation(options) {
           ...(options.adminFile
             ? { content: readComposedCommentFile(options.adminFile) }
             : {}),
+          ...(reviewedBuildVersionId ? { reviewedBuildVersionId } : {}),
+          ...(buildReviewMethod ? { buildReviewMethod } : {}),
         },
       );
     }
@@ -768,7 +868,7 @@ export function parseAdminOperation(options) {
   }
 
   throw cliValidationError(
-    "Usage: lumine admin identity|daily-run|recommendations|post|subjects|subject|featured|comment|chat|news|audit|brief|bot-output|notable ...",
+    "Usage: lumine admin identity|daily-run|recommendations|builds|post|subjects|subject|featured|comment|chat|news|audit|brief|bot-output|notable ...",
   );
 }
 
@@ -947,6 +1047,50 @@ export function parseRecommendationTarget({ target, explicitType = "" }) {
   return { type, id };
 }
 
+export function parseAdminCommentTarget({ target, explicitType = "" }) {
+  const normalized = String(target || "").trim();
+  const prefixed = normalized.match(
+    /^(subject|comment|build|aistory|dailyreflection):(\d+)$/i,
+  );
+  const buildUrl = normalized.match(/\/(?:app|build)\/(\d+)(?:[/?#]|$)/i);
+  const baseTarget = parseRecommendationTarget({
+    target:
+      prefixed?.[1]?.toLowerCase() === "build" || buildUrl
+        ? `subject:${prefixed?.[2] || buildUrl?.[1]}`
+        : normalized,
+    explicitType:
+      String(explicitType || "").toLowerCase() === "build"
+        ? "subject"
+        : explicitType,
+  });
+  const inferredBuild = prefixed?.[1]?.toLowerCase() === "build" || !!buildUrl;
+  const explicitBuild = String(explicitType || "").toLowerCase() === "build";
+  if (explicitType && !explicitBuild && inferredBuild) {
+    throw cliValidationError(
+      "The target and --type identify different content types.",
+    );
+  }
+  if (explicitBuild && !inferredBuild && !/^\d+$/.test(normalized)) {
+    throw cliValidationError(
+      "The target and --type identify different content types.",
+    );
+  }
+  if (inferredBuild || explicitBuild) {
+    return { type: "build", id: baseTarget.id };
+  }
+  return baseTarget;
+}
+
+function parseAdminBuildReviewMethod(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (normalized !== "runtime" && normalized !== "code") {
+    throw cliValidationError("--reviewed-via must be runtime or code.");
+  }
+  return normalized;
+}
+
 function normalizeRecommendationTargetType(value) {
   const normalized = String(value || "")
     .trim()

package/lib/commands.js

@@ -2194,6 +2194,10 @@ export function parseArgs(args) {
     adminEditionId: raw.editionId ? String(raw.editionId) : "",
     adminLeaseToken: raw.leaseToken ? String(raw.leaseToken) : "",
     adminFile: raw.file ? String(raw.file) : "",
+    adminReviewedBuildVersion: raw.reviewedVersion
+      ? String(raw.reviewedVersion)
+      : "",
+    adminBuildReviewMethod: raw.reviewedVia ? String(raw.reviewedVia) : "",
     adminFull: parseBoolean(raw.full, false),
     rewardTwinkles: raw.rewardTwinkles ? String(raw.rewardTwinkles) : "",
     includeComments: parseBoolean(raw.includeComments, false),
@@ -2511,9 +2515,11 @@ export function printHelp() {
   lumine admin identity list|status|use <zero|ciel|auto> [--json]
   lumine admin ai-bucket get --bucket-id <id> [--json]
   lumine admin ai-bucket accounts add --bucket-id <id> --user-ids <id,id,...> [--note <text>] [--json]
+  lumine admin ai-bucket note set --bucket-id <id> --note <text> [--json]
   lumine admin daily-run start [--identity zero|ciel|auto] [--comment-mode off|draft|post] [--run-key <key>] [--json]
   lumine admin daily-run status|complete|fail [--reason <text>] [--json]
   lumine admin recommendations list [--content-types comment,dailyReflection] [--unviewed|--viewed] [--cursor <cursor>] [--json]
+  lumine admin builds candidates [--cursor <cursor>] [--limit <number>] [--json]
   lumine admin subjects candidates [--after <date>] [--effort unassigned] [--unviewed|--viewed] [--cursor <cursor>] [--json]
   lumine admin subject get|reveal <subject-url-or-id> [--json]
   lumine admin subject comments <subject-url-or-id> [--unviewed|--viewed] [--cursor <cursor>] [--json]
@@ -2527,8 +2533,8 @@ export function printHelp() {
   lumine admin post recommend <target> [--type subject|comment|aiStory|dailyReflection] [--anyone-can-reward] [--reward-twinkles 3] [--json]
   lumine admin post skip <target> [--type comment|aiStory|dailyReflection] [--reason <text>] [--json]
   lumine admin post reward <target> [--type subject|comment|aiStory|dailyReflection] --twinkles 3 [--json]
-  lumine admin comment draft <target> [--type subject|comment|aiStory|dailyReflection] [--identity zero|ciel|auto] [--json]
-  lumine admin comment reply comment:<id> [--identity zero|ciel|auto] [--json]
+  lumine admin comment draft <target> [--type subject|comment|build|aiStory|dailyReflection] [--file <comment.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--identity zero|ciel|auto] [--json]
+  lumine admin comment reply comment:<id> [--file <reply.md>] [--reviewed-version <id> --reviewed-via runtime|code] [--identity zero|ciel|auto] [--json]
   lumine admin comment post --draft-id <id> [--json]
   lumine admin comment edit <comment-id> --file <comment.md> [--json]
   lumine admin brief [--days <1..30>] [--json]
@@ -2597,7 +2603,7 @@ Options:
   --description <text>  Build description for new/describe
   --no-description      Skip New description or clear with describe
   --summary <text>      Save summary
-  --note <text>         Branch-suggestion message or notable-user rationale
+  --note <text>         Suggestion, notable-user, or AI-bucket context
   --cursor <id>         Continue an owner suggestion inbox listing
   --after <date>        Admin subjects: inclusive Unix/ISO creation boundary
   --effort unassigned  Admin subjects: show only unassigned effort
@@ -2611,13 +2617,15 @@ Options:
   --subject-ids <ids>   Complete ordered Featured subject IDs
   --bucket-id <id>      Unbanned AI identity bucket for account consolidation
   --user-ids <ids>      Explicit user IDs for an AI bucket batch (up to 500)
-  --type <type>         Admin target: subject, comment, aiStory, or dailyReflection
+  --type <type>         Admin target: subject, comment, build, aiStory, or dailyReflection
   --kind recommend      Admin recommendation queue kind
   --anyone-can-reward   Enable canonical reward eligibility
   --reward-twinkles 3   Pair a recommendation with exactly 3 Twinkles
   --twinkles 3          Give exactly 3 Twinkles through the normal economy
   --draft-id <id>       Canonical delegated comment draft ID
   --file <path>         Editorial JSON or composed comment text file
+  --reviewed-version <id> Published Build artifact version actually reviewed
+  --reviewed-via <method> Build review method: runtime or code
   --reason <text>       Reason when marking an admin run failed
   --force               Overwrite server files even if this workspace is stale or missing filesHash
   --search <text>       Search public open-source Builds

package/package.json

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

package/sdk/LUMINE_ADMIN.md

@@ -59,6 +59,8 @@ lumine admin ai-bucket get --bucket-id 10 --json
 lumine admin ai-bucket accounts add --bucket-id 10 \
   --user-ids 3127,13037,15410,16288 \
   --note "operator-confirmed account family" --json
+lumine admin ai-bucket note set --bucket-id 10 \
+  --note "Quota accounting only; not a moderation flag." --json
 ```
 
 `accounts add` accepts 1-500 unique positive user IDs, preflights the complete
@@ -67,6 +69,10 @@ re-attributes current-day AI usage, and returns the canonical bucket members.
 It is idempotent to retry. The API records the real operator in the private
 Lumine audit log; no public bot identity is involved.
 
+`note set` records up to 255 characters of private operational context on the
+canonical bucket. Use it to distinguish quota bookkeeping from moderation;
+the note itself changes no access, ban, or identity rules.
+
 This surface intentionally accepts only an existing **unbanned** bucket. It
 cannot ban accounts, block signup, add IP/device/risk-key rules, or infer an
 account family. Identification remains a human/LLM evidence judgment and must
@@ -484,6 +490,7 @@ lumine admin subjects candidates --after 2026-08-01T00:00:00Z \
   --cursor '<cursor>' --json
 lumine admin subjects candidates --effort unassigned --json
 lumine admin subjects candidates --unviewed --json
+lumine admin builds candidates --cursor '<cursor>' --limit 50 --json
 ```
 
 Schemas:
@@ -529,6 +536,29 @@ type SubjectCandidates = Success<{
   subjects: Subject[];
   pagination: Pagination & { scannedCount: number };
 }>;
+
+type BuildCandidates = Success<{
+  builds: Array<{
+    id: number;
+    title: string | null;
+    description: string | null;
+    username: string | null;
+    publishedAt: number | null;
+    publishedArtifactVersionId: number | null;
+    collaborationMode: "private" | "open_source";
+    url: string;
+    review: {
+      publishedArtifactVersionId: number | null;
+      codePullAvailable: boolean;
+      requiredBeforeComment: true;
+    };
+  }>;
+  pagination: {
+    nextCursor: string | null;
+    hasMore: boolean;
+    exhausted: boolean;
+  };
+}>;
 ```
 
 Both cursors freeze a primary-key high-water mark and traverse descending IDs,
@@ -538,6 +568,24 @@ filters, so a page — recommendation or subject — can be empty while `hasMore
 remains true; continue until `exhausted`. Subject `--after` is inclusive, and
 the opaque cursor is bound to its original date and effort filters.
 
+`builds candidates` is a management-agent discovery view over the canonical
+public Build browser, ordered by the current published release. It is
+available through the `admin` namespace only while a delegated run is active;
+page until `pagination.exhausted`. Each item includes its canonical app URL,
+published artifact version, and whether its code is pullable. This list does
+not decide that an app deserves a comment. The management agent must open and
+genuinely try the published runtime, or pull and read an open-source project,
+before making that judgment. Direct API/persona automation is never a review
+substitute.
+
+During every management run, scan recent Build candidates back through the
+run's review window alongside Subjects and the recommendation queue. An app
+that is thin, broken, private, unchanged since a prior substantive bot
+comment, or not meaningfully understood may be left alone. A new or materially
+updated app where specific, truthful feedback would help is comment-worthy.
+This is editorial attention, not a quota: do not manufacture a Build comment
+just to prove the queue was visited.
+
 `--content-types` is sent to APIs that support server-side filtering so excluded
 types do not run their eligibility/content queries. The local CLI also filters
 the returned page defensively for deployment compatibility. The server cursor
@@ -1653,7 +1701,7 @@ from memory:
   decisions are yours to make and record with `post skip` or in the run
   report).
 
-**Lumine Build app posts are composed-only, and only after actually looking
+**Lumine Build apps and app posts are composed-only, and only after actually looking
 (Mikey's direction, 2026-08-10).** When a post is about a Build app — the
 author shares their app, announces an update, or asks for feedback on their
 build — never use the server-generated draft path: the API persona cannot
@@ -1671,6 +1719,29 @@ tried it — ask the author about it instead. This is the standing rule for
 every composed comment, applied to apps: never claim an experience the
 session did not actually have.
 
+The same rule covers comments placed **directly on a Build app**. This is
+deliberately management-agent-only: no server-generated draft and no pure API
+persona may author one. After reviewing the project, bind the composed comment
+to the exact published artifact you saw:
+
+```bash
+lumine admin comment draft build:884 --file comment.md \
+  --reviewed-version 4512 --reviewed-via runtime --json
+lumine admin comment post --draft-id 77 --json
+```
+
+Use `--reviewed-via code` only when you actually pulled and read the project;
+`runtime` means you opened and tried the published app. Replies to human
+comments inside a Build use `comment:<id>` plus the same review flags. The API
+rejects missing review evidence, a server-generated Build draft, a mismatched
+published version, a private/noncanonical Build, or any Build/comment-context
+change between draft and publication. A changed version means review the new
+project state and compose again. The flags are an auditable statement of what
+the management agent did, not permission to infer experience from metadata.
+Autonomous mention/reply generation and sponsored AI replies are disabled in
+Build threads. The generic `comment edit` shortcut is also disabled there;
+review the current version and post a version-bound correction reply instead.
+
 **Offer a Lumine prompt when the moment invites it (Mikey's direction,
 2026-08-10).** Zero and Ciel may include one concrete, copy-pasteable Lumine
 prompt in a comment or reply — a genuinely powerful one, tailored to what the
@@ -1710,15 +1781,18 @@ containers, and publication applies to both kinds of draft.
 A draft targets one of:
 
 - `subject:<id>` (or a bare numeric ID) — a top-level comment on the subject;
+- `build:<id>` — a top-level comment on a public canonical Build, composed
+  after reviewing its exact published version;
 - `aiStory:<id>` / `dailyReflection:<id>` — a top-level comment on the
   standalone post;
 - `comment:<id>` — a public reply to that specific comment. `comment reply`
   is the same operation and requires a comment target.
 
 A reply's container resolves canonically from the target comment: its subject,
-or its AI Story / Daily Reflection root. Comments under any other root are
-rejected with `CLI_ADMIN_UNSUPPORTED_REPLY_ROOT`. Replies to Zero/Ciel
-comments and to notification comments are rejected with
+Build, or AI Story / Daily Reflection root. Comments under any other root are
+rejected with `CLI_ADMIN_UNSUPPORTED_REPLY_ROOT`. Build replies require the
+same exact-version review evidence as top-level Build comments. Replies to
+Zero/Ciel comments and to notification comments are rejected with
 `CLI_ADMIN_INVALID_REPLY_TARGET` — the bots never thread with themselves or
 each other, and a human's later reply to a delegated comment still enters the
 existing autonomous comment-assistant pipeline. Published replies carry the
@@ -1730,7 +1804,7 @@ type CommentDraft = Success<{
   draft: {
     id: number;
     runId: number;
-    targetType: "subject" | "comment" | "aiStory" | "dailyReflection";
+    targetType: "subject" | "comment" | "build" | "aiStory" | "dailyReflection";
     targetId: number;
     targetUrl: string;
     subjectId: number | null; // container subject; null for standalone posts
@@ -1761,7 +1835,8 @@ type CommentPost = CommentGet & {
     };
     published: {
       commentId: number;
-      targetType: "subject" | "comment" | "aiStory" | "dailyReflection";
+      targetType:
+        "subject" | "comment" | "build" | "aiStory" | "dailyReflection";
       targetId: number;
       subjectId: number | null;
       subjectUrl: string | null;
@@ -1772,12 +1847,13 @@ type CommentPost = CommentGet & {
 };
 ```
 
-The server loads the canonical container (subject or standalone post) and its
-complete visible comment context, then invokes the existing exact Zero/Ciel
-system prompt through the shared response assembler with a mode-specific
-decision policy (comment vs reply). The raw prompt is never returned or
-audited. The model—not regexes or keyword rules—chooses `draft` or `skip`
-under the run policy.
+For Subjects and standalone posts, the server loads the canonical container
+and its complete visible comment context, then invokes the existing exact
+Zero/Ciel system prompt through the shared response assembler with a
+mode-specific decision policy (comment vs reply). The raw prompt is never
+returned or audited. The model—not regexes or keyword rules—chooses `draft`
+or `skip` under the run policy. Build comments never enter that generated
+path; they require management-agent-composed content and review evidence.
 
 Draft IDs are bound to operator, run, public bot, target, comment mode,
 context revision, persona revision, expiry, and idempotency key. The context