@genex-ai/cli-demo 0.63.0-dev.152 → 0.64.0-dev.154

package/dist/index.js

@@ -495,7 +495,7 @@ async function authorize(authBaseUrl, options) {
       cleanup();
       resolve(token);
     };
-    const fail2 = (err) => {
+    const fail3 = (err) => {
       if (settled) return;
       settled = true;
       cleanup();
@@ -512,7 +512,7 @@ async function authorize(authBaseUrl, options) {
         }
       });
     });
-    server.on("error", (err) => fail2(err));
+    server.on("error", (err) => fail3(err));
     server.listen(0, "127.0.0.1", () => {
       const { port } = server.address();
       const redirectUri = `http://127.0.0.1:${port}/callback`;
@@ -543,7 +543,7 @@ async function authorize(authBaseUrl, options) {
         );
       }
       timer = setTimeout(() => {
-        fail2(
+        fail3(
           new Error(
             "Timed out waiting for authorization. Re-run the command to try again."
           )
@@ -2585,7 +2585,7 @@ function buildGenOptions(kind, opts) {
   return options;
 }
 async function runGenerate(kind, opts) {
-  const log = createLogger({ quiet: opts.quiet });
+  const log = createLogger({ quiet: opts.quiet || opts.json });
   const prompt = opts.prompt?.trim();
   if (!prompt) {
     log.error(`Missing prompt. Usage: ${c.cyan(`genex ${kind} "<prompt>"`)}`);
@@ -2641,31 +2641,52 @@ async function runGenerate(kind, opts) {
   }
   await recordQueued(id, kind, prompt);
   if (opts.noWait) {
-    log.success(`Queued (${id}).`);
-    log.plain(`  Pick it up any time with: ${c.cyan(`npx genex wait ${id}`)}`);
-    log.dim("  (Re-running the generate command would start \u2014 and bill \u2014 a NEW generation.)");
+    if (opts.json) {
+      writeJson({
+        kind,
+        id,
+        status: "pending",
+        nextCommand: `genex wait ${id} --json`
+      });
+    } else {
+      log.success(`Queued (${id}).`);
+      log.plain(`  Pick it up any time with: ${c.cyan(`npx genex wait ${id}`)}`);
+      log.dim("  (Re-running the generate command would start \u2014 and bill \u2014 a NEW generation.)");
+    }
     return id;
   }
-  await awaitAndReport(apiUrl, token, id, kind, log, opts.open);
+  await awaitAndReport(apiUrl, token, id, kind, log, opts.open, opts.json);
   return id;
 }
-async function awaitAndReport(apiUrl, token, id, kind, log, open = false) {
-  log.step("Generating\u2026 (this can take up to a minute)");
-  const onProgress = (p) => log.dim(`  ${p}%`);
-  const timeoutMs = waitTimeoutFor(kind);
-  const deadline = Date.now() + timeoutMs;
-  const streamed = await waitViaSSE(apiUrl, token, id, onProgress, deadline);
-  const view = streamed === "unsupported" ? await poll(apiUrl, token, id, onProgress, timeoutMs) : streamed;
+async function awaitAndReport(apiUrl, token, id, kind, log, open = false, json = false) {
+  if (!json) log.step("Generating\u2026 (this can take up to a minute)");
+  const view = await waitForTerminalView(
+    apiUrl,
+    token,
+    id,
+    kind,
+    json ? () => {
+    } : (p) => log.dim(`  ${p}%`)
+  );
   if (!view) {
-    log.error("Timed out waiting for the generation.");
+    if (json) writeJson({ kind, id, status: "failed", error: "Timed out waiting for the generation." });
+    else log.error("Timed out waiting for the generation.");
     process.exitCode = 1;
     return;
   }
-  await reportTerminal(kind, view, log, open);
+  await reportTerminal(kind, view, log, open, json);
 }
-async function reportTerminal(kind, view, log, open = false) {
+async function waitForTerminalView(apiUrl, token, id, kind, onProgress = () => {
+}) {
+  const timeoutMs = waitTimeoutFor(kind);
+  const deadline = Date.now() + timeoutMs;
+  const streamed = await waitViaSSE(apiUrl, token, id, onProgress, deadline);
+  return streamed === "unsupported" ? poll(apiUrl, token, id, onProgress, timeoutMs) : streamed;
+}
+async function reportTerminal(kind, view, log, open = false, json = false) {
   if (view.status !== "completed") {
-    log.error(`Generation ${view.status}${view.error ? `: ${view.error}` : ""}.`);
+    if (json) writeJson({ kind, id: view.id, status: view.status, error: view.error ?? null });
+    else log.error(`Generation ${view.status}${view.error ? `: ${view.error}` : ""}.`);
     if (view.status === "failed") {
       await recordTerminal(view.id, "failed");
       if (kind === "video") {
@@ -2678,11 +2699,33 @@ async function reportTerminal(kind, view, log, open = false) {
   }
   const files = view.files ?? [];
   if (files.length === 0) {
-    log.error("Generation completed but produced no files.");
+    if (json) writeJson({ kind, id: view.id, status: "failed", error: "Generation completed but produced no files." });
+    else log.error("Generation completed but produced no files.");
     process.exitCode = 1;
     return;
   }
   await recordTerminal(view.id, "completed", files.map((f) => f.url));
+  if (kind === "character_concept") {
+    reportCharacterConceptTerminal(view, log, { json, open });
+    return;
+  }
+  if (kind === "character_preview") {
+    reportCharacterPreviewTerminal(view, log, { json, open });
+    return;
+  }
+  if (json) {
+    writeJson({
+      kind,
+      id: view.id,
+      status: view.status,
+      files,
+      ...kind === "character" ? {
+        characterId: view.id,
+        nextCommand: `genex controller character --character ${view.id}`
+      } : {}
+    });
+    return;
+  }
   log.plain("");
   log.success("Done \u2014 live on R2 (nothing downloaded or committed):");
   for (const f of files) {
@@ -2712,6 +2755,8 @@ var WAIT_TIMEOUT_MS = 10 * 60 * 1e3;
 var KIND_WAIT_TIMEOUT_MS = {
   video: 15 * 60 * 1e3,
   // 15 min
+  character_concept: 15 * 60 * 1e3,
+  character_preview: 30 * 60 * 1e3,
   character: 30 * 60 * 1e3,
   character_animation: 20 * 60 * 1e3
 };
@@ -2823,17 +2868,179 @@ function printHint(kind, view, files, log) {
     texture: `Load each map with TextureLoader (RepeatWrapping) into a MeshStandardMaterial \u2014 see genex-ai-texture. Use the URLs above by role.`,
     image: `Load with TextureLoader (set colorSpace = SRGBColorSpace) onto any mesh/plane/sprite \u2014 see genex-ai-image. url = "${url}"`,
     video: `Wire an HTMLVideoElement (crossOrigin="anonymous", muted, loop, playsInline) into a THREE.VideoTexture \u2014 see genex-ai-video. url = "${url}"`,
+    character_concept: "Show all three concept candidates to the user and wait for an explicit selection.",
+    character_preview: "Show all four preview views to the user and wait for explicit approval before finalizing.",
     character: `Install the controller and current manifest with genex controller character --character ${view.id}.`,
     character_animation: "The action is now part of the character's current manifest; refresh the local controller manifest before testing."
   };
   log.dim(`  ${hint[kind]}`);
   log.dim("  Reference the URL directly in your code \u2014 don't download it into the repo.");
 }
+var CONCEPT_STOP = "STOP \u2014 show all three concept images to the user and wait for an explicit selection. Do not create the 3D preview until they choose candidate 1, 2, or 3.";
+function metadataOf(view) {
+  return view.metadata && typeof view.metadata === "object" ? view.metadata : {};
+}
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function conceptCandidates(view) {
+  const candidates = [];
+  for (const file of view.files ?? []) {
+    const match = /^(?:concept-candidate|character-concept)-([123])(?:\.[a-z0-9]+)?$/i.exec(file.role);
+    if (!match) continue;
+    candidates.push({ candidate: Number(match[1]), role: file.role, url: file.url });
+  }
+  return candidates.sort((a, b) => a.candidate - b.candidate);
+}
+function conceptContactSheet(view) {
+  return (view.files ?? []).find(
+    (file) => /^(?:concept-gallery|character-concepts-contact-sheet)(?:\.[a-z0-9]+)?$/i.test(file.role)
+  );
+}
+function requestedBuildOf(view) {
+  const metadata = metadataOf(view);
+  const raw = metadata.requestedBuild && typeof metadata.requestedBuild === "object" ? metadata.requestedBuild : {};
+  const actionIds = Array.isArray(raw.actionIds) ? raw.actionIds.filter((id) => typeof id === "number" && Number.isInteger(id)) : [];
+  return {
+    actionIds,
+    controllerPack: raw.controllerPack !== false,
+    ...finiteNumber(raw.heightMeters) === void 0 ? {} : { heightMeters: finiteNumber(raw.heightMeters) }
+  };
+}
+function characterFinalizeCommand(previewId, intent) {
+  const args = [
+    "genex",
+    "character",
+    "finalize",
+    previewId,
+    "--user-approved",
+    "--approve-remesh",
+    "10000"
+  ];
+  if (intent.heightMeters !== void 0) args.push("--height", String(intent.heightMeters));
+  for (const actionId of intent.actionIds) args.push("--animation", String(actionId));
+  return args.join(" ");
+}
+function reportCharacterConceptTerminal(view, log, opts = {}) {
+  const candidates = conceptCandidates(view);
+  if (candidates.length !== 3 || candidates.some((entry, index) => entry.candidate !== index + 1)) {
+    const error = "Character concept generation completed without exactly candidates 1, 2, and 3.";
+    if (opts.json) writeJson({ kind: "character_concept", id: view.id, status: "failed", error });
+    else log.error(error);
+    process.exitCode = 1;
+    return;
+  }
+  const metadata = metadataOf(view);
+  const contactSheet = conceptContactSheet(view);
+  const nextCommand = `genex character preview ${view.id} --candidate <n> --user-approved`;
+  if (opts.open) openUrl(contactSheet?.url ?? candidates[0].url);
+  if (opts.json) {
+    writeJson({
+      kind: "character_concept",
+      stage: "concept",
+      id: view.id,
+      status: view.status,
+      provider: stringValue(metadata.provider),
+      model: stringValue(metadata.aiModel) ?? stringValue(metadata.providerModel),
+      candidates,
+      ...contactSheet ? { contactSheetUrl: contactSheet.url } : {},
+      ...opts.quote ? { quote: opts.quote } : {},
+      requiresUserApproval: true,
+      nextCommand
+    });
+    return;
+  }
+  log.success("Three character concept candidates are ready:");
+  for (const candidate of candidates) log.plain(`  ${candidate.candidate}. ${candidate.url}`);
+  if (contactSheet) log.plain(`  Contact sheet: ${contactSheet.url}`);
+  log.plain("");
+  log.plain(`  ${c.bold("\u{1F441}  Show these to the user")} \u2014 include all three numbered links, not only your favorite.`);
+  log.plain(`  ${c.bold(CONCEPT_STOP)}`);
+  log.plain(`  After approval: ${c.cyan(nextCommand)}`);
+  log.plain("");
+}
+var PREVIEW_DIRECTIONS = ["front", "back", "left", "right"];
+function previewViews(view) {
+  const metadata = metadataOf(view);
+  const rawViews = metadata.views && typeof metadata.views === "object" ? metadata.views : {};
+  const result = {};
+  for (const direction of PREVIEW_DIRECTIONS) {
+    const fromMetadata = stringValue(rawViews[direction]);
+    const fromFile = (view.files ?? []).find((file) => {
+      const role = file.role.toLowerCase();
+      return file.contentType.startsWith("image/") && role.includes(direction);
+    })?.url;
+    result[direction] = fromMetadata ?? fromFile;
+  }
+  return result;
+}
+function previewSource(view) {
+  return (view.files ?? []).find(
+    (file) => file.contentType === "model/gltf-binary" || /(?:source-highpoly|character-preview)(?:\.glb)?$/i.test(file.role)
+  )?.url;
+}
+function reportCharacterPreviewTerminal(view, log, opts = {}) {
+  const metadata = metadataOf(view);
+  const views = previewViews(view);
+  const sourceFaceCount = finiteNumber(metadata.sourceFaceCount);
+  const missingViews = PREVIEW_DIRECTIONS.filter((direction) => !views[direction]);
+  if (sourceFaceCount === void 0 || missingViews.length > 0) {
+    const detail = [
+      sourceFaceCount === void 0 ? "source face count" : "",
+      missingViews.length > 0 ? `${missingViews.join(", ")} view${missingViews.length === 1 ? "" : "s"}` : ""
+    ].filter(Boolean).join(" and ");
+    const error = `Character preview completed without ${detail}.`;
+    if (opts.json) writeJson({ kind: "character_preview", id: view.id, status: "failed", error });
+    else log.error(error);
+    process.exitCode = 1;
+    return;
+  }
+  const intent = requestedBuildOf(view);
+  const nextCommand = characterFinalizeCommand(view.id, intent);
+  const sourceUrl = previewSource(view);
+  const stop = `STOP \u2014 show the front, back, left, and right views to the user. The high-detail source has ${sourceFaceCount} faces and remains preserved in R2. Ask them to approve a separate 10,000-face triangle rigging copy.`;
+  if (opts.open) openUrl(views.front);
+  if (opts.json) {
+    writeJson({
+      kind: "character_preview",
+      stage: "preview",
+      id: view.id,
+      status: view.status,
+      provider: stringValue(metadata.provider),
+      model: stringValue(metadata.aiModel) ?? stringValue(metadata.providerModel),
+      poseMode: stringValue(metadata.poseMode),
+      shouldRemesh: metadata.shouldRemesh === true,
+      sourceFaceCount,
+      views,
+      ...sourceUrl ? { sourceUrl } : {},
+      requestedBuild: intent,
+      ...opts.quote ? { quote: opts.quote } : {},
+      requiresUserApproval: true,
+      nextCommand
+    });
+    return;
+  }
+  log.success("The high-detail Meshy character preview is ready:");
+  for (const direction of PREVIEW_DIRECTIONS) log.plain(`  ${direction}: ${views[direction]}`);
+  if (sourceUrl) log.plain(`  High-detail source: ${sourceUrl}`);
+  log.plain("");
+  log.plain(`  ${c.bold("\u{1F441}  Show these to the user")} \u2014 include all four views.`);
+  log.plain(`  ${c.bold(stop)}`);
+  log.plain(`  After approval: ${c.cyan(nextCommand)}`);
+  log.plain("");
+}
+function writeJson(value) {
+  process.stdout.write(`${JSON.stringify(value)}
+`);
+}
 
 // src/commands/wait.ts
 var TERMINAL2 = /* @__PURE__ */ new Set(["completed", "failed"]);
 async function runWait(opts) {
-  const log = createLogger({ quiet: opts.quiet });
+  const log = createLogger({ quiet: opts.quiet || opts.json });
   const id = opts.id?.trim();
   if (!id) {
     log.error(
@@ -2881,10 +3088,10 @@ async function runWait(opts) {
   log.dim(`  ${kind} ${id}`);
   log.plain("");
   if (TERMINAL2.has(view.status)) {
-    await reportTerminal(kind, view, log, opts.open);
+    await reportTerminal(kind, view, log, opts.open, opts.json);
     return;
   }
-  await awaitAndReport(apiUrl, token, id, kind, log, opts.open);
+  await awaitAndReport(apiUrl, token, id, kind, log, opts.open, opts.json);
 }
 
 // src/commands/controller.ts
@@ -12583,13 +12790,29 @@ async function installMeshyCharacterManifest(args) {
   }
   const provenance = manifest.provenance;
   if (provenance?.provider === "meshy" && typeof provenance.aiModel === "string") {
-    const apiVersion = typeof provenance.apiVersion === "string" && provenance.apiVersion.length > 0 ? `; API ${provenance.apiVersion}` : "";
+    const recordedApiVersion = typeof provenance.meshyApiVersion === "string" && provenance.meshyApiVersion.length > 0 ? provenance.meshyApiVersion : typeof provenance.apiVersion === "string" && provenance.apiVersion.length > 0 ? provenance.apiVersion : void 0;
+    const apiVersion = recordedApiVersion ? `; API ${recordedApiVersion}` : "";
     args.log.success(`Meshy model: ${provenance.aiModel}${apiVersion}`);
     if ((provenance.poseMode === "a-pose" || provenance.poseMode === "t-pose") && typeof provenance.shouldRemesh === "boolean" && typeof provenance.targetPolycount === "number") {
       args.log.dim(
         `  generation: ${provenance.poseMode}, remesh ${provenance.shouldRemesh ? "on" : "off"}, target ${provenance.targetPolycount} polygons`
       );
     }
+    if (typeof provenance.conceptModel === "string" && provenance.conceptModel.length > 0 && typeof provenance.conceptCandidate === "number" && Number.isInteger(provenance.conceptCandidate)) {
+      args.log.success(`Guided source: ${provenance.conceptModel} candidate ${provenance.conceptCandidate}`);
+      const lineage = [
+        typeof provenance.conceptGenerationId === "string" && provenance.conceptGenerationId.length > 0 ? `concept ${provenance.conceptGenerationId}` : void 0,
+        typeof provenance.previewGenerationId === "string" && provenance.previewGenerationId.length > 0 ? `preview ${provenance.previewGenerationId}` : void 0
+      ].filter((value) => value !== void 0);
+      if (lineage.length > 0) args.log.dim(`  lineage: ${lineage.join("; ")}`);
+    }
+    if (typeof provenance.sourceFaceCount === "number" && Number.isFinite(provenance.sourceFaceCount) && typeof provenance.remeshTargetFaceCount === "number" && Number.isFinite(provenance.remeshTargetFaceCount)) {
+      const actual = typeof provenance.remeshActualFaceCount === "number" && Number.isFinite(provenance.remeshActualFaceCount) ? `, actual ${provenance.remeshActualFaceCount}` : "";
+      const topology = provenance.remeshTopology === "triangle" ? " triangle" : "";
+      args.log.dim(
+        `  geometry: ${provenance.sourceFaceCount} source faces -> target ${provenance.remeshTargetFaceCount}${topology} faces${actual}`
+      );
+    }
   } else {
     args.log.warn("Meshy model/version metadata is unavailable in this legacy manifest.");
   }
@@ -12772,32 +12995,181 @@ async function quote(url, token, body) {
   }
   return (await response.json()).quote;
 }
-function showAmbiguity(selector, candidates, log) {
-  log.error(`\u201C${selector}\u201D is ambiguous. Choose an action id:`);
-  for (const candidate of candidates) {
-    log.plain(`  ${c.cyan(String(candidate.actionId))}  ${candidate.name}  ${c.dim(candidate.key)}`);
+function showAmbiguity(selector, candidates, log, json = false) {
+  if (json) {
+    writeJson({
+      kind: "character",
+      status: "selection_required",
+      selector,
+      candidates: candidates.map((candidate) => ({
+        actionId: candidate.actionId,
+        key: candidate.key,
+        name: candidate.name
+      }))
+    });
+  } else {
+    log.error(`\u201C${selector}\u201D is ambiguous. Choose an action id:`);
+    for (const candidate of candidates) {
+      log.plain(`  ${c.cyan(String(candidate.actionId))}  ${candidate.name}  ${c.dim(candidate.key)}`);
+    }
   }
   process.exitCode = 1;
 }
 async function runCharacter(opts) {
-  const log = createLogger({ quiet: opts.quiet });
+  if (opts.directText) {
+    await runDirectTextCharacter(opts);
+    return;
+  }
+  await runCharacterConcept(opts);
+}
+function fail(opts, message, kind = "character") {
+  if (opts.json) writeJson({ kind, status: "failed", error: message });
+  else createLogger({ quiet: opts.quiet }).error(message);
+  process.exitCode = 1;
+}
+function requestedBuild(opts, actionIds) {
+  return {
+    actionIds,
+    controllerPack: opts.controllerPack !== false,
+    ...opts.height === void 0 ? {} : { heightMeters: opts.height }
+  };
+}
+async function postWorkflow(url, token, body) {
+  const response = await apiFetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    body: JSON.stringify(body)
+  });
+  if (printedStructuredError(response)) return null;
+  if (!response.ok) {
+    const data2 = await response.json().catch(() => ({}));
+    throw new Error(data2.message ?? data2.error ?? `Character workflow request failed (HTTP ${response.status}).`);
+  }
+  const data = await response.json();
+  if (typeof data.id !== "string" || data.id.length === 0) {
+    throw new Error("Character workflow request returned no generation id.");
+  }
+  return { id: data.id, kind: data.kind, status: data.status, creditsQuoted: data.creditsQuoted };
+}
+async function runWorkflow(args) {
+  const log = createLogger({ quiet: args.opts.quiet || args.opts.json });
+  const created = await postWorkflow(`${args.ctx.apiUrl}${args.createPath}`, args.ctx.token, args.body);
+  if (!created) {
+    process.exitCode = 1;
+    return;
+  }
+  await recordQueued(created.id, args.kind, args.prompt);
+  if (args.opts.noWait) {
+    const nextCommand = `genex wait ${created.id}${args.opts.json ? " --json" : ""}`;
+    if (args.opts.json) {
+      writeJson({
+        kind: args.kind,
+        id: created.id,
+        status: created.status ?? "pending",
+        quote: args.quote,
+        requiresUserApproval: args.kind !== "character",
+        nextCommand
+      });
+    } else {
+      log.success(`Queued (${created.id}).`);
+      log.plain(`  Next: ${c.cyan(nextCommand)}`);
+      log.dim("  Wait on this id to resume. Repeating the same approval reuses its existing job.");
+    }
+    return;
+  }
+  if (!args.opts.json) log.step("Generating\u2026");
+  const view = await waitForTerminalView(
+    args.ctx.apiUrl,
+    args.ctx.token,
+    created.id,
+    args.kind,
+    args.opts.json ? () => {
+    } : (progress) => log.dim(`  ${progress}%`)
+  );
+  if (!view) {
+    fail(args.opts, "Timed out waiting for the character workflow.", args.kind);
+    return;
+  }
+  if (view.status !== "completed") {
+    await reportTerminal(args.kind, view, log, false, args.opts.json);
+    return;
+  }
+  await recordTerminal(view.id, "completed", (view.files ?? []).map((file) => file.url));
+  await args.completed(view);
+}
+async function runCharacterConcept(opts) {
+  const log = createLogger({ quiet: opts.quiet || opts.json });
   const prompt = opts.prompt?.trim();
   if (!prompt) {
-    log.error(`Missing prompt. Usage: ${c.cyan('genex character "<prompt>"')}`);
-    process.exitCode = 1;
+    fail(opts, 'Missing brief. Usage: genex character "<brief>".', "character_concept");
+    return;
+  }
+  if (opts.polycount !== void 0) {
+    fail(opts, "--polycount is only available with --direct-text. The approval flow remeshes only after finalize approval.", "character_concept");
+    return;
+  }
+  if (opts.controllerPack === false) {
+    fail(opts, "--no-controller-pack is only available with --direct-text. The guided Meshy parity flow always installs neutral-v3.", "character_concept");
     return;
   }
   const resolved = resolveActionSelectors(opts.actions ?? []);
   if (!resolved.ok) {
-    showAmbiguity(resolved.selector, resolved.candidates, log);
+    showAmbiguity(resolved.selector, resolved.candidates, log, opts.json);
     return;
   }
   const ctx = await context(opts);
   if (!ctx) {
-    log.error("Not authorized. Run `genex init` first to sign in.");
+    fail(opts, "Not authorized. Run `genex init` first to sign in.", "character_concept");
+    return;
+  }
+  const build = requestedBuild(opts, resolved.actionIds);
+  const request = { prompt, candidates: 3, requestedBuild: build };
+  const price = await quote(`${ctx.apiUrl}/api/characters/concepts/quote`, ctx.token, request);
+  if (!price) {
     process.exitCode = 1;
     return;
   }
+  if (price.candidateCount !== 3) {
+    fail(opts, `The concept quote returned ${price.candidateCount} candidates; this workflow requires exactly 3.`, "character_concept");
+    return;
+  }
+  if (!opts.json) {
+    log.plain(c.bold("Character concept quote"));
+    log.plain(`  ${price.credits} Genex credits \xB7 ${price.candidateCount} candidates \xB7 ${price.providerModel}`);
+    log.plain("");
+  }
+  await runWorkflow({
+    opts,
+    ctx,
+    kind: "character_concept",
+    prompt,
+    createPath: "/api/characters/concepts",
+    body: request,
+    quote: price,
+    completed: (view) => reportCharacterConceptTerminal(view, log, {
+      json: opts.json,
+      open: opts.open,
+      quote: price
+    })
+  });
+}
+async function runDirectTextCharacter(opts) {
+  const log = createLogger({ quiet: opts.quiet || opts.json });
+  const prompt = opts.prompt?.trim();
+  if (!prompt) {
+    fail(opts, 'Missing prompt. Usage: genex character "<prompt>" --direct-text.');
+    return;
+  }
+  const resolved = resolveActionSelectors(opts.actions ?? []);
+  if (!resolved.ok) {
+    showAmbiguity(resolved.selector, resolved.candidates, log, opts.json);
+    return;
+  }
+  const ctx = await context(opts);
+  if (!ctx) {
+    fail(opts, "Not authorized. Run `genex init` first to sign in.");
+    return;
+  }
   const controllerPack = opts.controllerPack !== false;
   const price = await quote(`${ctx.apiUrl}/api/characters/quote`, ctx.token, {
     actionIds: resolved.actionIds,
@@ -12807,17 +13179,19 @@ async function runCharacter(opts) {
     process.exitCode = 1;
     return;
   }
-  log.plain(c.bold("Character quote"));
-  log.plain(`  ${price.credits} Genex credits = base ${price.baseCredits} + actions ${price.animationCredits}`);
-  if (price.controllerPackKey) {
-    const version = price.controllerPackVersion === void 0 ? "" : ` v${price.controllerPackVersion}`;
-    const fingerprint = price.controllerPackFingerprint ? ` \xB7 fingerprint ${price.controllerPackFingerprint}` : "";
-    log.plain(
-      `  controller pack ${c.cyan(`${price.controllerPackKey}${version}`)}${fingerprint} \xB7 provider actions ${(price.controllerActionIds ?? []).join(", ")}`
-    );
+  if (!opts.json) {
+    log.plain(c.bold("Direct-text character quote"));
+    log.plain(`  ${price.credits} Genex credits = base ${price.baseCredits} + actions ${price.animationCredits}`);
+    if (price.controllerPackKey) {
+      const version = price.controllerPackVersion === void 0 ? "" : ` v${price.controllerPackVersion}`;
+      const fingerprint = price.controllerPackFingerprint ? ` \xB7 fingerprint ${price.controllerPackFingerprint}` : "";
+      log.plain(
+        `  controller pack ${c.cyan(`${price.controllerPackKey}${version}`)}${fingerprint} \xB7 provider actions ${(price.controllerActionIds ?? []).join(", ")}`
+      );
+    }
+    log.dim(`  ${price.actionsGenerated} Meshy animation task${price.actionsGenerated === 1 ? "" : "s"} in this request.`);
+    log.plain("");
   }
-  log.dim(`  ${price.actionsGenerated} Meshy animation task${price.actionsGenerated === 1 ? "" : "s"} in this request.`);
-  log.plain("");
   await runGenerate("character", {
     ...opts,
     prompt,
@@ -12827,12 +13201,135 @@ async function runCharacter(opts) {
       actionIds: resolved.actionIds,
       controllerPack,
       ...opts.height === void 0 ? {} : { heightMeters: opts.height },
-      ...opts.polycount === void 0 ? {} : { targetPolycount: opts.polycount }
+      targetPolycount: opts.polycount ?? 1e4
+    }
+  });
+}
+async function runCharacterPreview(opts) {
+  const log = createLogger({ quiet: opts.quiet || opts.json });
+  const conceptId = opts.conceptId?.trim();
+  if (!conceptId) {
+    fail(opts, "Missing concept id. Usage: genex character preview <concept-id> --candidate <1|2|3> --user-approved.", "character_preview");
+    return;
+  }
+  if (!Number.isInteger(opts.candidate) || ![1, 2, 3].includes(opts.candidate)) {
+    fail(opts, "--candidate must be exactly 1, 2, or 3.", "character_preview");
+    return;
+  }
+  if (opts.userApproved !== true) {
+    fail(opts, "STOP: preview creation requires the user's explicit selection. Re-run with --user-approved only after they choose this candidate.", "character_preview");
+    return;
+  }
+  const ctx = await context(opts);
+  if (!ctx) {
+    fail(opts, "Not authorized. Run `genex init` first to sign in.", "character_preview");
+    return;
+  }
+  const body = { candidateIndex: opts.candidate, userApproved: true };
+  const basePath = `/api/characters/concepts/${encodeURIComponent(conceptId)}/previews`;
+  const price = await quote(`${ctx.apiUrl}${basePath}/quote`, ctx.token, body);
+  if (!price) {
+    process.exitCode = 1;
+    return;
+  }
+  if (!opts.json) {
+    log.plain(c.bold("Character 3D preview quote"));
+    log.plain(`  ${price.credits} Genex credits \xB7 candidate ${price.candidateIndex} \xB7 ${price.providerModel} \xB7 no remesh`);
+    log.plain("");
+  }
+  await runWorkflow({
+    opts,
+    ctx,
+    kind: "character_preview",
+    prompt: `Preview candidate ${opts.candidate} from concept ${conceptId}`,
+    createPath: basePath,
+    body,
+    quote: price,
+    completed: (view) => reportCharacterPreviewTerminal(view, log, {
+      json: opts.json,
+      open: opts.open,
+      quote: price
+    })
+  });
+}
+async function runCharacterFinalize(opts) {
+  const log = createLogger({ quiet: opts.quiet || opts.json });
+  const previewId = opts.previewId?.trim();
+  if (!previewId) {
+    fail(opts, "Missing preview id. Usage: genex character finalize <preview-id> --user-approved --approve-remesh 10000.");
+    return;
+  }
+  if (opts.userApproved !== true) {
+    fail(opts, "STOP: finalization requires explicit user approval of all four preview views. Re-run with --user-approved only after approval.");
+    return;
+  }
+  if (opts.approveRemesh !== 1e4) {
+    fail(opts, "--approve-remesh must be exactly 10000. No other rigging-copy target is accepted.");
+    return;
+  }
+  if (opts.polycount !== void 0) {
+    fail(opts, "Do not combine --polycount with finalize; --approve-remesh 10000 is the only accepted rigging-copy target.");
+    return;
+  }
+  if (opts.controllerPack === false) {
+    fail(opts, "--no-controller-pack is only available with --direct-text. Guided finalization requires neutral-v3.");
+    return;
+  }
+  const resolved = resolveActionSelectors(opts.actions ?? []);
+  if (!resolved.ok) {
+    showAmbiguity(resolved.selector, resolved.candidates, log, opts.json);
+    return;
+  }
+  const ctx = await context(opts);
+  if (!ctx) {
+    fail(opts, "Not authorized. Run `genex init` first to sign in.");
+    return;
+  }
+  const body = {
+    ...requestedBuild(opts, resolved.actionIds),
+    userApproved: true,
+    approvedRemeshTarget: 1e4
+  };
+  const basePath = `/api/characters/previews/${encodeURIComponent(previewId)}/finalize`;
+  const price = await quote(`${ctx.apiUrl}${basePath}/quote`, ctx.token, body);
+  if (!price) {
+    process.exitCode = 1;
+    return;
+  }
+  if (!opts.json) {
+    log.plain(c.bold("Character finalize quote"));
+    log.plain(`  ${price.credits} Genex credits = base ${price.baseCredits} + actions ${price.animationCredits}`);
+    log.plain("  Approved rigging copy: 10,000 faces; the high-detail source remains preserved in R2.");
+    log.plain("");
+  }
+  await runWorkflow({
+    opts,
+    ctx,
+    kind: "character",
+    prompt: `Finalize approved character preview ${previewId}`,
+    createPath: basePath,
+    body,
+    quote: price,
+    completed: async (view) => {
+      if (opts.json) {
+        writeJson({
+          kind: "character",
+          stage: "finalize",
+          id: view.id,
+          characterId: view.id,
+          status: view.status,
+          files: view.files ?? [],
+          quote: price,
+          nextCommand: `genex controller character --character ${view.id}`
+        });
+        return;
+      }
+      await reportTerminal("character", view, log);
     }
   });
 }
 async function runCharacterAnimate(opts) {
-  const log = createLogger({ quiet: opts.quiet });
+  const log = createLogger({ quiet: opts.quiet || opts.json });
   const characterId = opts.characterId?.trim();
   if (!characterId) {
     log.error("Missing character id.");
@@ -12841,7 +13338,7 @@ async function runCharacterAnimate(opts) {
   }
   const resolved = resolveActionSelectors(opts.actions ?? []);
   if (!resolved.ok) {
-    showAmbiguity(resolved.selector, resolved.candidates, log);
+    showAmbiguity(resolved.selector, resolved.candidates, log, opts.json);
     return;
   }
   if (resolved.actionIds.length === 0) {
@@ -12865,14 +13362,26 @@ async function runCharacterAnimate(opts) {
     return;
   }
   if (price.actionsGenerated === 0) {
-    log.success(`All ${price.alreadyInstalled ?? resolved.actionIds.length} requested actions are already installed; no credits charged.`);
+    if (opts.json) {
+      writeJson({
+        kind: "character_animation",
+        status: "completed",
+        characterId,
+        alreadyInstalled: price.alreadyInstalled ?? resolved.actionIds.length,
+        credits: 0
+      });
+    } else {
+      log.success(`All ${price.alreadyInstalled ?? resolved.actionIds.length} requested actions are already installed; no credits charged.`);
+    }
     return;
   }
-  log.plain(c.bold("Animation quote"));
-  log.plain(
-    `  ${price.credits} Genex credits = actions ${price.animationCredits}${price.rerigCredits > 0 ? ` + re-rig ${price.rerigCredits}` : ""}`
-  );
-  log.plain("");
+  if (!opts.json) {
+    log.plain(c.bold("Animation quote"));
+    log.plain(
+      `  ${price.credits} Genex credits = actions ${price.animationCredits}${price.rerigCredits > 0 ? ` + re-rig ${price.rerigCredits}` : ""}`
+    );
+    log.plain("");
+  }
   await runGenerate("character_animation", {
     ...opts,
     prompt: `Attach Meshy actions ${resolved.actionIds.join(", ")} to character ${characterId}`,
@@ -13215,18 +13724,18 @@ async function runUi(opts) {
     process.exitCode = 1;
   }
 }
-function fail(message, details) {
+function fail2(message, details) {
   throw new Error(details === void 0 ? message : `${message} ${JSON.stringify(details)}`);
 }
 function requireOpt(value, flag, sub) {
-  if (!value?.trim()) fail(`Missing ${flag}. Run \`genex ui ${sub}\` \u2014 see \`genex --help\`.`);
+  if (!value?.trim()) fail2(`Missing ${flag}. Run \`genex ui ${sub}\` \u2014 see \`genex --help\`.`);
   return value.trim();
 }
 async function uiExtract(opts, log) {
   const input = requireOpt(opts.input, "--in", "extract");
   const outDir = requireOpt(opts.outDir, "--out-dir", "extract");
   const names = (opts.names ?? "").split(",").map((s) => s.trim()).filter(Boolean);
-  if (names.length === 0) fail("Missing --names (comma-separated element names, reading order).");
+  if (names.length === 0) fail2("Missing --names (comma-separated element names, reading order).");
   const minPixels = opts.minPixels ?? 2e3;
   const padding = opts.padding ?? 8;
   const chroma = opts.chroma ?? 240;
@@ -13452,26 +13961,26 @@ async function uiExtract(opts, log) {
 function parseBox(raw, label) {
   const parts = raw.split(",").map((part) => Number.parseInt(part.trim(), 10));
   if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
-    fail(`Invalid ${label} box \u2014 expected x,y,w,h.`, { raw });
+    fail2(`Invalid ${label} box \u2014 expected x,y,w,h.`, { raw });
   }
   const [x, y, w, h] = parts;
-  if (w <= 0 || h <= 0) fail(`Invalid ${label} box dimensions.`, { raw });
+  if (w <= 0 || h <= 0) fail2(`Invalid ${label} box dimensions.`, { raw });
   return { x, y, w, h };
 }
 function parsePairs(raw) {
   return raw.split(";").map((part) => part.trim()).filter(Boolean).map((part) => {
     const pieces = part.split(":");
     if (pieces.length !== 3 && pieces.length !== 4) {
-      fail(
+      fail2(
         "Invalid pair \u2014 expected name:cleanX,cleanY,w,h:annX,annY,w,h[:expectedComponents].",
         { pair: part }
       );
     }
     const [name, cleanRaw, annotatedRaw, expectedRaw] = pieces;
-    if (!/^[a-z0-9][a-z0-9-]*$/i.test(name)) fail("Invalid pair name.", { name });
+    if (!/^[a-z0-9][a-z0-9-]*$/i.test(name)) fail2("Invalid pair name.", { name });
     const expectedComponents = expectedRaw === void 0 ? null : Number.parseInt(expectedRaw, 10);
     if (expectedRaw !== void 0 && (!Number.isFinite(expectedComponents) || expectedComponents < 1)) {
-      fail("Invalid expected component count.", { name, expectedRaw });
+      fail2("Invalid expected component count.", { name, expectedRaw });
     }
     return {
       name,
@@ -13483,7 +13992,7 @@ function parsePairs(raw) {
 }
 function assertInside(box, image, label) {
   if (box.x < 0 || box.y < 0 || box.x + box.w > image.width || box.y + box.h > image.height) {
-    fail(`${label} crop is outside the source image.`, {
+    fail2(`${label} crop is outside the source image.`, {
       box,
       image: { w: image.width, h: image.height }
     });
@@ -13510,7 +14019,7 @@ function assertNotFlush(png, label, maxFrac) {
   const edges = edgeOpaqueFraction(png);
   const flush2 = Object.entries(edges).filter(([, frac]) => frac > maxFrac);
   if (flush2.length > 0) {
-    fail(
+    fail2(
       `${label}: crop box is slicing the element \u2014 opaque content is flush against the image edge. Widen the crop box (or pass --edge-flush-max 1 for a deliberate full-bleed asset).`,
       {
         flushEdges: flush2.map(([edge, frac]) => ({ edge, opaqueFraction: Number(frac.toFixed(3)) })),
@@ -13660,7 +14169,7 @@ async function uiMasks(opts, log) {
   const results = [];
   for (const pair of pairs) {
     if (pair.cleanBox.w !== pair.annotatedBox.w || pair.cleanBox.h !== pair.annotatedBox.h) {
-      fail("Clean and annotated crop boxes must have identical dimensions.", pair);
+      fail2("Clean and annotated crop boxes must have identical dimensions.", pair);
     }
     assertInside(pair.cleanBox, image, `${pair.name} clean`);
     assertInside(pair.annotatedBox, image, `${pair.name} annotated`);
@@ -13671,7 +14180,7 @@ async function uiMasks(opts, log) {
     const annotatedBBox = subjectBBox(annotated);
     const registrationDelta = bboxDelta(cleanBBox, annotatedBBox);
     if (registrationDelta > registrationTolerance) {
-      fail("Annotated copy registration differs too much from the clean asset.", {
+      fail2("Annotated copy registration differs too much from the clean asset.", {
         name: pair.name,
         registrationDelta: Number(registrationDelta.toFixed(4)),
         registrationTolerance,
@@ -13681,7 +14190,7 @@ async function uiMasks(opts, log) {
     }
     const converted = convertGreenMask(annotated);
     if (converted.coverage < minCoverage || converted.coverage > maxCoverage) {
-      fail("Green mask coverage outside the accepted range.", {
+      fail2("Green mask coverage outside the accepted range.", {
         name: pair.name,
         coverage: converted.coverage,
         minCoverage,
@@ -13690,7 +14199,7 @@ async function uiMasks(opts, log) {
     }
     const components = greenComponents(converted.png, minComponentPixels);
     if (pair.expectedComponents && components.length !== pair.expectedComponents) {
-      fail("Green mask component count mismatch.", {
+      fail2("Green mask component count mismatch.", {
         name: pair.name,
         expectedComponents: pair.expectedComponents,
         actualComponents: components.length
@@ -13806,7 +14315,7 @@ async function uiTextColor(opts, log) {
   const minFrac = opts.minFrac ?? 4e-3;
   const image = await loadPng(input);
   if (box.x < 0 || box.y < 0 || box.x + box.w > image.width || box.y + box.h > image.height) {
-    fail("Box is outside the source image.", { box, image: { w: image.width, h: image.height } });
+    fail2("Box is outside the source image.", { box, image: { w: image.width, h: image.height } });
   }
   const region = cropPng(image, box);
   if (opts.cropPath) await writePng(opts.cropPath, region);
@@ -13879,11 +14388,11 @@ async function uiTrim(opts, log) {
   const input = requireOpt(opts.input, "--in", "trim");
   const outPath = opts.out ?? input;
   if (/^https?:\/\//i.test(outPath)) {
-    fail("--in is a URL \u2014 pass --out <png> to say where the trimmed copy goes.");
+    fail2("--in is a URL \u2014 pass --out <png> to say where the trimmed copy goes.");
   }
   const png = await loadPng(input);
   const bbox = alphaBBoxPx(png);
-  if (!bbox) fail("Image is fully transparent \u2014 nothing to trim.", { input });
+  if (!bbox) fail2("Image is fully transparent \u2014 nothing to trim.", { input });
   const cropBox = {
     x: bbox.minX,
     y: bbox.minY,
@@ -13916,7 +14425,7 @@ async function uiSeams(opts, log) {
   const tol = opts.seamTolerance ?? DEFAULT_SEAM_TOLERANCE;
   const png = await loadPng(input);
   if (png.width < 4 || png.height < 4) {
-    fail("Image is too small to test for tiling.", { width: png.width, height: png.height });
+    fail2("Image is too small to test for tiling.", { width: png.width, height: png.height });
   }
   const r = measureSeam(png, tol);
   const name = input.split("/").pop() ?? input;
@@ -13928,7 +14437,7 @@ async function uiSeams(opts, log) {
     );
     return;
   }
-  fail(
+  fail2(
     `Visible ${r.worstAxis} tiling seam in ${name}: the tile boundary jumps ${r.worstRatio}\xD7 the texture's own detail (want \u2264 ${tol}\xD7). Regenerate it seamless/tileable. Don't hide it behind a hand-picked UV repeat \u2014 that trades a seam for a stretched texture (scale belongs in the UVs: worldUV, genex-ai-texture).`
   );
 }
@@ -13955,7 +14464,13 @@ ${c.bold("Usage")}
   genex texture "<prompt>" [options] Generate a PBR texture into public/assets/textures.
   genex image "<prompt>" [options]   Generate an image (PNG); prints a public asset URL.
   genex video "<prompt>" [options]   Generate a video (mp4); prints a public asset URL.
-  genex character "<prompt>"         Generate a controller-ready Meshy character.
+  genex character "<brief>"          Generate 3 character concepts for user selection.
+  genex character preview <concept-id>
+                                     Generate an unremeshed Meshy 6 preview of one
+                                     explicitly user-approved concept candidate.
+  genex character finalize <preview-id>
+                                     Finalize an approved preview as a 10,000-face
+                                     controller-ready Meshy character.
   genex character animate <id>       Add Meshy library actions to that character.
   genex animations search "<intent>" Search Meshy's animation library by gameplay intent.
   genex wait <id>                    Attach to a generation enqueued with --no-wait and
@@ -14060,12 +14575,19 @@ ${c.bold("Options for `list`")}
   --auth-url <url>     Override the auth site (used only if sign-in is needed).
 
 ${c.bold("Options for `character` / `animations search`")}
-  --animation <id|q>   (character) add an action; repeatable. Ambiguous queries print
+  --animation <id|q>   (character/finalize) add an action; repeatable. Ambiguous queries print
                        ranked action IDs instead of choosing silently.
-  --no-controller-pack (character) skip the validated idle/walk/run/jump pack.
+  --candidate <1|2|3>  (character preview) selected concept candidate.
+  --user-approved      Confirm the user explicitly approved the candidate/preview.
+  --approve-remesh 10000
+                       (character finalize) approve the separate 10,000-face rigging copy.
+  --direct-text        Compatibility path: skip concept/preview approval and generate
+                       directly from text (defaults to a 10,000-face target).
+  --no-controller-pack (character --direct-text only) skip the validated locomotion pack.
   --height <meters>    (character) target character height, 0.5-3 meters.
-  --polycount <count>  (character) target 10000-100000 polygons.
-  --no-wait            (character/animate) enqueue and return a generation id.
+  --polycount <count>  (character --direct-text only) target 10000-100000 polygons.
+  --no-wait            (character/preview/finalize/animate) enqueue and return a generation id.
+  --json               Emit one machine-readable workflow result object.
   --action <id|query>  (character animate) action to add; repeatable.
   --category <name>    (animations search) restrict results to a Meshy category.
   --in-place           (animations search) return provider-declared InPlace actions only.
@@ -14116,7 +14638,10 @@ ${c.bold("Examples")}
   genex ui extract --in <sheet-url> --out-dir ui/ --names health-bar,minimap,ammo
   genex controller character
   genex animations search "rifle reload" --json
-  genex character "stylized sci-fi courier, practical clothing" --animation 466 --no-wait
+  genex character "stylized sci-fi courier, practical clothing" --animation 466
+  genex character preview <concept-id> --candidate 2 --user-approved
+  genex character finalize <preview-id> --user-approved --approve-remesh 10000 --animation 466
+  genex character "stylized sci-fi courier" --direct-text --no-wait
   genex character animate <character-id> --action <action-id>
   genex controller character --character <character-id>
   genex controller anims sword pistol
@@ -14175,6 +14700,8 @@ function parseArgs(argv) {
     "--action",
     "--height",
     "--polycount",
+    "--candidate",
+    "--approve-remesh",
     "--category",
     "--limit"
   ]);
@@ -14206,6 +14733,12 @@ function parseArgs(argv) {
       case "--no-controller-pack":
         parsed.options.controllerPack = false;
         break;
+      case "--user-approved":
+        parsed.options.userApproved = true;
+        break;
+      case "--direct-text":
+        parsed.options.directText = true;
+        break;
       case "--in-place":
         parsed.options.inPlace = true;
         break;
@@ -14267,7 +14800,11 @@ function parseArgs(argv) {
         } else if (parsed.command === "character") {
           if (parsed.options.name === "animate" && !parsed.options.characterId) {
             parsed.options.characterId = arg;
-          } else if (parsed.options.name !== "animate") {
+          } else if (parsed.options.name === "preview" && !parsed.options.conceptId) {
+            parsed.options.conceptId = arg;
+          } else if (parsed.options.name === "finalize" && !parsed.options.previewId) {
+            parsed.options.previewId = arg;
+          } else if (!["animate", "preview", "finalize"].includes(parsed.options.name ?? "")) {
             parsed.options.name = `${parsed.options.name} ${arg}`;
           } else {
             parsed.error = `Unexpected argument: ${arg}`;
@@ -14369,6 +14906,22 @@ function applyValueFlag(options, flag, value) {
       options.polycount = n;
       break;
     }
+    case "--candidate": {
+      const n = Number(value);
+      if (!Number.isInteger(n) || n < 1 || n > 3) {
+        throw new Error(`Invalid --candidate value: ${value} (expected 1|2|3)`);
+      }
+      options.candidate = n;
+      break;
+    }
+    case "--approve-remesh": {
+      const n = Number(value);
+      if (!Number.isInteger(n) || n !== 1e4) {
+        throw new Error(`Invalid --approve-remesh value: ${value} (expected exactly 10000)`);
+      }
+      options.approveRemesh = n;
+      break;
+    }
     case "--category":
       options.category = value;
       break;
@@ -14533,6 +15086,10 @@ async function main() {
       case "character":
         if (parsed.options.name === "animate") {
           await runCharacterAnimate(parsed.options);
+        } else if (parsed.options.name === "preview") {
+          await runCharacterPreview(parsed.options);
+        } else if (parsed.options.name === "finalize") {
+          await runCharacterFinalize(parsed.options);
         } else {
           await runCharacter({ ...parsed.options, prompt: parsed.options.name });
         }