ima2-gen 3.11.0 → 3.12.1

package/README.md

@@ -156,7 +156,7 @@ Image generation can run through the local Codex/ChatGPT OAuth path, a configure
 - `provider: "api"` calls the OpenAI Responses API with the hosted `image_generation` tool.
 - `provider: "grok"` starts bundled `progrok` on `127.0.0.1:18645`, runs mandatory xAI Web Search plus a planner pass (default: `grok-4.5`, configurable in settings or via `--planner-model`), then calls xAI Images API through the local proxy. `grok-4.3` remains available as an explicit compatibility override.
 - `provider: "grok-api"` calls the xAI Images API directly with `XAI_API_KEY` (no bundled progrok OAuth proxy).
-- `provider: "nai"` calls the NovelAI image API with a persistent API token (`pst-...`, saved in Settings > API Keys or `NOVELAI_API_KEY`). Four models: `nai-diffusion-5-full`, `nai-diffusion-5-curated`, `nai-diffusion-4-5-full`, `nai-diffusion-4-5-curated`. Responses arrive as a ZIP archive that ima2 decodes to PNG. Text-to-image only — reference images and edits are refused rather than silently dropped, and image generation requires an active NovelAI subscription.
+- `provider: "nai"` calls the NovelAI image API with a persistent API token (saved in Settings > API Keys or `NOVELAI_API_KEY`; no fixed token prefix is required). Four models: `nai-diffusion-5-full`, `nai-diffusion-5-curated`, `nai-diffusion-4-5-full`, `nai-diffusion-4-5-curated`. Responses arrive as a ZIP archive that ima2 decodes to PNG. Text-to-image only — reference images, edits, and masks are refused rather than silently dropped. Browser and CLI surfaces expose negative prompt, sampler/schedule, steps/guidance/CFG rescale, seed, presets, Auto SMEA, Decrisper, Variety+, and V5 alpha.
 - `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool (model: `nano-banana-2`). Output is fixed at 1024×1024 JPEG, max 3 reference images. No web search, quality, or size controls.
 - `provider: "gemini-api"` calls the Google Generative Language API directly. Supports two models: `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Auth is via `GEMINI_API_KEY` env var, web UI key management, or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON`). When both an API key and Vertex credentials are configured, Vertex takes priority. Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K); these controls are only honored on the direct API path — the Vertex AI endpoint ignores aspect/size because it does not accept the `response_format` field. Per-model cost differs: `nano-banana-2` (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; `nano-banana-pro`: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
 - API-key generation supports classic generate, edit, mask-guided edit, multimode, and node generation.
@@ -320,6 +320,8 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `XAI_API_KEY` | — | API key for `provider: "grok-api"` direct xAI Images API path |
 | `NOVELAI_API_KEY` | — | NovelAI persistent API token for `provider: "nai"` |
 | `IMA2_NAI_IMAGE_MODEL_DEFAULT` | `nai-diffusion-5-full` | Default NovelAI image model |
+| `IMA2_NAI_DEFAULT_AUTO_SMEA` | `false` | Default NovelAI Auto SMEA state |
+| `IMA2_NAI_DEFAULT_DECRISPER` | `false` | Default NovelAI Decrisper (`dynamic_thresholding`) state |
 | `IMA2_API_IMAGE_MODEL_DEFAULT` | `gpt-5.6-luna` | Default image model for `provider: "api"` |
 | `IMA2_API_REASONING_EFFORT` | `low` | Default reasoning effort for `provider: "api"` |
 | `IMA2_API_IMAGE_SIZE` | `1024x1024` | Default size for `provider: "api"` |

package/bin/commands/gen.js

@@ -17,6 +17,7 @@ import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from
 import { deriveProviderIds } from "../../lib/providers/derive.js";
 import { listProviders } from "../../lib/mcp/providerRegistry.js";
 import { BACKGROUND_PRESETS } from "../../lib/backgroundPresets.js";
+import { NAI_CLI_FLAGS, NAI_CLI_HELP, finalizeNaiCliTarget, parseNaiCliOptions, unwrapNaiCliResult } from "../lib/nai-options.js";
 const VALID_MODES = new Set(["auto", "direct"]);
 const VALID_MODERATION = new Set(["auto", "low"]);
 const MAX_GENERATION_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxGeneratedImages) || 24));
@@ -43,6 +44,7 @@ const SPEC = {
         character: { type: "string" },
         "reasoning-effort": { type: "string" }, "web-search": { type: "boolean" },
         "no-web-search": { type: "boolean" }, help: { short: "h", type: "boolean" },
+        ...NAI_CLI_FLAGS,
     },
 };
 const HELP = `
@@ -83,6 +85,7 @@ const HELP = `
         --reasoning-effort <none|low|medium|high|xhigh|max>
                                             Core lanes only
         --web-search / --no-web-search      Core lanes only
+${NAI_CLI_HELP}
 
   Examples:
     ima2 defaults set image oauth/gpt-5.6-luna
@@ -90,6 +93,7 @@ const HELP = `
     ima2 gen "poster" --model oauth/luna --mode direct
     ima2 gen "fox logo mark" --bg transparent -o logo.png
     ima2 gen "campaign still" --model runway/gen-4 --ref 1780000000000_abcd.png
