@mrgoonie/multix 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.7](https://github.com/mrgoonie/multix-cli/compare/v1.0.6...v1.0.7) (2026-10-11)
+
+
+### Fixed
+
+* **core:** let a later .env file fill a blank value ([#129](https://github.com/mrgoonie/multix-cli/issues/129)) ([bdfb673](https://github.com/mrgoonie/multix-cli/commit/bdfb6739770f0e7bb9d2623606cdb32d454779d4))
+
+## [1.0.6](https://github.com/mrgoonie/multix-cli/compare/v1.0.5...v1.0.6) (2026-10-11)
+
+
+### Fixed
+
+* **providers:** read model defaults after loading .env files ([#121](https://github.com/mrgoonie/multix-cli/issues/121)) ([5f36dba](https://github.com/mrgoonie/multix-cli/commit/5f36dba0fc7a1ccbe3d904e928c4ef82b3c6ce36))
+
 ## [1.0.5](https://github.com/mrgoonie/multix-cli/compare/v1.0.4...v1.0.5) (2026-10-11)
 
 

package/README.md

@@ -115,7 +115,7 @@ Set at least one provider key. Add to `.env` in your project root or `~/.multix/
 
 Set extra keys as `GEMINI_API_KEY_2`, `GEMINI_API_KEY_3`, … (any numeric suffix; numbered keys alone are enough). `multix` tries `GEMINI_API_KEY` first, then the numbered keys in ascending order, skipping duplicates. When a key returns HTTP 429 (or 400/403 with `RESOURCE_EXHAUSTED`), it cools down for the server's `Retry-After`/`retryDelay` (default 60s) and the same request is retried with the next ready key; other errors are not rotated. A Files API upload is repeated on the new key if the following generate call is rate-limited. Veo rotates on submit only, so a rate limit while polling or downloading never starts a second billed job. `doc convert` stops its own retries on a rate limit. Cooldowns last for the current process only, and logs name the env var, never the key. `multix check` lists the keys in rotation and pings each one. Quotas are per Google Cloud project: keys from the same project share one quota, so rotation only helps across projects.
 
-Priority: `process.env` > `cwd/.env` > `~/.multix/.env`. Set `MULTIX_LEGACY_CLAUDE_ENV=1` (shell or `~/.multix/.env`) to also read legacy AgentKit files (`.claude/skills/{ai-multimodal,ak-ai-multimodal}/.env`, `.claude/skills/.env`, `.claude/.env`, project first, then home) with the lowest priority (credential names only, never endpoint/proxy settings); `multix check -v` lists the env files that were loaded.
+Priority: `process.env` > `cwd/.env` > `~/.multix/.env`. A blank or whitespace-only value in a `.env` file does not count as set, so a project `.env` copied from `.env.example` does not hide `~/.multix/.env`; a shell variable wins even when blank. Set `MULTIX_LEGACY_CLAUDE_ENV=1` (shell or `~/.multix/.env`) to also read legacy AgentKit files (`.claude/skills/{ai-multimodal,ak-ai-multimodal}/.env`, `.claude/skills/.env`, `.claude/.env`, project first, then home) with the lowest priority (credential names only, never endpoint/proxy settings); `multix check -v` lists the env files that were loaded.
 
 A project `.env` may only set variables `multix` reads: provider keys, the provider settings in `.env.example` (`*_BASE_URL`, model overrides, Cloudflare IDs), the documented `MULTIX_*` settings (`MULTIX_OUTPUT_DIR`, so a project can choose where outputs go, `MULTIX_IMAGE_FORMAT`, `MULTIX_MAX_DOWNLOAD_MB`, `MULTIX_UPLOAD_MIN_KBPS`) and `NO_COLOR`. The opt-ins `MULTIX_ALLOW_PROJECT_BASE_URL` and `MULTIX_LEGACY_CLAUDE_ENV` are refused there; set them in the shell or `~/.multix/.env`. Other names, such as `NODE_OPTIONS`, `npm_config_registry`, `LD_PRELOAD` or `HTTPS_PROXY`, are not loaded, so they never reach `multix` or the tools it starts (`npm` in `multix update`, ffmpeg, ImageMagick, cwebp); one warning on stderr lists the ignored names, never their values. The shell and `~/.multix/.env` are not filtered.
 

package/dist/cli.js

@@ -402,6 +402,12 @@ function parseFile(file) {
     return void 0;
   }
 }
+function fileMaySet(name, value) {
+  const current = process.env[name];
+  if (current === void 0) return true;
+  if (current.trim() !== "" || value.trim() === "") return false;
+  return fileOrigins.get(envNameKey(name))?.value === current;
+}
 function loadFile(file, source, accept = () => true, onRefused) {
   const parsed = parseFile(file);
   if (!parsed) return void 0;
@@ -410,7 +416,7 @@ function loadFile(file, source, accept = () => true, onRefused) {
       onRefused?.(name);
       continue;
     }
-    if (process.env[name] !== void 0) continue;
+    if (!fileMaySet(name, value)) continue;
     process.env[name] = value;
     fileOrigins.set(envNameKey(name), { source, file, value });
   }
@@ -495,10 +501,8 @@ function inspectTrustedSetting(name, credentials, harmless) {
   if (origin?.source !== "project") {
     return value ? { status: "used", value, source: origin?.source ?? "shell" } : { status: "unset" };
   }
+  if (value === void 0) return { status: "unset" };
   const userValue = userFileValues[envNameKey(name)]?.trim() || void 0;
-  if (value === void 0) {
-    return userValue ? { status: "fallback", value: userValue, file: origin.file, reason: "it is empty" } : { status: "unset" };
-  }
   const project = (basis) => ({
     status: "used",
     value,
@@ -518,10 +522,9 @@ function applyTrustedSetting(name, state) {
   if (state.status === "unset") return void 0;
   if (state.status === "used") return state.value;
   if (state.status === "refused") throw new ConfigError(trustedSettingRefusal(name, state));
-  const hint = state.reason === "it is empty" ? "" : ` ${OPT_IN_HINT}`;
   warnOnce(
     `ignored:${name}`,
-    `Ignoring ${name} from project env file ${state.file} (${state.reason}); using the value from ~/.multix/.env.${hint}`
+    `Ignoring ${name} from project env file ${state.file} (${state.reason}); using the value from ~/.multix/.env. ${OPT_IN_HINT}`
   );
   return state.value;
 }
@@ -3006,6 +3009,11 @@ async function poll(opts) {
 // src/providers/byteplus/client.ts
 init_errors();
 
+// src/core/env-default.ts
+function envDefault(name, fallback) {
+  return process.env[name]?.trim() || fallback;
+}
+
 // src/providers/byteplus/models.ts
 var DEFAULT_BYTEPLUS_BASE_URL = "https://ark.ap-southeast.bytepluses.com/api/v3";
 var BYTEPLUS_ROUTING = {
@@ -3021,9 +3029,15 @@ var BYTEPLUS_3D_MODELS = [
   { id: "hitem3d-2-0-251223", name: "Hitem3d 2.0", family: "hitem3d" }
 ];
 var BYTEPLUS_DEFAULTS = {
-  imageModel: process.env.BYTEPLUS_IMAGE_MODEL ?? DEFAULT_BYTEPLUS_IMAGE_MODEL,
-  videoModel: process.env.BYTEPLUS_VIDEO_MODEL ?? DEFAULT_BYTEPLUS_VIDEO_MODEL,
-  threeDModel: process.env.BYTEPLUS_3D_MODEL ?? DEFAULT_BYTEPLUS_3D_MODEL,
+  get imageModel() {
+    return envDefault("BYTEPLUS_IMAGE_MODEL", DEFAULT_BYTEPLUS_IMAGE_MODEL);
+  },
+  get videoModel() {
+    return envDefault("BYTEPLUS_VIDEO_MODEL", DEFAULT_BYTEPLUS_VIDEO_MODEL);
+  },
+  get threeDModel() {
+    return envDefault("BYTEPLUS_3D_MODEL", DEFAULT_BYTEPLUS_3D_MODEL);
+  },
   videoResolution: "1080p",
   videoDuration: 8,
   videoAspectRatio: "16:9",
@@ -3838,7 +3852,7 @@ var CLOUDFLARE_VIDEO_CREDENTIALS = [
 function getCloudflareModel(kind, requested) {
   const expected = kind === "image" ? CLOUDFLARE_IMAGE_MODEL : CLOUDFLARE_TTS_MODEL;
   const overrideName = kind === "image" ? "CLOUDFLARE_AI_IMAGE_MODEL" : "CLOUDFLARE_AI_TTS_MODEL";
-  const model = requested ?? resolveKey(overrideName) ?? expected;
+  const model = requested ?? envDefault(overrideName, expected);
   if (model !== expected) {
     throw new ValidationError(`Unsupported Cloudflare ${kind} model: ${model}`);
   }
@@ -5024,11 +5038,17 @@ var FAL_ROUTING = {
 };
 var FAL_DEFAULTS = {
   // FLUX.1 [schnell] — fast, low-cost default text-to-image model.
-  imageModel: process.env.FAL_IMAGE_MODEL ?? "fal-ai/flux/schnell",
+  get imageModel() {
+    return envDefault("FAL_IMAGE_MODEL", "fal-ai/flux/schnell");
+  },
   // Stable, widely available default text-to-video model.
-  videoModel: process.env.FAL_VIDEO_MODEL ?? "fal-ai/kling-video/v1.6/standard/text-to-video",
+  get videoModel() {
+    return envDefault("FAL_VIDEO_MODEL", "fal-ai/kling-video/v1.6/standard/text-to-video");
+  },
   // Matching image-to-video model — used when --image-url is passed without -m.
-  videoImageModel: process.env.FAL_VIDEO_IMAGE_MODEL ?? "fal-ai/kling-video/v1.6/standard/image-to-video"
+  get videoImageModel() {
+    return envDefault("FAL_VIDEO_IMAGE_MODEL", "fal-ai/kling-video/v1.6/standard/image-to-video");
+  }
 };
 
 // src/providers/fal/run-helpers.ts
@@ -6098,15 +6118,15 @@ var ASPECT_RATIOS = [
 var IMAGE_SIZES = ["1K", "2K", "4K"];
 function getDefaultModel(task) {
   if (task === "generate") {
-    return process.env.IMAGE_GEN_MODEL ?? process.env.GEMINI_IMAGE_GEN_MODEL ?? IMAGE_MODEL_DEFAULT;
+    return envDefault("IMAGE_GEN_MODEL", envDefault("GEMINI_IMAGE_GEN_MODEL", IMAGE_MODEL_DEFAULT));
   }
   if (task === "generate-video") {
-    return process.env.VIDEO_GEN_MODEL ?? VIDEO_MODEL_DEFAULT;
+    return envDefault("VIDEO_GEN_MODEL", VIDEO_MODEL_DEFAULT);
   }
   if (task === "generate-speech") {
-    return process.env.GEMINI_TTS_MODEL ?? process.env.TTS_MODEL ?? TTS_MODEL_DEFAULT;
+    return envDefault("GEMINI_TTS_MODEL", envDefault("TTS_MODEL", TTS_MODEL_DEFAULT));
   }
-  return process.env.MULTIMODAL_MODEL ?? process.env.GEMINI_MODEL ?? ANALYSIS_MODEL_DEFAULT;
+  return envDefault("MULTIMODAL_MODEL", envDefault("GEMINI_MODEL", ANALYSIS_MODEL_DEFAULT));
 }
 
 // src/providers/gemini/result-formatter.ts
@@ -8969,8 +8989,12 @@ var LEONARDO_ROUTING = {
 };
 var DEFAULT_LEONARDO_MODEL_ID = "7b592283-e8a7-4c5a-9ba6-d18c31f258b9";
 var LEONARDO_DEFAULTS = {
-  modelId: process.env.LEONARDO_DEFAULT_MODEL ?? DEFAULT_LEONARDO_MODEL_ID,
-  videoModel: process.env.LEONARDO_VIDEO_MODEL ?? "MOTION2",
+  get modelId() {
+    return envDefault("LEONARDO_DEFAULT_MODEL", DEFAULT_LEONARDO_MODEL_ID);
+  },
+  get videoModel() {
+    return envDefault("LEONARDO_VIDEO_MODEL", "MOTION2");
+  },
   width: 1024,
   height: 1024,
   numImages: 1
@@ -9819,10 +9843,18 @@ var ALL_MINIMAX_MODELS = /* @__PURE__ */ new Set([
   ...MINIMAX_MUSIC_MODELS
 ]);
 var TASK_DEFAULTS2 = {
-  image: process.env.MINIMAX_IMAGE_MODEL ?? "image-01",
-  video: process.env.MINIMAX_VIDEO_MODEL ?? "MiniMax-Hailuo-2.3",
-  speech: process.env.MINIMAX_SPEECH_MODEL ?? "speech-2.8-hd",
-  music: process.env.MINIMAX_MUSIC_MODEL ?? "music-2.5"
+  get image() {
+    return envDefault("MINIMAX_IMAGE_MODEL", "image-01");
+  },
+  get video() {
+    return envDefault("MINIMAX_VIDEO_MODEL", "MiniMax-Hailuo-2.3");
+  },
+  get speech() {
+    return envDefault("MINIMAX_SPEECH_MODEL", "speech-2.8-hd");
+  },
+  get music() {
+    return envDefault("MINIMAX_MUSIC_MODEL", "music-2.5");
+  }
 };
 var VIDEO_DURATIONS = [6, 10];
 var VIDEO_RESOLUTIONS = ["720P", "1080P"];
@@ -10548,7 +10580,7 @@ async function transcribeOpenAIAudio(opts) {
 
 // src/providers/openai/commands/generate-speech.ts
 function registerOpenAIGenerateSpeechCommand(parent) {
-  parent.command("generate-speech").description("Generate speech with OpenAI TTS").option("--text <str>", "Text to speak").option("--prompt <str>", "Alias for --text").option("--model <id>", "TTS model", process.env.OPENAI_TTS_MODEL ?? DEFAULT_OPENAI_TTS_MODEL).option("--voice <name>", "OpenAI voice", "marin").option("--instructions <text>", "Voice/style instructions").option("--output-format <fmt>", "mp3|opus|aac|flac|wav|pcm", "mp3").option("--output <path>", "Copy generated audio to this path").option("-v, --verbose", "Verbose logging").action(async (opts) => {
+  parent.command("generate-speech").description("Generate speech with OpenAI TTS").option("--text <str>", "Text to speak").option("--prompt <str>", "Alias for --text").option("--model <id>", "TTS model", envDefault("OPENAI_TTS_MODEL", DEFAULT_OPENAI_TTS_MODEL)).option("--voice <name>", "OpenAI voice", "marin").option("--instructions <text>", "Voice/style instructions").option("--output-format <fmt>", "mp3|opus|aac|flac|wav|pcm", "mp3").option("--output <path>", "Copy generated audio to this path").option("-v, --verbose", "Verbose logging").action(async (opts) => {
     const text = opts.text ?? opts.prompt;
     if (!text) throw new ValidationError("Either --text or --prompt is required");
     validateTtsVoice(opts.voice);
@@ -10777,7 +10809,7 @@ function registerOpenAIGenerateCommand(parent) {
   parent.command("generate").description("Generate images with OpenAI Image API or experimental Codex driver").requiredOption("--prompt <text>", "Text prompt").option("--driver <driver>", "api|codex|auto", "auto").option(
     "-m, --model <id>",
     "Image model",
-    resolveKey("OPENAI_IMAGE_MODEL") ?? DEFAULT_OPENAI_IMAGE_MODEL
+    envDefault("OPENAI_IMAGE_MODEL", DEFAULT_OPENAI_IMAGE_MODEL)
   ).option("--size <size>", "1024x1024|1024x1536|1536x1024|auto", "1024x1024").option("--quality <q>", "low|medium|high", "medium").option(
     "--format <fmt>",
     "Provider output format png|jpeg|webp (explicit value keeps it; default png then WebP)"
@@ -10823,7 +10855,7 @@ function registerOpenAIImageToImageCommand(parent) {
   ).option("--driver <driver>", "api|codex|auto", "auto").option(
     "-m, --model <id>",
     "Image model",
-    resolveKey("OPENAI_IMAGE_MODEL") ?? DEFAULT_OPENAI_IMAGE_MODEL
+    envDefault("OPENAI_IMAGE_MODEL", DEFAULT_OPENAI_IMAGE_MODEL)
   ).option("--size <size>", "1024x1024|1024x1536|1536x1024|auto", "1024x1024").option("--quality <q>", "low|medium|high", "medium").option(
     "--format <fmt>",
     "Provider output format png|jpeg|webp (explicit value keeps it; default png then WebP)"
@@ -10867,7 +10899,7 @@ function collect6(value, prev) {
 
 // src/providers/openai/commands/transcribe.ts
 function registerOpenAITranscribeCommand(parent) {
-  parent.command("transcribe").description("Transcribe audio/video with OpenAI STT").requiredOption("--input <path>", "Audio or video file").option("--model <id>", "STT model", process.env.OPENAI_STT_MODEL ?? DEFAULT_OPENAI_STT_MODEL).option("--format <fmt>", "json|text|diarized_json", "text").option("--language <code>", "ISO language code").option("--chunking-strategy <strategy>", "e.g. auto").option(
+  parent.command("transcribe").description("Transcribe audio/video with OpenAI STT").requiredOption("--input <path>", "Audio or video file").option("--model <id>", "STT model", envDefault("OPENAI_STT_MODEL", DEFAULT_OPENAI_STT_MODEL)).option("--format <fmt>", "json|text|diarized_json", "text").option("--language <code>", "ISO language code").option("--chunking-strategy <strategy>", "e.g. auto").option(
     "--known-speaker-name <name>",
     "Known speaker name; repeatable",
     collect7,
@@ -11100,7 +11132,7 @@ function registerOpenRouterGenerateCommand(parent) {
   ).requiredOption("--prompt <text>", "Image generation prompt").option("--model <id>", "OpenRouter model id (e.g. google/gemini-3.1-flash-image-preview)").option("--aspect-ratio <ratio>", "Aspect ratio (e.g. 1:1, 16:9)", "1:1").option("--image-size <size>", "Image size hint (e.g. 1K, 2K)").option("--num-images <n>", "Number of images to generate", "1").option("--output <path>", "Copy first image to this path").addOption(imageFormatOption()).addOption(noWebpOption()).option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
-      const model = opts.model ?? resolveKey("OPENROUTER_IMAGE_MODEL") ?? DEFAULT_OPENROUTER_MODEL;
+      const model = opts.model ?? envDefault("OPENROUTER_IMAGE_MODEL", DEFAULT_OPENROUTER_MODEL);
       const numImages = Math.max(1, Number.parseInt(opts.numImages, 10) || 1);
       logger.debug(`Generating ${numImages} image(s) via OpenRouter: ${model}`);
       const result = await generateOpenRouterImage({
@@ -11149,7 +11181,7 @@ function registerOpenRouterImageToImageCommand(parent) {
         throw new ValidationError("At least one --ref is required for image-to-image.");
       }
       const logger = createLogger({ verbose: opts.verbose ?? false });
-      const model = opts.model ?? resolveKey("OPENROUTER_IMAGE_MODEL") ?? DEFAULT_MODEL;
+      const model = opts.model ?? envDefault("OPENROUTER_IMAGE_MODEL", DEFAULT_MODEL);
       const strength = parseStrength(opts.strength);
       const fallbackModels = (resolveKey("OPENROUTER_FALLBACK_MODELS") ?? "").split(",").map((m) => m.trim()).filter(Boolean);
       const resolvedRefs = [];
@@ -11365,7 +11397,7 @@ function registerOpenRouterImageToVideoCommand(parent) {
   ).requiredOption("--prompt <text>", "Motion/scene prompt").requiredOption("--image-url <url>", "First-frame image URL (https)").option("--last-frame-url <url>", "Optional last-frame image URL").option("--model <id>", "OpenRouter video model id (e.g. google/veo-3.1)").option("--resolution <r>", "Resolution hint (e.g. 720p, 1080p)").option("--aspect-ratio <r>", "Aspect ratio hint (e.g. 16:9, 9:16)").option("--duration <n>", "Duration seconds").option("--seed <n>", "Fixed seed").option("--wait", "Poll until status is 'completed' or 'failed'").option("--wait-timeout <ms>", "Poll timeout in ms (with --wait)", "600000").option("--download", "Download the generated video on success (implies --wait)").option("--output <path>", "Copy downloaded video to this path").option("--no-thumb", "Skip downloading the thumbnail if the API returns one").option("-v, --verbose", "Verbose logging").action(
     async (opts) => {
       const logger = createLogger({ verbose: opts.verbose ?? false });
-      const model = opts.model ?? resolveKey("OPENROUTER_VIDEO_MODEL") ?? "google/veo-3.1";
+      const model = opts.model ?? envDefault("OPENROUTER_VIDEO_MODEL", "google/veo-3.1");
       const frame_images = [
         {
           type: "image_url",
@@ -12602,8 +12634,10 @@ function settingLine(label, state, commands = "commands that use it") {
   if (state.status === "used") {
     return { level: "info", message: `${label} in effect (from ${usedFrom(state)})` };
   }
-  const why = state.reason === "it is empty" ? "set empty in project .env" : `set in project .env while ${state.reason}`;
-  return { level: "warn", message: `${label} ignored: ${why}; using ~/.multix/.env` };
+  return {
+    level: "warn",
+    message: `${label} ignored: set in project .env while ${state.reason}; using ~/.multix/.env`
+  };
 }
 var sameState = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 function routingSettingReport() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrgoonie/multix",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "AI multimodal CLI — OpenAI, Gemini, MiniMax, OpenRouter, Leonardo, BytePlus, ElevenLabs, fal.ai, Atlas Cloud, Replicate, HeyGen, ffmpeg, ImageMagick, doc-to-md",
   "type": "module",
   "bin": {
@@ -81,7 +81,6 @@
     "commander": "^12.1.0",
     "dotenv": "^16.4.5",
     "execa": "^9.4.0",
-    "undici": "^7.2.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {

package/skill/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: multix
 description: AI multimodal CLI — generate and edit images (OpenAI, Codex driver, Gemini Nano Banana, Imagen, MiniMax, OpenRouter, Leonardo, BytePlus Seedream, Cloudflare Workers AI FLUX.1 Schnell, fal.ai FLUX, Replicate FLUX), generate video (Gemini Veo, MiniMax Hailuo, OpenRouter via Veo/Seedance/Kling, Leonardo via Motion/Veo/Kling/Hailuo/Seedance/LTX, BytePlus Seedance, Cloudflare AI Gateway via Replicate, fal.ai queue models, Replicate direct API models incl. P-Video, HeyGen Video Agent and scripted avatar videos), video translation and lipsync (HeyGen), TTS/STT/music (OpenAI, Gemini Flash TTS incl. Gemini 3.8 with delivery-style control, MiniMax, Cloudflare Workers AI MeloTTS, ElevenLabs), 3D models (BytePlus Hyper3D/Hitem3d), analyze/transcribe media, convert documents to Markdown, optimize media via ffmpeg/ImageMagick, and self-update the CLI. Use whenever the user wants to create, edit, or transform images/video/audio/3D/documents from a CLI, mentions any of: OpenAI, Codex image driver, image-to-image, i2i, image edit, watercolor/cyberpunk style transfer, reference image, OpenRouter, Nano Banana, Flux, Seedream, Veo, Hailuo, Seedance, Kling, Cloudflare Workers AI, AI Gateway, fal.ai, Atlas Cloud, Replicate, replicate.com models, Replicate predictions, HeyGen, avatar video, talking head, Video Agent, video translation, dubbing, lipsync, video generation, text-to-video, image-to-video, i2v, ElevenLabs voice cloning, updating/upgrading multix, or asks for batch media optimization.
-version: 1.0.5 # x-release-please-version
+version: 1.0.7 # x-release-please-version
 ---
 
 # multix — AI Multimodal CLI
@@ -54,7 +54,7 @@ CLOUDFLARE_API_TOKEN  # Cloudflare Workers AI / AI Gateway token
 # Video additionally requires CLOUDFLARE_AI_GATEWAY_ID and REPLICATE_API_TOKEN.
 ```
 
-Priority: `process.env` > `cwd/.env` > `~/.multix/.env`. Set `MULTIX_LEGACY_CLAUDE_ENV=1` to also read legacy AgentKit `.claude` env files (credential names only, lowest priority); `multix check -v` lists loaded env files. A project `.env` may only set names multix reads (provider keys and settings from `.env.example`, the documented `MULTIX_*` settings such as `MULTIX_OUTPUT_DIR`, `NO_COLOR`; never `MULTIX_ALLOW_PROJECT_BASE_URL` or `MULTIX_LEGACY_CLAUDE_ENV`); anything else there (`NODE_OPTIONS`, `npm_config_*`, `LD_PRELOAD`, proxy/TLS variables) is not loaded, with one stderr warning naming the ignored variables. Put such variables in the shell.
+Priority: `process.env` > `cwd/.env` > `~/.multix/.env`; a blank value in a `.env` file does not count as set, so a later file can fill it (a shell value wins even when blank). Set `MULTIX_LEGACY_CLAUDE_ENV=1` to also read legacy AgentKit `.claude` env files (credential names only, lowest priority); `multix check -v` lists loaded env files. A project `.env` may only set names multix reads (provider keys and settings from `.env.example`, the documented `MULTIX_*` settings such as `MULTIX_OUTPUT_DIR`, `NO_COLOR`; never `MULTIX_ALLOW_PROJECT_BASE_URL` or `MULTIX_LEGACY_CLAUDE_ENV`); anything else there (`NODE_OPTIONS`, `npm_config_*`, `LD_PRELOAD`, proxy/TLS variables) is not loaded, with one stderr warning naming the ignored variables. Put such variables in the shell.
 
 ## Gemini text-output tasks