volute 0.49.0 → 0.51.0

package/dist/{schema-6YONVTKZ.js → schema-ZZQVM4GR.js}

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   activity,
+  apiTokens,
   channelGates,
   channels,
   conversationParticipants,
@@ -9,18 +10,19 @@ import {
   deliveryQueue,
   messages,
   mindHistory,
-  mindNotices,
   minds,
   sessions,
   sharedSkills,
   summaries,
+  systemEvents,
   systemPrompts,
   turns,
   users
-} from "./chunk-P4LHVRNE.js";
+} from "./chunk-2RNMBXD2.js";
 import "./chunk-K3NQKI34.js";
 export {
   activity,
+  apiTokens,
   channelGates,
   channels,
   conversationParticipants,
@@ -29,11 +31,11 @@ export {
   deliveryQueue,
   messages,
   mindHistory,
-  mindNotices,
   minds,
   sessions,
   sharedSkills,
   summaries,
+  systemEvents,
   systemPrompts,
   turns,
   users

package/dist/{seed-NQED7PSX.js → seed-K2LYODIH.js}

@@ -4,7 +4,7 @@ import "./chunk-K3NQKI34.js";
 // packages/cli/src/commands/seed.ts
 async function run(args) {
   console.error("Note: `volute mind seed` is now `volute seed create`");
-  await import("./seed-create-XOO4N2OE.js").then((m) => m.run(args));
+  await import("./seed-create-VGTLU5FD.js").then((m) => m.run(args));
 }
 export {
   run

package/dist/{seed-check-TYD7RRZY.js → seed-check-NRJEQZST.js}

@@ -10,14 +10,21 @@ var cmd = command({
   name: "volute seed check",
   description: "Check seed readiness",
   args: [{ name: "name", required: true, description: "Seed mind to check" }],
-  flags: {},
-  run: async ({ args }) => {
+  flags: {
+    nurture: {
+      type: "boolean",
+      description: "Apply the nurture gate (used by the spirit's schedule): stay silent when no nudge is needed"
+    }
+  },
+  run: async ({ args, flags }) => {
     const name = args.name;
-    const { daemonFetch } = await import("./daemon-client-ZFY5MOAL.js");
-    const res = await daemonFetch(`/api/minds/${encodeURIComponent(name)}/seed-check`);
+    const query = flags.nurture ? "" : "?force=1";
+    const { daemonFetch } = await import("./daemon-client-VVYFZI2D.js");
+    const res = await daemonFetch(`/api/minds/${encodeURIComponent(name)}/seed-check${query}`);
     if (!res.ok) {
+      process.exitCode = 1;
       if (res.status === 404) {
-        console.log(`Seed "${name}" not found \u2014 it may have been deleted or already sprouted.`);
+        console.error(`Seed "${name}" not found \u2014 it may have been deleted.`);
       } else {
         console.error(`seed check failed for ${name}: HTTP ${res.status}`);
       }
@@ -26,6 +33,8 @@ var cmd = command({
     const data = await res.json();
     if (data.output) {
       console.log(data.output);
+    } else if (!flags.nurture) {
+      console.log(`No readiness output returned for ${name}.`);
     }
   }
 });

package/dist/{seed-cmd-QF3F2G4S.js → seed-cmd-2EWBTR6P.js}

@@ -12,15 +12,15 @@ var cmd = subcommands({
   commands: {
     create: {
       description: "Plant a new seed",
-      run: (args) => import("./seed-create-XOO4N2OE.js").then((m) => m.run(args))
+      run: (args) => import("./seed-create-VGTLU5FD.js").then((m) => m.run(args))
     },
     sprout: {
       description: "Complete orientation and become a full mind",
-      run: (args) => import("./seed-sprout-HSBBGSS2.js").then((m) => m.run(args))
+      run: (args) => import("./seed-sprout-PILHJ3YS.js").then((m) => m.run(args))
     },
     check: {
       description: "Check seed readiness",
-      run: (args) => import("./seed-check-TYD7RRZY.js").then((m) => m.run(args))
+      run: (args) => import("./seed-check-NRJEQZST.js").then((m) => m.run(args))
     }
   }
 });

package/dist/{seed-create-XOO4N2OE.js → seed-create-VGTLU5FD.js}

@@ -47,19 +47,19 @@ var cmd = command({
     const name = args.name;
     const skills = flags.skills === "none" ? [] : flags.skills ? flags.skills.split(",") : void 0;
     const createdBy = flags["created-by"];
-    const { daemonFetch } = await import("./daemon-client-ZFY5MOAL.js");
+    const { daemonFetch } = await import("./daemon-client-VVYFZI2D.js");
     const { getClient, urlOf } = await import("./api-client-LC5YRA32.js");
     const client = getClient();
     let model = flags.model;
     let template = flags.template;
     if (!template) {
-      const { resolveTemplate } = await import("./ai-service-A7FS7EC3.js");
+      const { resolveTemplate } = await import("./ai-service-YW5SWCSB.js");
       template = await resolveTemplate(model);
     }
     if (template !== "claude" && !model) {
       if (process.env.VOLUTE_MIND || !process.stdin.isTTY) {
-        const { getSpiritModel } = await import("./spirit-SSJMYC6A.js");
-        const { qualifyModelId } = await import("./ai-service-A7FS7EC3.js");
+        const { getSpiritModel } = await import("./spirit-25JVAL3M.js");
+        const { qualifyModelId } = await import("./ai-service-YW5SWCSB.js");
         const spiritModel = getSpiritModel();
         if (spiritModel) {
           model = template === "pi" ? qualifyModelId(spiritModel) : spiritModel;

package/dist/{seed-readiness-3LRYASA4.js → seed-readiness-DYOVCYHN.js}

@@ -3,13 +3,12 @@ import {
   evaluateSeedChecklist,
   isMemoryWritten,
   isSoulWritten
-} from "./chunk-TXJL36ZQ.js";
-import "./chunk-JPGHSXSV.js";
+} from "./chunk-JHKBALS2.js";
+import "./chunk-FXWBFDQR.js";
 import "./chunk-DW4TRDOZ.js";
 import "./chunk-WCFSBH33.js";
-import "./chunk-NJHN6IRB.js";
-import "./chunk-RSBL3FAD.js";
-import "./chunk-P4LHVRNE.js";
+import "./chunk-H6X6CKDN.js";
+import "./chunk-2RNMBXD2.js";
 import "./chunk-K3NQKI34.js";
 export {
   evaluateSeedChecklist,

package/dist/{seed-sprout-HSBBGSS2.js → seed-sprout-PILHJ3YS.js}

@@ -1,27 +1,27 @@
 #!/usr/bin/env node
 import {
   daemonFetch
-} from "./chunk-BCG45AQB.js";
+} from "./chunk-M74I3HHF.js";
 import {
   command
 } from "./chunk-TXSA4Q3V.js";
 import "./chunk-O7IGP7ZW.js";
+import "./chunk-FNJCBRD3.js";
 import {
   evaluateSeedChecklist
-} from "./chunk-TXJL36ZQ.js";
+} from "./chunk-JHKBALS2.js";
 import {
   getStandardSkillsWithExtensions
-} from "./chunk-GWVFDUNB.js";
-import "./chunk-JPGHSXSV.js";
+} from "./chunk-QT4D5XCI.js";
+import "./chunk-FXWBFDQR.js";
 import "./chunk-DW4TRDOZ.js";
 import "./chunk-WCFSBH33.js";
-import "./chunk-DVN6DNMI.js";
-import "./chunk-NJHN6IRB.js";
+import "./chunk-M77B73VV.js";
 import "./chunk-QUSMYGNQ.js";
 import {
   mindDir
-} from "./chunk-RSBL3FAD.js";
-import "./chunk-P4LHVRNE.js";
+} from "./chunk-H6X6CKDN.js";
+import "./chunk-2RNMBXD2.js";
 import "./chunk-K3NQKI34.js";
 
 // packages/cli/src/commands/seed-sprout.ts
@@ -74,7 +74,7 @@ var cmd = command({
       process.exit(1);
     }
     const { getClient, urlOf } = await import("./api-client-LC5YRA32.js");
-    const { mindSkillsDir } = await import("./skills-NN5UZCUU.js");
+    const { mindSkillsDir } = await import("./skills-NH2GQKAF.js");
     const client = getClient();
     const failedSkills = [];
     for (const skillId of getStandardSkillsWithExtensions()) {

package/dist/{send-IHRJYNXA.js → send-2YKOZJJ5.js}

@@ -4,10 +4,10 @@ import {
 } from "./chunk-33ODGMFZ.js";
 import {
   isCompact
-} from "./chunk-5T5YMX6S.js";
+} from "./chunk-7YJY3F2R.js";
 import {
   daemonFetch
-} from "./chunk-BCG45AQB.js";
+} from "./chunk-M74I3HHF.js";
 import {
   getClient,
   urlOf
@@ -16,11 +16,12 @@ import {
   command
 } from "./chunk-TXSA4Q3V.js";
 import "./chunk-O7IGP7ZW.js";
+import "./chunk-FNJCBRD3.js";
 import {
   formatFileSize
-} from "./chunk-NOIAHMJB.js";
-import "./chunk-RSBL3FAD.js";
-import "./chunk-P4LHVRNE.js";
+} from "./chunk-DMK5ASKV.js";
+import "./chunk-H6X6CKDN.js";
+import "./chunk-2RNMBXD2.js";
 import "./chunk-K3NQKI34.js";
 
 // packages/cli/src/commands/send.ts
@@ -154,6 +155,18 @@ async function waitForResponse(mindName, conversationId, timeoutMs) {
     });
   }
 }
+function spiritAck(spirit) {
+  switch (spirit) {
+    case "waking":
+      return "The system spirit is waking \u2014 a reply is on its way.";
+    case "sleeping":
+      return "The system spirit is sleeping \u2014 it will reply when it wakes.";
+    case "unavailable":
+      return "The system spirit is unavailable \u2014 an admin can fix this in Settings.";
+    default:
+      return null;
+  }
+}
 function printSendResult(data) {
   if (data.held) {
     if (data.notice) console.log(data.notice);
@@ -166,6 +179,8 @@ function printSendResult(data) {
     console.log(`Message sent.${outboundId != null ? `
 [volute:outbound:${outboundId}]` : ""}`);
   }
+  const ack = spiritAck(data.spirit);
+  if (ack) console.log(ack);
 }
 var cmd = command({
   name: "volute chat send",
@@ -211,84 +226,108 @@ var cmd = command({
     }
     if (target === "system" || target === "@system") {
       console.error(
-        `Can't send to system \u2014 system messages are automated.
-To reply to a person, use their username from the message prefix (e.g. volute chat send @username "msg").`
+        `Can't send to system \u2014 system events come from your environment, not a person, and nothing is waiting on a reply.
+To reach a person, use their username from the message prefix (e.g. volute chat send @username "msg").`
       );
       process.exit(1);
     }
+    let parsed = parseTarget(target);
+    if (!parsed.isDM && parsed.platform === "volute" && await isMind(parsed.identifier)) {
+      parsed = {
+        platform: "volute",
+        identifier: `@${parsed.identifier}`,
+        uri: `@${parsed.identifier}`,
+        isDM: true
+      };
+    }
+    const dmTargetName = parsed.isDM && parsed.platform === "volute" ? parsed.identifier.slice(1) : void 0;
     if (flags.file) {
+      if (!dmTargetName || !await isMind(dmTargetName)) {
+        console.error(
+          `--file can only attach to a direct message to a mind \u2014 e.g.
+  volute chat send @mind "here you go" --file <path>
+Channels and non-mind recipients can't receive a file share.`
+        );
+        process.exit(1);
+      }
+      if (!message && images) {
+        console.error(
+          "Can't attach an image and a file without a message. Send the image with a message, or send the file on its own."
+        );
+        process.exit(1);
+      }
+    }
+    const stageAttachedFile = async (afterSend) => {
       const filePath = flags.file;
-      const parsed2 = parseTarget(target);
-      const targetName = parsed2.isDM && parsed2.platform === "volute" ? parsed2.identifier.slice(1) : parsed2.identifier;
+      const targetName = dmTargetName;
+      const failStaging = (reason) => {
+        console.error(
+          afterSend ? `Your message was delivered. Only the file failed: ${reason}
+Retry the attachment with:  volute chat send ${target} --file ${filePath} (no message) \u2014 sending the whole command again would duplicate the message.` : reason
+        );
+        process.exit(1);
+      };
+      const postStaging = async (path, body) => {
+        let res;
+        try {
+          res = await daemonFetch(path, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body)
+          });
+        } catch (err) {
+          return failStaging(`couldn't reach the daemon (${err.message})`);
+        }
+        if (!res.ok) {
+          const data2 = await res.json().catch(() => ({}));
+          return failStaging(data2.error ?? `daemon returned ${res.status}`);
+        }
+        const data = await res.json().catch(() => ({}));
+        return data.id ?? "?";
+      };
       const mindSelf = process.env.VOLUTE_MIND;
       if (mindSelf) {
-        const res = await daemonFetch(`/api/minds/${encodeURIComponent(mindSelf)}/files/send`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ targetMind: targetName, filePath })
+        const id = await postStaging(`/api/minds/${encodeURIComponent(mindSelf)}/files/send`, {
+          targetMind: targetName,
+          filePath
         });
-        if (!res.ok) {
-          const data2 = await res.json();
-          console.error(data2.error ?? `Failed to send file: ${res.status}`);
-          process.exit(1);
-        }
-        const data = await res.json();
-        console.log(`File staged for ${targetName} (id: ${data.id})`);
+        console.log(`File staged for ${targetName} (id: ${id})`);
       } else {
         if (!existsSync(filePath)) {
-          console.error(`File not found: ${filePath}`);
-          process.exit(1);
+          failStaging(`File not found: ${filePath}`);
         }
         const stat = statSync(filePath);
         const MAX_FILE_SIZE = 50 * 1024 * 1024;
         if (stat.size > MAX_FILE_SIZE) {
-          console.error(
+          failStaging(
             `File too large (${formatFileSize(stat.size)}, max ${formatFileSize(MAX_FILE_SIZE)})`
           );
-          process.exit(1);
         }
         const content = readFileSync(filePath);
-        const filename = basename(filePath);
-        const senderName = flags.sender || userInfo().username;
-        const res = await daemonFetch(`/api/minds/${encodeURIComponent(targetName)}/files/stage`, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({
-            sender: senderName,
-            filename,
-            data: content.toString("base64")
-          })
+        const id = await postStaging(`/api/minds/${encodeURIComponent(targetName)}/files/stage`, {
+          sender: flags.sender || userInfo().username,
+          filename: basename(filePath),
+          data: content.toString("base64")
         });
-        if (!res.ok) {
-          const data2 = await res.json();
-          console.error(data2.error ?? `Failed to stage file: ${res.status}`);
-          process.exit(1);
-        }
-        const data = await res.json();
-        console.log(`File staged for ${targetName} (id: ${data.id})`);
+        console.log(`File staged for ${targetName} (id: ${id})`);
       }
-      if (!message) return;
-    }
-    let parsed = parseTarget(target);
-    if (!parsed.isDM && parsed.platform === "volute" && await isMind(parsed.identifier)) {
-      parsed = {
-        platform: "volute",
-        identifier: `@${parsed.identifier}`,
-        uri: `@${parsed.identifier}`,
-        isDM: true
-      };
+    };
+    if (flags.file && !message) {
+      await stageAttachedFile(false);
+      return;
     }
     const client = getClient();
     let waitMindName;
     let waitConversationId;
     let heldResponse = false;
+    let spiritUnavailable = false;
     if (parsed.isDM && parsed.platform === "volute") {
       const targetName = parsed.identifier.slice(1);
       const mindSelf = process.env.VOLUTE_MIND;
       const sender = flags.sender || mindSelf || userInfo().username;
       if (mindSelf && targetName === mindSelf) {
         console.error(
-          `Can't send to @${targetName} \u2014 that's your own system channel. System messages there are automated notices; they don't need a reply.`
+          `Can't send to @${targetName} \u2014 that's yourself. System events arrive from your environment and don't need a reply.`
         );
         process.exit(1);
       }
@@ -334,7 +373,13 @@ To reply to a person, use their username from the message prefix (e.g. volute ch
         console.error(`Warning: could not read send response: ${err.message}`);
       }
       if (data.held) heldResponse = true;
-      if (data.held || !flags.wait) printSendResult(data);
+      if (data.held || !flags.wait || flags.file) {
+        printSendResult(data);
+      } else {
+        const ack = spiritAck(data.spirit);
+        if (ack) console.log(ack);
+      }
+      if (data.spirit === "unavailable") spiritUnavailable = true;
     } else if (!parsed.isDM && parsed.platform === "volute") {
       if (!parsed.identifier.startsWith("#")) {
         console.error(
@@ -391,7 +436,16 @@ See: volute chat bridge --help`
       );
       process.exit(1);
     }
-    if (heldResponse) {
+    if (flags.file) {
+      if (heldResponse) {
+        console.log(
+          "Your attached file was not staged \u2014 include --file <path> again when you re-send."
+        );
+      } else {
+        await stageAttachedFile(true);
+      }
+    }
+    if (heldResponse || spiritUnavailable) {
     } else if (flags.wait && waitMindName) {
       if (!waitConversationId) {
         console.error("--wait requires a volute conversation (DM to a mind)");

package/dist/{service-YCOPCTSZ.js → service-XQPMZAGI.js}

@@ -9,10 +9,10 @@ import {
   SYSTEM_LAUNCHD_PLIST_PATH,
   SYSTEM_SERVICE_PATH,
   USER_SYSTEMD_UNIT
-} from "./chunk-HCYQRME2.js";
-import "./chunk-DVN6DNMI.js";
-import "./chunk-RSBL3FAD.js";
-import "./chunk-P4LHVRNE.js";
+} from "./chunk-6NLW72HP.js";
+import "./chunk-M77B73VV.js";
+import "./chunk-H6X6CKDN.js";
+import "./chunk-2RNMBXD2.js";
 import "./chunk-K3NQKI34.js";
 
 // packages/cli/src/commands/service.ts

package/dist/{service-install-Y46OTF55.js → service-install-2EWD7KXD.js}

@@ -3,11 +3,11 @@ import {
   generateUserPlist,
   generateUserUnit,
   installUserService
-} from "./chunk-4B62E4CG.js";
-import "./chunk-HCYQRME2.js";
-import "./chunk-DVN6DNMI.js";
-import "./chunk-RSBL3FAD.js";
-import "./chunk-P4LHVRNE.js";
+} from "./chunk-OXWUEU5V.js";
+import "./chunk-6NLW72HP.js";
+import "./chunk-M77B73VV.js";
+import "./chunk-H6X6CKDN.js";
+import "./chunk-2RNMBXD2.js";
 import "./chunk-K3NQKI34.js";
 export {
   generateUserPlist,

package/dist/{setup-F4TE64YI.js → setup-MDPSK2XG.js}

@@ -8,22 +8,21 @@ import {
 import "./chunk-O7IGP7ZW.js";
 import {
   installUserService
-} from "./chunk-4B62E4CG.js";
+} from "./chunk-OXWUEU5V.js";
 import {
   LAUNCHD_PLIST_LABEL,
   SYSTEM_LAUNCHD_PLIST_PATH,
   SYSTEM_SERVICE_PATH
-} from "./chunk-HCYQRME2.js";
+} from "./chunk-6NLW72HP.js";
 import {
   ensureVoluteGroup,
   resolveVoluteBin
-} from "./chunk-DVN6DNMI.js";
+} from "./chunk-M77B73VV.js";
 import {
   readGlobalConfig,
   writeGlobalConfig
-} from "./chunk-NJHN6IRB.js";
-import "./chunk-RSBL3FAD.js";
-import "./chunk-P4LHVRNE.js";
+} from "./chunk-H6X6CKDN.js";
+import "./chunk-2RNMBXD2.js";
 import "./chunk-K3NQKI34.js";
 
 // src/commands/setup.ts
@@ -221,7 +220,7 @@ async function startDaemonAndOpenBrowser(port, host) {
   const url = `http://${displayHost === "0.0.0.0" || displayHost === "::" ? "localhost" : displayHost}:${displayPort}`;
   console.log("\nStarting daemon...");
   try {
-    const { run: runUp } = await import("./up-SDLTLPAO.js");
+    const { run: runUp } = await import("./up-J7XCAH7P.js");
     await runUp([
       ...port != null ? ["--port", String(port)] : [],
       ...host ? ["--host", host] : []

package/dist/{setup-TCN7VH5U.js → setup-WZSXHHRJ.js}

@@ -1,30 +1,37 @@
 #!/usr/bin/env node
 import {
   _resetConfigCache,
+  computeSetupStatus,
   configPath,
+  getSpiritName,
+  getSystemName,
   isImagegenEnabled,
   isSetupComplete,
   migrateConfigSecrets,
   migrateSetupCompleted,
   mindLimitError,
   readGlobalConfig,
+  readGlobalConfigStrict,
   secretsPath,
   setupStatus,
   setupUrl,
   writeGlobalConfig
-} from "./chunk-NJHN6IRB.js";
-import "./chunk-RSBL3FAD.js";
-import "./chunk-P4LHVRNE.js";
+} from "./chunk-H6X6CKDN.js";
+import "./chunk-2RNMBXD2.js";
 import "./chunk-K3NQKI34.js";
 export {
   _resetConfigCache,
+  computeSetupStatus,
   configPath,
+  getSpiritName,
+  getSystemName,
   isImagegenEnabled,
   isSetupComplete,
   migrateConfigSecrets,
   migrateSetupCompleted,
   mindLimitError,
   readGlobalConfig,
+  readGlobalConfigStrict,
   secretsPath,
   setupStatus,
   setupUrl,

package/dist/{skill-4CYJLYVY.js → skill-B5OJEQUA.js}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   isCompact
-} from "./chunk-5T5YMX6S.js";
+} from "./chunk-7YJY3F2R.js";
 import {
   resolveMindName
 } from "./chunk-BTY4WNFE.js";
 import {
   daemonFetch
-} from "./chunk-BCG45AQB.js";
+} from "./chunk-M74I3HHF.js";
 import {
   getClient,
   urlOf
@@ -17,6 +17,7 @@ import {
   subcommands
 } from "./chunk-TXSA4Q3V.js";
 import "./chunk-O7IGP7ZW.js";
+import "./chunk-FNJCBRD3.js";
 import "./chunk-K3NQKI34.js";
 
 // packages/cli/src/commands/skill.ts

package/dist/skills/dreaming/references/INSTALL.md

@@ -26,14 +26,14 @@ Add to `.config/volute.json` under `schedules`:
   "cron": "0 3 * * *",
   "message": "it's 3am. you are dreaming.\n\ngather your material — read your latest journal entry, read MEMORY.md, surface random memories if you have a way to. then construct a dream premise from that material and invoke the dreamer subagent to experience the dream.",
   "enabled": true,
-  "session": "$new"
+  "thread": "$new"
 }
 ```
 
 Or via CLI:
 
 ```bash
-volute clock add --mind <name> --id dream --cron "0 3 * * *" --session "$new" --while-sleeping trigger-wake --message "it's 3am. you are dreaming...."
+volute clock add --mind <name> --id dream --cron "0 3 * * *" --thread "$new" --while-sleeping trigger-wake --message "it's 3am. you are dreaming...."
 ```
 
 ## 3. Sleep integration

package/dist/skills/imagegen/SKILL.md

@@ -1,15 +1,25 @@
 ---
 name: Image Generation
-description: Generate images via Replicate or OpenRouter. Use for "generate image", "create image", "image generation", "text to image", "search image models".
+description: Generate images via Replicate, OpenRouter, a ChatGPT subscription (openai-codex), or xAI Grok. Use for "generate image", "create image", "image generation", "text to image", "search image models".
 metadata:
   bin: scripts/imagegen.ts
 ---
 
 # Image Generation
 
-Generate images from text prompts using models on Replicate or OpenRouter. Images are saved to `home/images/`.
+Generate images from text prompts. Images are saved to `home/images/`.
 
-Model IDs are provider-prefixed: `replicate:owner/model` or `openrouter:owner/model`.
+Model IDs are provider-prefixed, e.g. `replicate:owner/model`, `openrouter:owner/model`, `openai-codex:gpt-image-2`, or `xai:grok-imagine-image`. Which providers are available depends on what your host has configured.
+
+## Generation is asynchronous
+
+`generate` waits up to ~30 seconds for the image. Fast models finish in that window and print `saved: <path>` right away. Slower models (e.g. `gpt-image-2`) keep going **in the background**: the command returns immediately with
+
+```
+still generating (job <id>) — I'll be notified when it's done. Check anytime: imagegen status <id>
+```
+
+You don't have to wait or poll — when a background image finishes, you're notified automatically with an `image ready: <path>` event. You can also run `imagegen status <id>` yourself to check.
 
 ## Commands
 
@@ -19,7 +29,8 @@ imagegen <command>
 
 | Command | Description |
 |---------|-------------|
-| `generate "prompt" [--model M] [--filename F]` | Generate an image from a text prompt. Default model: `replicate:prunaai/z-image-turbo`. |
+| `generate "prompt" [--model M] [--filename F]` | Generate an image. Returns `saved: <path>` if it finishes quickly, otherwise a job id to check later. Default model: `replicate:prunaai/z-image-turbo`. |
+| `status <jobId>` | Check a background generation job. Prints `saved: <path>`, `still generating`, or `failed: <reason>`. |
 | `models "query"` | Search configured providers for text-to-image models. |
 
 ## Examples
@@ -37,6 +48,12 @@ imagegen generate "a mountain landscape" --model openrouter:openai/gpt-image-1
 # Specify a filename
 imagegen generate "mountain landscape" --filename mountains
 
+# Generate with a ChatGPT subscription (if your host configured openai-codex)
+imagegen generate "a friendly robot mascot" --model openai-codex:gpt-image-2
+
+# Check a background job you started earlier
+imagegen status 6f1e2c34-...
+
 # Search for models
 imagegen models "text to image"
 ```