+    ima2 gen "transparent character sprite" --provider nai --model nai-diffusion-5-full --nai-straight-alpha --nai-negative-prompt "watermark"
 `;
 /**
  * Resolves --out against --out-dir.
@@ -287,7 +291,7 @@ async function requestCoreImage(args, context, n, requestId) {
     const body = { prompt: context.prompt, quality: args.quality, size: args.size, n, references,
         ...(args["no-size-nudge"] ? { sizeNudge: false } : {}),
         model: context.target.model, mode: args.mode, moderation: args.moderation, sessionId: args.session,
-        provider: context.target.lane };
+        provider: context.target.lane, ...context.naiOptions };
     body.requestId = requestId;
     if (args.bg)
         body.backgroundPreset = String(args.bg);
@@ -385,6 +389,7 @@ export default async function genCmd(argv) {
         out(HELP);
         return;
     }
+    const naiPreflight = unwrapNaiCliResult(parseNaiCliOptions(args, "allow-unknown"), Boolean(args.json));
     let prompt = args.positional.join(" ");
     if (!prompt && !args.stdin)
         die(2, "prompt is required (positional or via --stdin)");
@@ -393,13 +398,14 @@ export default async function genCmd(argv) {
         die(2, `max ${MAX_REFERENCE_COUNT} --ref attachments`);
     const { server, catalog } = await fetchCatalog(args.server, Boolean(args.json));
     const target = resolveImageTarget(args, catalog);
+    const naiFinal = unwrapNaiCliResult(finalizeNaiCliTarget(naiPreflight, target), Boolean(args.json));
     if (args.character && target.transport !== "mcp") {
         fail({ json: Boolean(args.json), code: "CAPABILITY_MISMATCH",
             message: "--character is only supported on MCP lanes (runway/higgsfield); core lanes use element mentions",
             exitCode: 2 });
     }
     let context = { server, catalog, target, prompt, refs, explicitOut: args.out ? String(args.out) : null,
-        outDir: args["out-dir"] ? String(args["out-dir"]) : null };
+        outDir: args["out-dir"] ? String(args["out-dir"]) : null, naiOptions: naiFinal.payload };
     if (target.transport === "mcp")
         return runMcpImage(argv, args, context);
     if (args.stdin) {

package/bin/commands/multimode.js

@@ -7,6 +7,7 @@ import { config } from "../../config.js";
 import { createCliRequestId, recoverGeneratedOutputs, formatRecoveryHint } from "../lib/recover-output.js";
 import { canonicalizeImageModel } from "../lib/model-aliases.js";
 import { deriveCliImageModelSet, deriveProviderIds } from "../../lib/providers/derive.js";
+import { NAI_CLI_FLAGS, NAI_CLI_HELP, parseNaiCliOptions, unwrapNaiCliResult } from "../lib/nai-options.js";
 const MAX_GENERATION_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxGeneratedImages) || 24));
 const MAX_REFERENCE_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxRefCount) || 5));
 const PROVIDER_VALUES = ["auto", ...deriveProviderIds()];
@@ -34,6 +35,7 @@ const SPEC = {
         session: { type: "string" },
         "show-partial": { type: "boolean" },
         help: { short: "h", type: "boolean" },
+        ...NAI_CLI_FLAGS,
     },
 };
 const HELP = `
