@stage5/lumine 0.2.17 → 0.2.19

package/README.md

@@ -9,8 +9,11 @@ npx @stage5/lumine@latest new "Daily Reflection App"
 npx @stage5/lumine@latest new --title "Daily Reflection App" --description "Private journal with streaks"
 npx @stage5/lumine@latest rename "My New Build Title"
 npx @stage5/lumine@latest rename "New Title" --target 123
+npx @stage5/lumine@latest describe "A welcoming place to build together"
+npx @stage5/lumine@latest describe --no-description --target 123
 npx @stage5/lumine@latest projects
 npx @stage5/lumine@latest branches 884
+npx @stage5/lumine@latest suggestions 884
 npx @stage5/lumine@latest explore --sort forks
 npx @stage5/lumine@latest reference https://www.twin-kle.com/app/123
 npx @stage5/lumine@latest fork https://www.twin-kle.com/app/123
@@ -31,6 +34,12 @@ local workspace, but it does not auto-start a Lumine greeting or prompt run, so
 creating a project from the CLI does not spend AI battery. Add project files
 locally, including `/index.html`, then run `lumine save`.
 
+Use `lumine rename` to change an existing Build title and `lumine describe` to
+change its description through the same canonical metadata route as the
+website. Both commands target the current workspace or selected Build; pass
+`--target <build-url-or-id>` to update another Build you own. Run
+`lumine describe --no-description` to clear a description explicitly.
+
 For team projects, Lumine mirrors the website workspace flow: choosing or
 pulling the owner's main project creates or reuses your contribution branch and
 checks out that branch locally. Saves go to your branch, so the project owner
@@ -40,6 +49,17 @@ Use `lumine branches <build-url-or-id>` to list the contribution branches you
 can review, including each contributor, branch number, status, and URL. Then use
 `lumine diff <branch-url>` to inspect one branch.
 
+Branch contributors can nudge the project owner from their pulled branch with
+`lumine suggest branch [message]` or `lumine suggest thumbnail`. The thumbnail
+command offers the thumbnail currently saved on that branch. Project owners can
+run `lumine suggestions <build-url-or-id>` to see their open suggestion inbox.
+The inbox prints canonical follow-up commands for merging or replacing Main and
+for applying the exact frozen thumbnail shown in a suggestion. The same actions
+are also available directly as `lumine suggestions merge <id>`,
+`lumine suggestions replace-main <id>`, and
+`lumine suggestions adopt-thumbnail <id>`. Large inboxes are cursor-paginated;
+the CLI prints the exact `--cursor` command for the next page.
+
 Use `lumine explore` to list public open-source Build apps that can be used as
 examples or starting points. It supports `--search` and `--sort forks`,
 `--sort popular`, or `--sort recent`. Use `lumine reference <build-url-or-id>`
@@ -133,6 +153,64 @@ claude "Read CLAUDE.md, then make the requested change."
 The login command uses a browser approval code and stores a scoped token and the
 selected project at `~/.twinkle/lumine-cli-auth.json`.
 
+## Privileged website administration
+
+`lumine admin` reuses Mikey's saved CLI login while keeping the visible public
+actor separate. The server reloads Mikey's current authority from the writer,
+resolves Zero/Ciel by immutable IDs, and binds every operation to an expiring,
+purpose-scoped daily run. Flags, usernames, token claims, and local state never
+grant delegation. Delegated work does not create a bot login or presence
+session, but its public content changes use Twinkle's normal real-time socket
+events.
+
+```bash
+lumine admin identity list --json
+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 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
+lumine admin subject comments 123 --cursor '<cursor>' --json
+lumine admin subject reveal 123 --json
+lumine admin subject effort set 123 --level 3 --json
+lumine admin subject creator set-made-by-poster 123 --json
+lumine admin featured list --json
+lumine admin subject feature 123 --json
+lumine admin subject unfeature 123 --json
+lumine admin featured reorder --subject-ids 30,20,10 --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 daily-run complete --json
+```
+
+Numeric recommendation targets default to subjects. Use `comment:<id>`,
+`aiStory:<id>`, `dailyReflection:<id>`, a canonical URL, or the matching
+`--type` for another post kind. Commenting is always `off` for a new run unless
+`--comment-mode draft` or `--comment-mode post` is explicitly supplied. Drafts
+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.
+
+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
+stable `--idempotency-key` when retrying one mutation across processes; the
+server also enforces canonical no-duplicate invariants. Failed mutation JSON
+includes `error.details.retryIdempotencyKey` so a partial attempt can be
+resumed with the exact generated key.
+
+Subject and recommendation-queue listings use opaque, stable snapshot cursors.
+Pass the returned `data.pagination.nextCursor` back through `--cursor` until
+`data.pagination.exhausted` is true. Subject `--after` is inclusive and cursors
+are bound to the original date and effort filters.
+
+The complete run lifecycle, command contracts, nullable fields, Karma approval
+behavior, pagination semantics, secret-subject behavior, presence isolation,
+and retry rules are documented in
+[`sdk/LUMINE_ADMIN.md`](sdk/LUMINE_ADMIN.md).
+
 `lumine login` opens the Twinkle approval page automatically. If you are running
 in SSH, CI, or an agent environment, use:
 

package/bin/lumine.js

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
 import { main } from "../lib/commands.js";
+import { formatAdminJsonError, isAdminJsonInvocation } from "../lib/admin.js";
 
 main().catch((error) => {
-  console.error(`lumine: ${error?.message || error}`);
+  if (isAdminJsonInvocation(process.argv.slice(2))) {
+    console.log(JSON.stringify(formatAdminJsonError(error)));
+  } else {
+    console.error(`lumine: ${error?.message || error}`);
+  }
   process.exitCode = 1;
 });