@@ -62,6 +64,7 @@ const HELP = `
         --show-partial                  Print [partial #N received] notices
         --timeout <sec>                 Default: 600
         --server <url>                  Override server URL
+${NAI_CLI_HELP}
 `;
 export default async function multimodeCmd(argv) {
     const hasCount = argv.some((value) => value === "-n" || value === "--count" || value.startsWith("--count="));
@@ -73,6 +76,7 @@ export default async function multimodeCmd(argv) {
         out(HELP);
         return;
     }
+    const naiPreflight = unwrapNaiCliResult(parseNaiCliOptions(args, "require-explicit"), Boolean(args.json));
     const prompt = args.positional.join(" ");
     if (!prompt)
         die(2, "prompt required");
@@ -117,6 +121,7 @@ export default async function multimodeCmd(argv) {
         moderation: args.moderation,
         sessionId: args.session,
         requestId,
+        ...naiPreflight.payload,
     };
     const model = canonicalizeImageModel(args.model);
     if (model)

package/bin/commands/node.js

@@ -6,6 +6,7 @@ import { out, die, color, json, exitCodeForError } from "../lib/output.js";
 import { canonicalizeImageModel } from "../lib/model-aliases.js";
 import { config } from "../../config.js";
 import { deriveProviderIds } from "../../lib/providers/derive.js";
+import { NAI_CLI_FLAGS, NAI_CLI_HELP, parseNaiCliOptions, unwrapNaiCliResult } from "../lib/nai-options.js";
 const MAX_GENERATION_COUNT = Math.max(1, Math.trunc(Number(config.limits.maxGeneratedImages) || 24));
 const PROVIDER_VALUES = ["auto", ...deriveProviderIds()];
 const HELP = `
@@ -16,7 +17,8 @@ const HELP = `
     show <nodeId> [--json]
 
   Generate options:
-        --provider <${PROVIDER_VALUES.join("|")}>  Provider for this request
+    --provider <${PROVIDER_VALUES.join("|")}>  Provider for this request
+${NAI_CLI_HELP}
 `;
 const GEN_FLAGS = {
     quality: { short: "q", type: "string", default: "low" },
@@ -37,6 +39,7 @@ const GEN_FLAGS = {
     session: { type: "string" },
     "no-stream": { type: "boolean" },
     help: { short: "h", type: "boolean" },
+    ...NAI_CLI_FLAGS,
 };
 const SHOW_FLAGS = {
     json: { type: "boolean" },
@@ -58,6 +61,7 @@ async function generateSub(argv) {
         out(HELP);
         return;
     }
+    const naiPreflight = unwrapNaiCliResult(parseNaiCliOptions(args, "require-explicit"), Boolean(args.json));
     const prompt = args.positional.join(" ");
     if (!prompt)
         die(2, "prompt required");
@@ -83,6 +87,7 @@ async function generateSub(argv) {
         references,
         moderation: args.moderation,
         sessionId: args.session,
+        ...naiPreflight.payload,
     };
     const model = canonicalizeImageModel(args.model);
     if (model)

package/bin/lib/args.js

@@ -6,7 +6,7 @@ export function parseArgs(argv, spec = {}) {
         if (def.short)
             shortMap[def.short] = name;
     }
-    const out = { positional: [], _unknown: [] };
+    const out = { positional: [], _unknown: [], _present: [] };
     for (const [name, def] of Object.entries(spec.flags || {})) {
         if (def.repeatable)
             out[name] = [];
@@ -38,6 +38,7 @@ export function parseArgs(argv, spec = {}) {
                 i++;
                 continue;
             }
+            out._present.push(name);
             if (def.type === "boolean") {
                 out[name] = true;
                 i++;
@@ -61,6 +62,7 @@ export function parseArgs(argv, spec = {}) {
                 i++;
                 continue;
             }
+            out._present.push(name);
             const def = spec.flags[name];
             if (def.type === "boolean") {
                 out[name] = true;

package/bin/lib/nai-options.js

@@ -0,0 +1,195 @@
+import { NAI_NOISE_SCHEDULES, NAI_QUALITY_PRESET_IDS, NAI_SAMPLERS, NAI_UC_PRESET_IDS, } from "../../lib/naiImageAdapter.js";
+import { getProvider } from "../../lib/providers/registry.js";
+import { fail } from "./output.js";
+export const NAI_CLI_FLAGS = {
+    "nai-negative-prompt": { type: "string" },
+    "nai-sampler": { type: "string" },
+    "nai-noise-schedule": { type: "string" },
+    "nai-steps": { type: "string" },
+    "nai-scale": { type: "string" },
+    "nai-cfg-rescale": { type: "string" },
+    "nai-seed": { type: "string" },
+    "nai-uc-preset": { type: "string" },
+    "nai-quality-preset": { type: "string" },
+    "nai-auto-smea": { type: "boolean" },
+    "no-nai-auto-smea": { type: "boolean" },
+    "nai-decrisper": { type: "boolean" },
+    "no-nai-decrisper": { type: "boolean" },
+    "nai-variety-plus": { type: "boolean" },
+    "no-nai-variety-plus": { type: "boolean" },
+    "nai-straight-alpha": { type: "boolean" },
+    "no-nai-straight-alpha": { type: "boolean" },
+};
+export const NAI_CLI_HELP = `
+  NovelAI options (nai lane only):
+        --nai-negative-prompt <text>       Undesired content (max 10,000 chars)
+        --nai-sampler <sampler>            ${NAI_SAMPLERS.filter((v) => v !== "ddim_v3").join("|")}
+        --nai-noise-schedule <schedule>    ${NAI_NOISE_SCHEDULES.join("|")}
+        --nai-steps <1..50>                Diffusion steps
+        --nai-scale <1..10>                Prompt guidance
+        --nai-cfg-rescale <0..1>           Guidance rescale
+        --nai-seed <0..4294967295>         Reproducible seed
+        --nai-uc-preset <preset>           ${NAI_UC_PRESET_IDS.join("|")}
+        --nai-quality-preset <preset>      ${NAI_QUALITY_PRESET_IDS.join("|")} (V5 only)
+        --nai-auto-smea / --no-nai-auto-smea
+        --nai-decrisper / --no-nai-decrisper
+        --nai-variety-plus / --no-nai-variety-plus
+        --nai-straight-alpha / --no-nai-straight-alpha  V5 only
+`;
+export function unwrapNaiCliResult(result, jsonMode) {
+    if ("message" in result) {
+        fail({ json: jsonMode, code: result.code, message: result.message,
+            ...(result.flag ? { extra: { flag: result.flag } } : {}) });
+    }
+    return result.value;
+}
+const SELECTABLE_SAMPLERS = NAI_SAMPLERS.filter((value) => value !== "ddim_v3");
+const NAI_MODEL_IDS = new Set(getProvider("nai").models.filter((model) => model.kind === "image").map((model) => model.id));
+const V5_MODEL_IDS = new Set(["nai-diffusion-5-full", "nai-diffusion-5-curated"]);
+const OPTION_KEYS = Object.keys(NAI_CLI_FLAGS);
+const VALUE_OPTION_KEYS = Object.entries(NAI_CLI_FLAGS)
+    .filter(([, definition]) => definition.type !== "boolean")
+    .map(([key]) => key);
+function failure(code, message, flag) {
+    return { ok: false, code, message, ...(flag ? { flag } : {}) };
+}
+function isFailure(value) {
+    return Boolean(value && typeof value === "object" && "ok" in value && value.ok === false);
+}
+function explicitModel(raw) {
+    if (typeof raw !== "string" || !raw)
+        return null;
+    const slash = raw.indexOf("/");
+    if (slash < 0)
+        return NAI_MODEL_IDS.has(raw) ? raw : null;
+    const lane = raw.slice(0, slash);
+    const model = raw.slice(slash + 1);
+    return lane === "nai" && NAI_MODEL_IDS.has(model) ? model : null;
+}
+function classifyTarget(args) {
+    const provider = typeof args.provider === "string" ? args.provider : undefined;
+    const providerClass = !provider || provider === "auto"
+        ? "unknown"
+        : provider === "nai" ? "nai" : "non-nai";
+    const rawModel = typeof args.model === "string" ? args.model : undefined;
+    const modelClass = !rawModel
+        ? "unknown"
+        : explicitModel(rawModel) ? "nai" : "non-nai";
+    if ((providerClass === "nai" && modelClass === "non-nai") ||
+        (providerClass === "non-nai" && modelClass === "nai"))
+        return "conflict";
+    if (providerClass === "nai" || modelClass === "nai")
+        return "nai";
+    if (providerClass === "non-nai" || modelClass === "non-nai")
+        return "non-nai";
+    return "unknown";
+}
+function enumValue(args, key, allowed) {
+    const raw = args[key];
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== "string" || !allowed.includes(raw)) {
+        return failure("NAI_FLAG_INVALID", `--${key} must be one of: ${allowed.join(", ")}`, `--${key}`);
+    }
+    return raw;
+}
+function numberValue(args, key, min, max, integer = false) {
+    const raw = args[key];
+    if (raw === undefined)
+        return undefined;
+    const value = typeof raw === "string" && raw.trim() !== "" ? Number(raw) : Number.NaN;
+    if (!Number.isFinite(value) || value < min || value > max || (integer && !Number.isInteger(value))) {
+        return failure("NAI_FLAG_INVALID", `--${key} must be ${integer ? "an integer " : ""}between ${min} and ${max}`, `--${key}`);
+    }
+    return value;
+}
+function booleanPair(args, positive, negative) {
+    if (args[positive] && args[negative]) {
+        return failure("NAI_FLAG_CONFLICT", `--${positive} and --${negative} are mutually exclusive`, `--${positive}`);
+    }
+    if (args[positive])
+        return true;
+    if (args[negative])
+        return false;
+    return undefined;
+}
+function assignValue(payload, key, value) {
+    if (isFailure(value))
+        return value;
+    if (value !== undefined)
+        payload[key] = value;
+    return null;
+}
+function buildPayload(args) {
+    const payload = {};
+    const negative = args["nai-negative-prompt"];
+    if (negative !== undefined) {
+        if (typeof negative !== "string" || negative.length > 10_000) {
+            return failure("NAI_FLAG_INVALID", "--nai-negative-prompt must be at most 10,000 characters", "--nai-negative-prompt");
+        }
+        payload.negativePrompt = negative;
+    }
+    const values = [
+        ["sampler", enumValue(args, "nai-sampler", SELECTABLE_SAMPLERS)],
+        ["noiseSchedule", enumValue(args, "nai-noise-schedule", NAI_NOISE_SCHEDULES)],
+        ["steps", numberValue(args, "nai-steps", 1, 50, true)],
+        ["scale", numberValue(args, "nai-scale", 1, 10)],
+        ["cfgRescale", numberValue(args, "nai-cfg-rescale", 0, 1)],
+        ["seed", numberValue(args, "nai-seed", 0, 2 ** 32 - 1, true)],
+        ["ucPresetId", enumValue(args, "nai-uc-preset", NAI_UC_PRESET_IDS)],
+        ["qualityPresetId", enumValue(args, "nai-quality-preset", NAI_QUALITY_PRESET_IDS)],
+        ["autoSmea", booleanPair(args, "nai-auto-smea", "no-nai-auto-smea")],
+        ["decrisper", booleanPair(args, "nai-decrisper", "no-nai-decrisper")],
+        ["varietyPlus", booleanPair(args, "nai-variety-plus", "no-nai-variety-plus")],
+        ["straightAlpha", booleanPair(args, "nai-straight-alpha", "no-nai-straight-alpha")],
+    ];
+    for (const [key, value] of values) {
+        const error = assignValue(payload, key, value);
+        if (error)
+            return error;
+    }
+    return payload;
+}
+function needsV5(payload) {
+    return payload.straightAlpha === true || payload.qualityPresetId !== undefined;
+}
+export function parseNaiCliOptions(args, policy) {
+    const present = new Set(args._present ?? []);
+    const hasOptions = OPTION_KEYS.some((key) => present.has(key) || args[key] !== undefined);
+    if (!hasOptions)
+        return { ok: true, value: { hasOptions: false, payload: {}, target: "unknown" } };
+    const missingValue = VALUE_OPTION_KEYS.find((key) => present.has(key) && args[key] === undefined);
+    if (missingValue) {
+        return failure("NAI_FLAG_INVALID", `--${missingValue} requires a value`, `--${missingValue}`);
+    }
+    const built = buildPayload(args);
+    if (isFailure(built))
+        return built;
+    const target = classifyTarget(args);
+    if (target === "conflict")
+        return failure("NAI_TARGET_CONFLICT", "NovelAI flags conflict with the explicit provider/model target");
+    if (target === "non-nai")
+        return failure("NAI_FLAG_TARGET_MISMATCH", "NovelAI flags require a NovelAI provider/model target");
+    if (target === "unknown" && policy === "require-explicit") {
+        return failure("NAI_EXPLICIT_TARGET_REQUIRED", "NovelAI flags require --provider nai or --model nai-diffusion-*");
+    }
+    const model = explicitModel(args.model);
+    if (needsV5(built) && policy === "require-explicit" && !model) {
+        return failure("NAI_V5_MODEL_REQUIRED", "V5-only NovelAI flags require an explicit V5 model");
+    }
+    if (needsV5(built) && model && !V5_MODEL_IDS.has(model)) {
+        return failure("NAI_V5_MODEL_REQUIRED", "V5-only NovelAI flags are not supported by V4.5");
+    }
+    return { ok: true, value: { hasOptions, payload: built, target } };
+}
+export function finalizeNaiCliTarget(preflight, target) {
+    if (!preflight.hasOptions)
+        return { ok: true, value: preflight };
+    if (target.lane !== "nai" || !NAI_MODEL_IDS.has(target.model)) {
+        return failure("NAI_FLAG_TARGET_MISMATCH", "NovelAI flags require a resolved NovelAI target");
+    }
+    if (needsV5(preflight.payload) && !V5_MODEL_IDS.has(target.model)) {
+        return failure("NAI_V5_MODEL_REQUIRED", "V5-only NovelAI flags are not supported by V4.5");
+    }
+    return { ok: true, value: { ...preflight, target: "nai" } };
+}

package/config.js

@@ -260,6 +260,8 @@ export const config = {
         defaultScale: pickInt(env.IMA2_NAI_DEFAULT_SCALE, fileCfg.naiProvider?.defaultScale, 5),
         defaultSampler: pickStr(env.IMA2_NAI_DEFAULT_SAMPLER, fileCfg.naiProvider?.defaultSampler, "k_euler_ancestral"),
         defaultNoiseSchedule: pickStr(env.IMA2_NAI_DEFAULT_NOISE_SCHEDULE, fileCfg.naiProvider?.defaultNoiseSchedule, "karras"),
+        defaultAutoSmea: pickBool(env.IMA2_NAI_DEFAULT_AUTO_SMEA, fileCfg.naiProvider?.defaultAutoSmea, false),
+        defaultDecrisper: pickBool(env.IMA2_NAI_DEFAULT_DECRISPER, fileCfg.naiProvider?.defaultDecrisper, false),
     },
     log: {
         level: pickStr(env.IMA2_LOG_LEVEL, fileCfg.log?.level, defaultLogLevelForEnv(env)),

package/docs/API.md

@@ -18,6 +18,7 @@ Image generation supports OAuth, API-key, Grok, and Gemini (`agy` and `gemini-ap
 - `provider: "agy"` spawns the Antigravity CLI (`agy -p`) to generate images via Google Gemini's `default_api:generate_image` tool. Model is `nano-banana-2`. Output is fixed at 1024×1024 JPEG. Max 3 reference images (i2i). No web search, quality, size, or mask controls. Multimode returns a single image. Video is unsupported (`AGY_VIDEO_UNSUPPORTED`).
 - `provider: "grok-api"` uses a direct xAI API key instead of the bundled progrok OAuth proxy. Same pipeline as `grok` (Web Search → planner → `/v1/images/generations`), same aspect ratio and resolution options. Requires an xAI API key configured via the web UI key management or `XAI_API_KEY` env var. Also supports video generation.
 - `provider: "gemini-api"` calls the Google Generative Language API directly (or Vertex AI with a service account JSON). Supports models `nano-banana-2` (Gemini 3.1 Flash Image) and `nano-banana-pro` (Gemini 3 Pro Image). Supports variable aspect ratios (1:1 through 21:9) and four resolution tiers (512px, 1K, 2K, 4K) on both auth paths — the direct API path sends `generation_config.response_format.image` (snake_case) while the Vertex AI endpoint (`aiplatform.googleapis.com`) sends `generationConfig.imageConfig` (camelCase). With `size: "auto"` the image config is omitted entirely and the model decides ratio/size. Auth: `GEMINI_API_KEY` env var, web UI key management (`/api/keys/gemini`), or a Vertex AI service account JSON (`VERTEX_SERVICE_ACCOUNT_JSON` or `/api/keys/vertex`). When both Vertex credentials and an API key are configured, Vertex takes priority. The chosen auth mode (`apikey` or `vertex`) persists to `~/.ima2/config.json` as `geminiAuthMode` and is restored on server startup. Per-model cost: `nano-banana-2` (Flash): 512=$0.001, 1K=$0.003, 2K=$0.004, 4K=$0.006; `nano-banana-pro`: 1K=$0.007, 2K=$0.007, 4K=$0.013. No web search or mask controls.
+- `provider: "nai"` calls NovelAI text-to-image generation with one of `nai-diffusion-5-full`, `nai-diffusion-5-curated`, `nai-diffusion-4-5-full`, or `nai-diffusion-4-5-curated`. It accepts the provider-native request fields documented below and returns a ZIP that ima2 decodes to PNG. References, edits, and masks are explicitly refused.
 - API-key generation covers classic generate, edit, mask-guided edit, multimode, and node generation.
 - If `provider: "api"` is requested without an API key, routes fail before upstream with `401` and `API_KEY_REQUIRED`.
 - Grok generation maps `size` to xAI `aspect_ratio` and `resolution`; it does not send an OpenAI-style `size` field upstream. Grok edit uses xAI `/v1/images/edits`; Grok mask edit remains unsupported and returns `GROK_MASK_UNSUPPORTED`.
@@ -216,6 +217,19 @@ generations maintain character and scene continuity for multi-shot video product
 
 Current app default: `gpt-5.6-luna`. `gpt-5.5` and the other supported GPT image models remain available when callers explicitly select them.
 
+When `provider` is `"nai"`, classic, multimode, and node generation accept the
+same 13 provider-native fields: `negativePrompt`, `sampler`, `noiseSchedule`,
+`steps`, `scale`, `cfgRescale`, `seed`, `ucPresetId`, `qualityPresetId`,
+`autoSmea`, `decrisper`, `varietyPlus`, and `straightAlpha`. Missing values stay
+sparse and resolve from `config.naiProvider`; operator defaults `defaultAutoSmea`
+and `defaultDecrisper` are `false` unless overridden by config or
+`IMA2_NAI_DEFAULT_AUTO_SMEA` / `IMA2_NAI_DEFAULT_DECRISPER`. Quality preset and
+enabled alpha are V5-only. The four exact image models are
+`nai-diffusion-5-full`, `nai-diffusion-5-curated`,
+`nai-diffusion-4-5-full`, and `nai-diffusion-4-5-curated`. The lane is
+text-to-image only: `NAI_REF_UNSUPPORTED`, `NAI_EDIT_UNSUPPORTED`, and
+`NAI_MASK_UNSUPPORTED` fail closed rather than discarding input.
+
 When `provider` is `"grok"`, supported models are `grok-imagine-image` and
 `grok-imagine-image-quality`. The server uses `grok-4.5` as the search/planner
 model by default (`IMA2_GROK_PLANNER_MODEL`) and times the mandatory search and
@@ -758,7 +772,7 @@ API key management endpoints for configuring provider credentials at runtime thr
 | Endpoint | Method | Description |
 |---|---|---|
 | `/api/keys/status` | GET | Returns configured/valid/maskedKey status for all providers (openai, xai, gemini, atlascloud, minimax, nai, vertex) plus `geminiAuthMode` (`"apikey"` or `"vertex"`) |
-| `/api/keys/:provider` | PUT | Save an API key. Body: `{ "apiKey": "..." }`. Validates key format and upstream before saving to config.json. Provider: `openai`, `xai`, `gemini`, `atlascloud`, `minimax`, or `nai`. `minimax` and `nai` have no fixed key prefix, so only the upstream validation call gates them; a NovelAI persistent token looks like `pst-...`. |
+| `/api/keys/:provider` | PUT | Save an API key. Body: `{ "apiKey": "..." }`. Validates key format and upstream before saving to config.json. Provider: `openai`, `xai`, `gemini`, `atlascloud`, `minimax`, or `nai`. `minimax` and `nai` have no fixed key prefix, so only the upstream validation call gates them. |
 | `/api/keys/:provider` | DELETE | Remove a config-sourced API key. Env-sourced keys cannot be removed (`ENV_KEY_IMMUTABLE`). |
 | `/api/keys/vertex` | PUT | Save a Vertex AI service account JSON. Body: `{ "serviceAccountJson": "..." }`. Validates JSON structure (`type: "service_account"`, `project_id` required). |
 | `/api/keys/vertex` | DELETE | Remove a config-sourced Vertex AI service account. |

package/docs/CLI.md

@@ -90,6 +90,47 @@ Provider override semantics:
 - `runway` / `higgsfield` (gen/video only) route through the MCP async pipeline (`POST /api/mcp/generate` + SSE wait). Runway requires an MCP connection; Higgsfield stays catalog-only (`locked`) until a paid plan. MCP lanes accept `-n 1` only, gallery filenames for `--ref`, and reject core-only flags with `FLAG_NOT_SUPPORTED`.
 - `auto` preserves route default behavior and currently resolves to GPT OAuth unless server routing changes (edit/multimode/node only; removed from gen/video in 3.0.0).
 
+### NovelAI native generation options
+
+`ima2 gen`, `ima2 multimode`, and `ima2 node generate` share these request-only
+flags. They do not change saved defaults.
+
+| Flag | Request field | Rule |
+|---|---|---|
+| `--nai-negative-prompt <text>` | `negativePrompt` | Undesired content, max 10,000 characters |
+| `--nai-sampler <id>` | `sampler` | Modern NovelAI sampler enum |
+| `--nai-noise-schedule <id>` | `noiseSchedule` | `native`, `karras`, `exponential`, or `polyexponential` |
+| `--nai-steps <1..50>` | `steps` | Integer |
+| `--nai-scale <1..10>` | `scale` | Prompt guidance |
+| `--nai-cfg-rescale <0..1>` | `cfgRescale` | Guidance rescale |
+| `--nai-seed <0..4294967295>` | `seed` | Integer; zero is valid |
+| `--nai-uc-preset <id>` | `ucPresetId` | `heavy`, `light`, `furryFocus`, `humanFocus`, or `none` |
+| `--nai-quality-preset <id>` | `qualityPresetId` | `standard`, `light`, or `none`; V5 only |
+| `--nai-auto-smea` / `--no-nai-auto-smea` | `autoSmea` | Explicit true/false |
+| `--nai-decrisper` / `--no-nai-decrisper` | `decrisper` | Explicit true/false |
+| `--nai-variety-plus` / `--no-nai-variety-plus` | `varietyPlus` | Explicit true/false |
+| `--nai-straight-alpha` / `--no-nai-straight-alpha` | `straightAlpha` | Enabled alpha is V5 only |
+
+`gen` may resolve a persisted NovelAI default set with
+`ima2 defaults set image nai/nai-diffusion-5-full`. `multimode` requires an
+explicit NovelAI target when any `--nai-*` flag is used, and `node generate`
+likewise requires an explicit NovelAI target. Provider/model conflicts fail before
+network I/O. V5-only values on V4.5 fail with `NAI_V5_MODEL_REQUIRED`; malformed
+values and non-NAI targets also exit 2. The ima2 NovelAI lane is text-to-image only:
+references, edits, and masks remain explicitly unsupported.
+
+```bash
+ima2 gen "character sprite, transparent background, has alpha" \
+  --model nai/nai-diffusion-5-full --nai-straight-alpha \
+  --nai-negative-prompt "watermark" -o sprite.png
+
+ima2 multimode "city at night" --provider nai --model nai-diffusion-5-full \
+  --nai-auto-smea --nai-decrisper --max-images 2
+
+ima2 node generate "portrait" --provider nai --model nai-diffusion-5-curated \
+  --nai-uc-preset light --nai-quality-preset light
+```
+
 `ima2 serve` starts the bundled Grok proxy automatically. No separate `progrok`
 install is required. Use `ima2 grok login` once to authorize xAI OAuth. Login
 defaults to `--manual-paste` so PowerShell, Terminal, and remote shells all use

package/docs/migration/runtime-test-inventory.md

@@ -4,7 +4,7 @@ Generated by `npm run test:inventory` (script: `scripts/classify-tests.mjs`).
 
 _Tests considered "runtime-importing" if they import from `../lib/`, `../routes/`, `../bin/`, `../server`, or `../config`._
 
-Total: 396 (runtime: 186, contract: 210)
+Total: 399 (runtime: 188, contract: 211)
 
 ## Runtime-importing tests
 - `tests/agent-mode-auto-planner-contract.test.ts`
@@ -120,6 +120,8 @@ Total: 396 (runtime: 186, contract: 210)
 - `tests/minimax-provider-contract.test.ts`
 - `tests/model-default-projection-contract.test.ts`
 - `tests/models-endpoint-contract.test.ts`
+- `tests/nai-built-runtime-contract.test.ts`
+- `tests/nai-cli-options-contract.test.ts`
 - `tests/nai-client-options-contract.test.ts`
 - `tests/nai-options-contract.test.ts`
 - `tests/nai-provider-contract.test.ts`
@@ -328,6 +330,7 @@ Total: 396 (runtime: 186, contract: 210)
 - `tests/multimode-backend-contract.test.js`
 - `tests/multimode-concurrent-store-contract.test.js`
 - `tests/multimode-ui-contract.test.js`
+- `tests/nai-cli-built-smoke.test.ts`
 - `tests/nai-ui-registration-contract.test.ts`
 - `tests/navrail-hover-label-contract.test.ts`
 - `tests/node-async-eventbus-contract.test.js`

package/lib/capabilities.js

@@ -64,6 +64,8 @@ export function buildIma2Capabilities({ appConfig = runtimeConfigDefault, packag
                 noiseSchedule: appConfig.naiProvider.defaultNoiseSchedule,
                 steps: appConfig.naiProvider.defaultSteps,
                 scale: appConfig.naiProvider.defaultScale,
+                autoSmea: appConfig.naiProvider.defaultAutoSmea,
+                decrisper: appConfig.naiProvider.defaultDecrisper,
             },
         },
         valid: {

package/lib/naiImageAdapter.js

@@ -79,8 +79,8 @@ export async function generateViaNai(prompt, ctx, options = {}) {
         n_samples: 1,
         ucPresetId: options.ucPresetId ?? "heavy",
         qualityPresetId: isV5 ? (options.qualityPresetId ?? "standard") : "standard",
-        autoSmea: false,
-        dynamic_thresholding: false,
+        autoSmea: options.autoSmea ?? cfg.defaultAutoSmea,
+        dynamic_thresholding: options.decrisper ?? cfg.defaultDecrisper,
         controlnet_strength: 1,
         legacy: false,
         legacy_v3_extend: false,

package/lib/naiOptions.js

@@ -86,6 +86,12 @@ export function readNaiOptions(body) {
     const varietyPlus = pickBoolean(raw.varietyPlus);
     if (varietyPlus !== undefined)
         out.varietyPlus = varietyPlus;
+    const autoSmea = pickBoolean(raw.autoSmea);
+    if (autoSmea !== undefined)
+        out.autoSmea = autoSmea;
+    const decrisper = pickBoolean(raw.decrisper);
+    if (decrisper !== undefined)
+        out.decrisper = decrisper;
     const ucPresetId = pickEnum(raw.ucPresetId, NAI_UC_PRESET_IDS);
     if (ucPresetId !== undefined)
         out.ucPresetId = ucPresetId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ima2-gen",
-  "version": "3.11.0",
+  "version": "3.12.1",
   "packageManager": "npm@11.18.0",
   "description": "Local-first visual generation runtime and studio for people and coding agents, with reproducible image and video workflows across multiple providers.",
   "type": "module",
@@ -119,5 +119,5 @@
     "tsx": "^4.23.12",
     "typescript": "^5.9.3"
   },
-  "gitHead": "d18e56caabd03d5019dbfffa8c9686c9be225e4f"
+  "gitHead": "ae45711d42383755697b66ff0b4a7e49beab8076"
 }

package/skills/ima2/SKILL.md

@@ -100,6 +100,78 @@ Grok requests with reference images use the edit/image-to-image path so the
 references remain attached after planning. Keep Grok references to three total
 input images.
 
+## NovelAI Image Generation
+
+Discover the live NovelAI lane before choosing a model:
+
+```bash
+ima2 models --kind image --lane nai --json
+ima2 defaults set image nai/nai-diffusion-5-full
+```
+
+The four exact model IDs are:
+
+- `nai-diffusion-5-full`
+- `nai-diffusion-5-curated`
+- `nai-diffusion-4-5-full`
+- `nai-diffusion-4-5-curated`
+
+Use a persistent NovelAI token from Settings > API Keys or `NOVELAI_API_KEY`.
+NovelAI does not publish one mandatory token prefix, so never reject a token based
+on a guessed prefix. Check the lane state through `ima2 models` instead.
+
+The same NovelAI options work on `ima2 gen`, `ima2 multimode`, and
+`ima2 node generate`. Run `ima2 gen --help` for the live enum/range list. Example:
+
+```bash
+ima2 gen "1girl, blue hair, city at night" \
+  --provider nai --model nai-diffusion-5-full \
+  --nai-negative-prompt "lowres, watermark" \
+  --nai-steps 28 --nai-scale 5 \
+  --nai-auto-smea --nai-decrisper --nai-variety-plus
+```
+
+For V5 native alpha, pair the request flag with an alpha-aware prompt:
+
+```bash
+ima2 gen "character sprite, transparent background, has alpha" \
+  --model nai/nai-diffusion-5-full \
+  --nai-straight-alpha -o sprite.png
+```
+
+Supported request controls include sampler, noise schedule, steps, guidance,
+CFG rescale, seed, undesired-content/UC preset, quality preset, Auto SMEA,
+Decrisper, Variety+, and V5 native alpha. `--nai-quality-preset` and enabled
+`--nai-straight-alpha` require an explicit V5 model on CLI surfaces that cannot
+resolve a saved catalog default. `multimode` and `node generate` require an
+explicit NovelAI provider or model whenever NAI-native flags are used; `gen`
+can use a persisted NovelAI CLI default.
+
+NovelAI V5 officially supports English and Japanese prompts. Natural language
+and tags both work; quote text that should appear in the image, and use tags such
+as `transparent background`, `has alpha`, or `alpha transparency` with the alpha
+flag. Other languages may work but are not the officially supported prompt pair.
+
+Do not assume a generation costs no Anlas. Check the current account and usage
+limit. The no-Anlas Opus conditions include one image, no base or source image,
+a normal resolution up to 1024x1024, and at most 28 steps; V5 usage limits can
+still apply.
+
+The ima2 NovelAI lane is text-to-image only. NovelAI itself has additional product
+features, but ima2 does not currently expose reference/img2img, masks/inpainting,
+Character Positioning, Director Reference, Vibe Transfer, or Max Enhance.
+References, edits, and masks fail closed with `NAI_REF_UNSUPPORTED`,
+`NAI_EDIT_UNSUPPORTED`, or `NAI_MASK_UNSUPPORTED` rather than being dropped.
+
+Primary product references, checked 2026-08-27: the official
+[NovelAI V5 release](https://journal.novelai.net/image-generation-novelai-diffusion-v5-is-here-c2df7c6b8d2d/)
+and [NovelAI subscription documentation](https://docs.novelai.net/en/subscription/).
+Native control details come from the official
+[sampling](https://docs.novelai.net/en/image/sampling/),
+[steps and guidance](https://docs.novelai.net/en/image/stepsguidance/),
+[quality tags](https://docs.novelai.net/en/image/qualitytags/), and
+[seed](https://docs.novelai.net/en/image/seed/) pages, checked the same date.
+
 ## Prompting Guidance
 
 GPT Image 2 can follow detailed visual instructions and can render visible text