gunni 0.3.0 → 0.3.3

package/dist/index.js

@@ -9,276 +9,6 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/core/model-registry.ts
-var model_registry_exports = {};
-__export(model_registry_exports, {
-  DEFAULTS: () => DEFAULTS,
-  getAllModels: () => getAllModels,
-  getCategories: () => getCategories,
-  getDefaultModel: () => getDefaultModel,
-  getModel: () => getModel,
-  getModelsByCategory: () => getModelsByCategory
-});
-function getAllModels() {
-  return MODELS;
-}
-function getModelsByCategory(category) {
-  return MODELS.filter((m) => m.category === category);
-}
-function getModel(id) {
-  return MODELS.find((m) => m.id === id);
-}
-function getDefaultModel(category) {
-  return MODELS.find((m) => m.category === category && m.isDefault);
-}
-function getCategories() {
-  return [...new Set(MODELS.map((m) => m.category))];
-}
-var DEFAULTS, MODELS;
-var init_model_registry = __esm({
-  "src/core/model-registry.ts"() {
-    "use strict";
-    DEFAULTS = {
-      image: "nano-banana",
-      edit: "nano-banana-edit",
-      describe: "florence-2",
-      upscale: "topaz-upscale",
-      removeBg: "bria-bg-remove",
-      video: "kling-v3-pro",
-      audio: "minimax-speech",
-      lipsync: "kling-lipsync",
-      design: "recraft-v4"
-    };
-    MODELS = [
-      // --- Image generation (hero: nano-banana) ---
-      {
-        id: "nano-banana",
-        name: "Nano Banana Pro",
-        provider: "google",
-        endpoint: "gemini-3-pro-image-preview",
-        category: "image",
-        description: "Google's state-of-the-art. Best overall quality and speed. Up to 4K resolution.",
-        isDefault: true
-      },
-      {
-        id: "recraft-v4",
-        name: "Recraft V4",
-        provider: "fal",
-        endpoint: "fal-ai/recraft/v4/text-to-image",
-        category: "image",
-        description: "Design and marketing. Only model that reliably renders text in images."
-      },
-      {
-        id: "flux-2-pro",
-        name: "Flux 2 Pro",
-        provider: "fal",
-        endpoint: "fal-ai/flux-2-pro",
-        category: "image",
-        description: "High-quality photorealism from Black Forest Labs."
-      },
-      // --- Image editing (hero: nano-banana-edit) ---
-      {
-        id: "nano-banana-edit",
-        name: "Nano Banana Pro Edit",
-        provider: "google",
-        endpoint: "gemini-3-pro-image-preview",
-        category: "edit",
-        description: "Google's model for precise image editing. Consistent with generation pipeline.",
-        isDefault: true,
-        multiImage: true
-      },
-      {
-        id: "flux-kontext",
-        name: "Flux Kontext Pro",
-        provider: "fal",
-        endpoint: "fal-ai/flux-pro/kontext/max/multi",
-        category: "edit",
-        description: "Targeted local edits with text and reference images. Supports multiple input images.",
-        multiImage: true
-      },
-      {
-        id: "flux-2-pro-edit",
-        name: "Flux 2 Pro Edit",
-        provider: "fal",
-        endpoint: "fal-ai/flux-2-pro/edit",
-        category: "edit",
-        description: "Multi-image editing. Combine up to 9 reference images with natural language. Use @image1, @image2 notation in prompts.",
-        multiImage: true
-      },
-      // --- Upscale (hero: topaz) ---
-      {
-        id: "topaz-upscale",
-        name: "Topaz Upscale",
-        provider: "fal",
-        endpoint: "fal-ai/topaz/upscale/image",
-        category: "upscale",
-        description: "Industry-standard image upscaling and enhancement.",
-        isDefault: true
-      },
-      // --- Video (hero: kling-v3-pro) ---
-      {
-        id: "kling-v3-pro",
-        name: "Kling V3 Pro",
-        provider: "fal",
-        endpoint: "fal-ai/kling-video/v3/pro/image-to-video",
-        category: "video",
-        description: "Cinematic video with fluid motion and native audio.",
-        isDefault: true
-      },
-      {
-        id: "kling-v3-pro-t2v",
-        name: "Kling V3 Pro (Text)",
-        provider: "fal",
-        endpoint: "fal-ai/kling-video/v3/pro/text-to-video",
-        category: "video",
-        description: "Kling V3 Pro text-to-video. No source image needed."
-      },
-      {
-        id: "veo-3.1",
-        name: "Veo 3.1",
-        provider: "fal",
-        endpoint: "fal-ai/veo3.1/image-to-video",
-        category: "video",
-        description: "Google's video generation with sound, via Fal."
-      },
-      {
-        id: "veo-3.1-t2v",
-        name: "Veo 3.1 (Text)",
-        provider: "fal",
-        endpoint: "fal-ai/veo3.1",
-        category: "video",
-        description: "Veo 3.1 text-to-video with native audio."
-      },
-      {
-        id: "veo-3.1-fast",
-        name: "Veo 3.1 Fast",
-        provider: "fal",
-        endpoint: "fal-ai/veo3.1/fast/image-to-video",
-        category: "video",
-        description: "Veo 3.1 Fast \u2014 62% cheaper, slightly lower quality. Image-to-video with sound."
-      },
-      {
-        id: "veo-3.1-fast-t2v",
-        name: "Veo 3.1 Fast (Text)",
-        provider: "fal",
-        endpoint: "fal-ai/veo3.1/fast",
-        category: "video",
-        description: "Veo 3.1 Fast text-to-video with native audio. Budget-friendly option."
-      },
-      {
-        id: "minimax-i2v",
-        name: "MiniMax Hailuo 2.3",
-        provider: "fal",
-        endpoint: "fal-ai/minimax/hailuo-2.3/pro/image-to-video",
-        category: "video",
-        description: "MiniMax Hailuo 2.3 Pro image-to-video. 1080p output."
-      },
-      {
-        id: "wan-2.6",
-        name: "Wan 2.6",
-        provider: "fal",
-        endpoint: "wan/v2.6/image-to-video",
-        category: "video",
-        description: "Alibaba Wan 2.6 image-to-video. Up to 1080p with native audio."
-      },
-      // --- Audio (hero: minimax-speech) ---
-      {
-        id: "minimax-speech",
-        name: "MiniMax Speech 2.8 HD",
-        provider: "fal",
-        endpoint: "fal-ai/minimax/speech-2.8-hd",
-        category: "audio",
-        description: "High-quality text-to-speech with multiple voices.",
-        isDefault: true
-      },
-      {
-        id: "elevenlabs-tts",
-        name: "ElevenLabs TTS v3",
-        provider: "fal",
-        endpoint: "fal-ai/elevenlabs/tts/turbo-v2.5",
-        category: "audio",
-        description: "Natural, conversational text-to-speech. Best for UGC voiceovers and narration."
-      },
-      // --- Lip sync (hero: kling-lipsync) ---
-      {
-        id: "kling-lipsync",
-        name: "Kling LipSync",
-        provider: "fal",
-        endpoint: "fal-ai/kling-video/lipsync/audio-to-video",
-        category: "lipsync",
-        description: "Lip-sync audio onto a video. Input: source video + audio track. Best quality lip sync.",
-        isDefault: true
-      },
-      {
-        id: "kling-avatar",
-        name: "Kling AI Avatar v2",
-        provider: "fal",
-        endpoint: "fal-ai/kling-video/ai-avatar/v2/standard",
-        category: "lipsync",
-        description: "Generate talking head video from a still image + audio. One-step avatar animation."
-      },
-      {
-        id: "sync-lipsync",
-        name: "Sync Labs Lipsync 2.0",
-        provider: "fal",
-        endpoint: "fal-ai/sync-lipsync",
-        category: "lipsync",
-        description: "Advanced lip sync with natural motion. Alternative to Kling LipSync."
-      },
-      // --- Describe / vision (hero: florence-2) ---
-      {
-        id: "florence-2",
-        name: "Florence 2 Large",
-        provider: "fal",
-        endpoint: "fal-ai/florence-2-large/detailed-caption",
-        category: "describe",
-        description: "Detailed image captioning and description.",
-        isDefault: true
-      },
-      // --- OpenAI image generation ---
-      {
-        id: "gpt-image",
-        name: "GPT Image 1.5",
-        provider: "openai",
-        endpoint: "gpt-image-1.5",
-        category: "image",
-        description: "OpenAI's latest image model. Best-in-class text rendering and editing.",
-        isDefault: false
-      },
-      {
-        id: "gpt-image-mini",
-        name: "GPT Image Mini",
-        provider: "openai",
-        endpoint: "gpt-image-1-mini",
-        category: "image",
-        description: "Cost-optimized OpenAI image model. Great for high-volume generation.",
-        isDefault: false
-      },
-      // --- OpenAI image editing ---
-      {
-        id: "gpt-image-edit",
-        name: "GPT Image 1.5 Edit",
-        provider: "openai",
-        endpoint: "gpt-image-1.5",
-        category: "edit",
-        description: "OpenAI image editing. Surgical precision for inpainting and modifications.",
-        isDefault: false,
-        multiImage: true
-      },
-      // --- Utility ---
-      {
-        id: "bria-bg-remove",
-        name: "Bria Background Removal",
-        provider: "fal",
-        endpoint: "fal-ai/bria/background/remove",
-        category: "utility",
-        description: "Remove backgrounds from images.",
-        isDefault: true
-      }
-    ];
-  }
-});
-
 // src/core/supabase.ts
 import { createClient } from "@supabase/supabase-js";
 function getSupabase() {
@@ -422,7 +152,7 @@ var init_refs = __esm({
 
 // src/index.ts
 import { Command } from "commander";
-import pc25 from "picocolors";
+import pc21 from "picocolors";
 
 // src/commands/image.ts
 import { existsSync } from "fs";
@@ -573,8 +303,253 @@ async function detectImageFormat(filePath) {
   return void 0;
 }
 
-// src/core/model-router.ts
-init_model_registry();
+// data/models.json
+var models_default = {
+  defaults: {
+    image: "nano-banana",
+    edit: "nano-banana-edit",
+    describe: "florence-2",
+    upscale: "topaz-upscale",
+    removeBg: "bria-bg-remove",
+    video: "kling-v3-pro",
+    audio: "minimax-speech",
+    lipsync: "kling-lipsync",
+    design: "recraft-v4"
+  },
+  models: [
+    {
+      id: "nano-banana",
+      name: "Nano Banana Pro",
+      provider: "google",
+      endpoint: "gemini-3-pro-image-preview",
+      category: "image",
+      description: "Google's state-of-the-art. Best overall quality and speed. Up to 4K resolution.",
+      isDefault: true
+    },
+    {
+      id: "recraft-v4",
+      name: "Recraft V4",
+      provider: "fal",
+      endpoint: "fal-ai/recraft/v4/text-to-image",
+      category: "image",
+      description: "Design and marketing. Only model that reliably renders text in images."
+    },
+    {
+      id: "flux-2-pro",
+      name: "Flux 2 Pro",
+      provider: "fal",
+      endpoint: "fal-ai/flux-2-pro",
+      category: "image",
+      description: "High-quality photorealism from Black Forest Labs."
+    },
+    {
+      id: "nano-banana-edit",
+      name: "Nano Banana Pro Edit",
+      provider: "google",
+      endpoint: "gemini-3-pro-image-preview",
+      category: "edit",
+      description: "Google's model for precise image editing. Consistent with generation pipeline.",
+      isDefault: true,
+      multiImage: true
+    },
+    {
+      id: "flux-kontext",
+      name: "Flux Kontext Pro",
+      provider: "fal",
+      endpoint: "fal-ai/flux-pro/kontext/max/multi",
+      category: "edit",
+      description: "Targeted local edits with text and reference images. Supports multiple input images.",
+      multiImage: true
+    },
+    {
+      id: "flux-2-pro-edit",
+      name: "Flux 2 Pro Edit",
+      provider: "fal",
+      endpoint: "fal-ai/flux-2-pro/edit",
+      category: "edit",
+      description: "Multi-image editing. Combine up to 9 reference images with natural language. Use @image1, @image2 notation in prompts.",
+      multiImage: true
+    },
+    {
+      id: "topaz-upscale",
+      name: "Topaz Upscale",
+      provider: "fal",
+      endpoint: "fal-ai/topaz/upscale/image",
+      category: "upscale",
+      description: "Industry-standard image upscaling and enhancement.",
+      isDefault: true
+    },
+    {
+      id: "kling-v3-pro",
+      name: "Kling V3 Pro",
+      provider: "fal",
+      endpoint: "fal-ai/kling-video/v3/pro/image-to-video",
+      category: "video",
+      description: "Cinematic video with fluid motion and native audio.",
+      isDefault: true
+    },
+    {
+      id: "kling-v3-pro-t2v",
+      name: "Kling V3 Pro (Text)",
+      provider: "fal",
+      endpoint: "fal-ai/kling-video/v3/pro/text-to-video",
+      category: "video",
+      description: "Kling V3 Pro text-to-video. No source image needed."
+    },
+    {
+      id: "veo-3.1",
+      name: "Veo 3.1",
+      provider: "fal",
+      endpoint: "fal-ai/veo3.1/image-to-video",
+      category: "video",
+      description: "Google's video generation with sound, via Fal."
+    },
+    {
+      id: "veo-3.1-t2v",
+      name: "Veo 3.1 (Text)",
+      provider: "fal",
+      endpoint: "fal-ai/veo3.1",
+      category: "video",
+      description: "Veo 3.1 text-to-video with native audio."
+    },
+    {
+      id: "veo-3.1-fast",
+      name: "Veo 3.1 Fast",
+      provider: "fal",
+      endpoint: "fal-ai/veo3.1/fast/image-to-video",
+      category: "video",
+      description: "Veo 3.1 Fast \u2014 62% cheaper, slightly lower quality. Image-to-video with sound."
+    },
+    {
+      id: "veo-3.1-fast-t2v",
+      name: "Veo 3.1 Fast (Text)",
+      provider: "fal",
+      endpoint: "fal-ai/veo3.1/fast",
+      category: "video",
+      description: "Veo 3.1 Fast text-to-video with native audio. Budget-friendly option."
+    },
+    {
+      id: "minimax-i2v",
+      name: "MiniMax Hailuo 2.3",
+      provider: "fal",
+      endpoint: "fal-ai/minimax/hailuo-2.3/pro/image-to-video",
+      category: "video",
+      description: "MiniMax Hailuo 2.3 Pro image-to-video. 1080p output."
+    },
+    {
+      id: "wan-2.6",
+      name: "Wan 2.6",
+      provider: "fal",
+      endpoint: "wan/v2.6/image-to-video",
+      category: "video",
+      description: "Alibaba Wan 2.6 image-to-video. Up to 1080p with native audio."
+    },
+    {
+      id: "minimax-speech",
+      name: "MiniMax Speech 2.8 HD",
+      provider: "fal",
+      endpoint: "fal-ai/minimax/speech-2.8-hd",
+      category: "audio",
+      description: "High-quality text-to-speech with multiple voices.",
+      isDefault: true
+    },
+    {
+      id: "elevenlabs-tts",
+      name: "ElevenLabs TTS v3",
+      provider: "fal",
+      endpoint: "fal-ai/elevenlabs/tts/turbo-v2.5",
+      category: "audio",
+      description: "Natural, conversational text-to-speech. Best for UGC voiceovers and narration."
+    },
+    {
+      id: "kling-lipsync",
+      name: "Kling LipSync",
+      provider: "fal",
+      endpoint: "fal-ai/kling-video/lipsync/audio-to-video",
+      category: "lipsync",
+      description: "Lip-sync audio onto a video. Input: source video + audio track. Best quality lip sync.",
+      isDefault: true
+    },
+    {
+      id: "kling-avatar",
+      name: "Kling AI Avatar v2",
+      provider: "fal",
+      endpoint: "fal-ai/kling-video/ai-avatar/v2/standard",
+      category: "lipsync",
+      description: "Generate talking head video from a still image + audio. One-step avatar animation."
+    },
+    {
+      id: "sync-lipsync",
+      name: "Sync Labs Lipsync 2.0",
+      provider: "fal",
+      endpoint: "fal-ai/sync-lipsync",
+      category: "lipsync",
+      description: "Advanced lip sync with natural motion. Alternative to Kling LipSync."
+    },
+    {
+      id: "florence-2",
+      name: "Florence 2 Large",
+      provider: "fal",
+      endpoint: "fal-ai/florence-2-large/detailed-caption",
+      category: "describe",
+      description: "Detailed image captioning and description.",
+      isDefault: true
+    },
+    {
+      id: "gpt-image",
+      name: "GPT Image 1.5",
+      provider: "openai",
+      endpoint: "gpt-image-1.5",
+      category: "image",
+      description: "OpenAI's latest image model. Best-in-class text rendering and editing.",
+      isDefault: false
+    },
+    {
+      id: "gpt-image-mini",
+      name: "GPT Image Mini",
+      provider: "openai",
+      endpoint: "gpt-image-1-mini",
+      category: "image",
+      description: "Cost-optimized OpenAI image model. Great for high-volume generation.",
+      isDefault: false
+    },
+    {
+      id: "gpt-image-edit",
+      name: "GPT Image 1.5 Edit",
+      provider: "openai",
+      endpoint: "gpt-image-1.5",
+      category: "edit",
+      description: "OpenAI image editing. Surgical precision for inpainting and modifications.",
+      isDefault: false,
+      multiImage: true
+    },
+    {
+      id: "bria-bg-remove",
+      name: "Bria Background Removal",
+      provider: "fal",
+      endpoint: "fal-ai/bria/background/remove",
+      category: "utility",
+      description: "Remove backgrounds from images.",
+      isDefault: true
+    }
+  ]
+};
+
+// src/core/model-registry.ts
+var DEFAULTS = models_default.defaults;
+var MODELS = models_default.models;
+function getAllModels() {
+  return MODELS;
+}
+function getModelsByCategory(category) {
+  return MODELS.filter((m) => m.category === category);
+}
+function getModel(id) {
+  return MODELS.find((m) => m.id === id);
+}
+function getCategories() {
+  return [...new Set(MODELS.map((m) => m.category))];
+}
 
 // src/providers/base.ts
 function resolveImagePaths(options) {
@@ -665,9 +640,6 @@ function isNodeError(err) {
   return err instanceof Error && "code" in err;
 }
 
-// src/providers/fal.ts
-init_model_registry();
-
 // src/core/uploader.ts
 import { readFile as readFile3 } from "fs/promises";
 import { basename } from "path";
@@ -758,9 +730,9 @@ var FalProvider = class extends BaseProvider {
       const message = err instanceof Error ? err.message : String(err);
       if (message.includes("Forbidden") || message.includes("401") || message.includes("403")) {
         throw new GunniError(
-          "API key rejected by fal.ai",
+          "Authentication failed",
           "AUTH_ERROR",
-          "Check your key at https://fal.ai/dashboard/keys and re-run `gunni config`."
+          "Check your API key and re-run `gunni config`."
         );
       }
       throw new GunniError("Request failed", "PROVIDER_ERROR", message);
@@ -886,6 +858,28 @@ var FalProvider = class extends BaseProvider {
       requestId: result.requestId
     };
   }
+  async submitToQueue(endpoint, input) {
+    const apiKey = this.overrideApiKey ?? await this.configManager.getApiKey("fal");
+    if (!apiKey) {
+      throw new GunniError("Not configured yet", "NO_API_KEY", "Run `gunni config` to get started.");
+    }
+    const { createFalClient } = await import("@fal-ai/client");
+    const client2 = createFalClient({ credentials: apiKey });
+    const result = await client2.queue.submit(endpoint, { input });
+    return result.request_id;
+  }
+  async checkQueueStatus(endpoint, requestId) {
+    const apiKey = this.overrideApiKey ?? await this.configManager.getApiKey("fal");
+    if (!apiKey) throw new GunniError("Not configured yet", "NO_API_KEY");
+    const { createFalClient } = await import("@fal-ai/client");
+    const client2 = createFalClient({ credentials: apiKey });
+    const status = await client2.queue.status(endpoint, { requestId });
+    if (status.status === "COMPLETED") {
+      const result = await client2.queue.result(endpoint, { requestId });
+      return { status: "COMPLETED", data: result.data };
+    }
+    return { status: status.status };
+  }
   async prepareImage(imagePath) {
     return uploadToFal(imagePath);
   }
@@ -894,7 +888,6 @@ var FalProvider = class extends BaseProvider {
 // src/providers/vertex.ts
 import { readFile as readFile4 } from "fs/promises";
 import { extname as extname2 } from "path";
-init_model_registry();
 var VERTEX_PROJECT = "gunni-488216";
 var VERTEX_LOCATION = "us-central1";
 function resolveAspectRatio(width, height) {
@@ -1136,7 +1129,6 @@ async function downloadFromGcs(gcsUri) {
 
 // src/providers/openai.ts
 import { readFile as readFile5 } from "fs/promises";
-init_model_registry();
 var OPENAI_API_BASE = "https://api.openai.com/v1";
 function resolveSize(width, height) {
   if (!width || !height) return "1024x1024";
@@ -1369,16 +1361,9 @@ var ModelRouter = class {
   }
 };
 
-// src/commands/image.ts
-init_model_registry();
-
-// src/core/provider-resolver.ts
-init_model_registry();
-
 // src/providers/google.ts
 import { readFile as readFile6 } from "fs/promises";
 import { extname as extname3 } from "path";
-init_model_registry();
 function imageExtToMimeType2(imagePath) {
   const ext = extname3(imagePath).toLowerCase();
   const map = {
@@ -1630,6 +1615,8 @@ function openFile(filePath) {
       detached: true,
       stdio: "ignore"
     });
+    child.on("error", () => {
+    });
     child.unref();
   } catch {
   }
@@ -1642,6 +1629,8 @@ function openUrl(url) {
       detached: true,
       stdio: "ignore"
     });
+    child.on("error", () => {
+    });
     child.unref();
   } catch {
   }
@@ -1681,6 +1670,7 @@ async function searchHistory(query) {
 // src/core/remote-client.ts
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+var DEFAULT_TIMEOUT_MS = 6e4;
 var RemoteClient = class {
   client = null;
   async connect(apiKey, serverUrl) {
@@ -1692,14 +1682,18 @@ var RemoteClient = class {
         }
       }
     );
-    this.client = new Client({ name: "gunni-cli", version: "0.2.0" });
+    this.client = new Client({ name: "gunni-cli", version: "0.3.3" });
     await this.client.connect(transport);
   }
   async callTool(name, args) {
     if (!this.client) {
       throw new GunniError("Remote client not connected", "NOT_CONNECTED");
     }
-    const result = await this.client.callTool({ name, arguments: args });
+    const result = await this.client.callTool(
+      { name, arguments: args },
+      void 0,
+      { timeout: DEFAULT_TIMEOUT_MS }
+    );
     const firstContent = result.content?.[0];
     if (!firstContent || firstContent.type !== "text") {
       throw new GunniError(
@@ -1707,7 +1701,20 @@ var RemoteClient = class {
         "INVALID_RESPONSE"
       );
     }
-    return JSON.parse(firstContent.text);
+    const text3 = firstContent.text;
+    if (result.isError) {
+      try {
+        const parsed = JSON.parse(text3);
+        throw new GunniError(
+          parsed.error?.message ?? parsed.error ?? text3,
+          parsed.error?.code ?? "REMOTE_ERROR"
+        );
+      } catch (e) {
+        if (e instanceof GunniError) throw e;
+        throw new GunniError(text3, "REMOTE_ERROR");
+      }
+    }
+    return JSON.parse(text3);
   }
   async disconnect() {
     if (this.client) {
@@ -2421,7 +2428,6 @@ async function handleRemoveBg(imagePath, modelId, opts, json) {
 // src/commands/video.ts
 import { existsSync as existsSync2 } from "fs";
 import ora3 from "ora";
-init_model_registry();
 import pc4 from "picocolors";
 var DEFAULT_MODEL = "kling-v3-pro";
 function registerVideoCommand(program2) {
@@ -2598,13 +2604,20 @@ async function handleRemote2(input, opts, json, apiKey, serverUrl) {
           "MISSING_INPUT"
         );
       }
-      if (existsSync2(input)) {
+      const looksLikeUrl = /^https?:\/\//.test(input);
+      if (!existsSync2(input) && !looksLikeUrl) {
+        prompt = opts.prompt ? `${input} ${opts.prompt}` : input;
+        if (!userExplicitModel && modelId === DEFAULT_MODEL) {
+          modelId = "kling-v3-pro-t2v";
+        }
+      } else if (existsSync2(input)) {
         update("Uploading image\u2026");
         imageUrl = await uploadLocalFile(input, apiKey, serverUrl);
+        prompt = opts.prompt ?? "";
       } else {
         imageUrl = input;
+        prompt = opts.prompt ?? "";
       }
-      prompt = opts.prompt ?? "";
     }
     if (opts.style) {
       const customerId = process.env.GUNNI_CUSTOMER_ID;
@@ -2636,7 +2649,22 @@ async function handleRemote2(input, opts, json, apiKey, serverUrl) {
     update("Generating video\u2026");
     const client2 = new RemoteClient();
     await client2.connect(apiKey, serverUrl);
-    const result = await client2.callTool("video", toolArgs);
+    let result = await client2.callTool("video", toolArgs);
+    if (result.jobId) {
+      const jobId = result.jobId;
+      let jobStatus;
+      while (true) {
+        await new Promise((r) => setTimeout(r, 5e3));
+        jobStatus = await client2.callTool("job_status", { job_id: jobId });
+        if (jobStatus.status === "completed") break;
+        if (jobStatus.status === "failed") {
+          await client2.disconnect();
+          throw new GunniError(jobStatus.error ?? "Job failed", "JOB_FAILED");
+        }
+        update(`Generating video\u2026 (${jobStatus.status})`);
+      }
+      result = jobStatus?.result ?? {};
+    }
     await client2.disconnect();
     const requestedPath = opts.output ?? `gunni-video-${Date.now()}.mp4`;
     const videoAssetUrl = result.video?.assetUrl;
@@ -2678,7 +2706,6 @@ async function handleRemote2(input, opts, json, apiKey, serverUrl) {
 
 // src/commands/audio.ts
 import ora4 from "ora";
-init_model_registry();
 import pc5 from "picocolors";
 var DEFAULT_MODEL2 = "minimax-speech";
 function registerAudioCommand(program2) {
@@ -2707,14 +2734,14 @@ Examples:
 Available audio models: minimax-speech (default), elevenlabs-tts
 Run 'gunni list models --type audio' for details.
 `
-  ).action(async (text4, opts) => {
+  ).action(async (text3, opts) => {
     const json = program2.opts().json ?? false;
     try {
       const config = new ConfigManager();
       const gunniKey = await config.getGunniApiKey();
       if (gunniKey) {
         const serverUrl = await config.getServerUrl();
-        return handleRemote3(text4, opts, json, gunniKey, serverUrl);
+        return handleRemote3(text3, opts, json, gunniKey, serverUrl);
       }
       throw new GunniError(
         "No API key configured",
@@ -2729,7 +2756,7 @@ Run 'gunni list models --type audio' for details.
       const endpoint = getEndpoint(modelId);
       const falInput = {};
       if (modelId === "minimax-speech") {
-        falInput.prompt = text4;
+        falInput.prompt = text3;
         falInput.voice_setting = {
           voice_id: opts.voice ?? "Wise_Woman",
           speed: 1,
@@ -2737,10 +2764,10 @@ Run 'gunni list models --type audio' for details.
           pitch: 0
         };
       } else if (modelId === "elevenlabs-tts") {
-        falInput.text = text4;
+        falInput.text = text3;
         if (opts.voice) falInput.voice_id = opts.voice;
       } else {
-        falInput.text = text4;
+        falInput.text = text3;
         if (opts.voice) {
           falInput.audio_url = opts.voice;
         }
@@ -2761,7 +2788,7 @@ Run 'gunni list models --type audio' for details.
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         command: "audio",
         model: modelId,
-        prompt: text4,
+        prompt: text3,
         outputPath: finalPath,
         outputUrl: audioUrl
       }).catch(() => {
@@ -2769,7 +2796,7 @@ Run 'gunni list models --type audio' for details.
       const output = {
         audio: { path: finalPath, url: audioUrl },
         model: modelId,
-        text: text4,
+        text: text3,
         voice: opts.voice
       };
       if (json) {
@@ -2796,14 +2823,14 @@ function getEndpoint(modelId) {
   }
   return model.endpoint;
 }
-async function handleRemote3(text4, opts, json, apiKey, serverUrl) {
+async function handleRemote3(text3, opts, json, apiKey, serverUrl) {
   const spinner = json ? void 0 : ora4("Generating audio\u2026").start();
   const update = (s) => {
     if (spinner) spinner.text = s;
   };
   try {
     const modelId = opts.model ?? DEFAULT_MODEL2;
-    const toolArgs = { text: text4, model: modelId };
+    const toolArgs = { text: text3, model: modelId };
     if (opts.voice) toolArgs.voice = opts.voice;
     const client2 = new RemoteClient();
     await client2.connect(apiKey, serverUrl);
@@ -2821,7 +2848,7 @@ async function handleRemote3(text4, opts, json, apiKey, serverUrl) {
     const output = {
       audio: { path: finalPath, url: audioAssetUrl },
       model: modelId,
-      text: text4,
+      text: text3,
       voice: opts.voice
     };
     if (json) {
@@ -2841,7 +2868,6 @@ async function handleRemote3(text4, opts, json, apiKey, serverUrl) {
 // src/commands/lipsync.ts
 import { existsSync as existsSync3 } from "fs";
 import ora5 from "ora";
-init_model_registry();
 import pc6 from "picocolors";
 var DEFAULT_MODEL3 = "kling-lipsync";
 function registerLipsyncCommand(program2) {
@@ -2992,7 +3018,22 @@ async function handleRemote4(audio, opts, json, apiKey, serverUrl) {
     update("Generating lip sync\u2026");
     const client2 = new RemoteClient();
     await client2.connect(apiKey, serverUrl);
-    const result = await client2.callTool("lipsync", toolArgs);
+    let result = await client2.callTool("lipsync", toolArgs);
+    if (result.jobId) {
+      const jobId = result.jobId;
+      let jobStatus;
+      while (true) {
+        await new Promise((r) => setTimeout(r, 5e3));
+        jobStatus = await client2.callTool("job_status", { job_id: jobId });
+        if (jobStatus.status === "completed") break;
+        if (jobStatus.status === "failed") {
+          await client2.disconnect();
+          throw new GunniError(jobStatus.error ?? "Job failed", "JOB_FAILED");
+        }
+        update(`Generating lip sync\u2026 (${jobStatus.status})`);
+      }
+      result = jobStatus?.result ?? {};
+    }
     await client2.disconnect();
     const videoAssetUrl = result.video?.assetUrl;
     if (!videoAssetUrl) {
@@ -3092,34 +3133,18 @@ function formatEntry(e) {
 // src/commands/learn.ts
 import pc8 from "picocolors";
 
-// src/core/knowledge.ts
-var TOPICS = {
-  overview: {
-    topic: "overview",
-    title: "Gunni Overview",
-    content: `Gunni tools for professional media creation:
-
-MEDIA: image (generate/edit/describe/upscale/remove-bg, routes by input), video, audio
-REFS: ref_save (save image as ref), refs (list or get refs by name), upload_ref (user uploads from their device)
-UTILITY: models (list models + updates), history (search past work), learn (you're here)
-
-ROUTING (image): prompt only \u2192 generate, image+prompt \u2192 edit, image only \u2192 describe, +upscale/remove_bg flags
-MULTI-IMAGE: pass an array of URLs to image for multi-ref editing
-
-USER IMAGE UPLOADS: When a user provides or pastes an image and you need to use it as input (for editing, video, describe, etc.), you MUST call upload_ref first. The image/video tools require a URL (https://...), not a local file path. Workflow:
-1. Call upload_ref with a name for the reference
-2. The user uploads their file via the Gunni Studio UI
-3. After upload completes, use the resulting URL in image/video tools
-Never pass a local file path to image or video. It will fail.
-
-PROJECT SYSTEM: BRIEF.md (creative direction), .gunni/assets.json (lineage), .gunni/seeds.json (proven seeds)
-
-IMPORTANT: Every generation response includes a galleryUrl. Always share it with the user so they can view results in full resolution.`
-  },
-  exploration: {
-    topic: "exploration",
-    title: "Creative Exploration",
-    content: `Creative work is a tree, not a pipeline. Here's how to explore effectively:
+// data/knowledge.json
+var knowledge_default = {
+  topics: {
+    overview: {
+      topic: "overview",
+      title: "Gunni Overview",
+      content: "Gunni tools for professional media creation:\n\nMEDIA: image (generate/edit/describe/upscale/remove-bg, routes by input), video, audio\nREFS: ref_save (save image as ref), refs (list or get refs by name), upload_ref (user uploads from their device)\nUTILITY: models (list models + updates), history (search past work), learn (you're here)\n\nROUTING (image): prompt only \u2192 generate, image+prompt \u2192 edit, image only \u2192 describe, +upscale/remove_bg flags\nMULTI-IMAGE: pass an array of URLs to image for multi-ref editing\n\nUSER IMAGE UPLOADS: When a user provides or pastes an image and you need to use it as input (for editing, video, describe, etc.), you MUST call upload_ref first. The image/video tools require a URL (https://...), not a local file path. Workflow:\n1. Call upload_ref with a name for the reference\n2. The user uploads their file via the Gunni Studio UI\n3. After upload completes, use the resulting URL in image/video tools\nNever pass a local file path to image or video. It will fail.\n\nPROJECT SYSTEM: BRIEF.md (creative direction), .gunni/assets.json (lineage), .gunni/seeds.json (proven seeds)\n\nIMPORTANT: Every generation response includes a galleryUrl. Always share it with the user so they can view results in full resolution."
+    },
+    exploration: {
+      topic: "exploration",
+      title: "Creative Exploration",
+      content: `Creative work is a tree, not a pipeline. Here's how to explore effectively:
 
 ROUND 1: START FOCUSED
 - Generate 1 image first. Show it to the user and get feedback before making more.
@@ -3145,91 +3170,21 @@ POLISH
 - Don't upscale until the concept is locked. Upscaling is the final step.
 - Use image --upscale for production quality.
 - Describe the final result to verify it meets the brief.`
-  },
-  prompting: {
-    topic: "prompting",
-    title: "Prompt Craft",
-    content: `How to write effective prompts for image generation:
-
-STRUCTURE
-- Lead with the subject, then add style, lighting, and mood.
-- Be specific: subject + action + setting + style + technical elements.
-- Good: "ceramic mug on wooden table, morning light, editorial photography, shallow depth of field"
-- Weak: "a nice mug photo"
-
-STYLE KEYWORDS THAT WORK
-- Photography: "editorial", "product photography", "studio lighting", "natural light", "shallow depth of field"
-- Design: "minimalist", "clean lines", "modern", "professional", "flat design"
-- Mood: "warm", "cinematic", "moody", "bright and airy", "dramatic lighting"
-- Quality: "high detail", "photorealistic", "4K", "professional grade"
-- Camera: "wide-angle", "f/2.8", "85mm portrait lens", "macro", "low angle shot", "dolly zoom"
-
-NEGATIVE PROMPTS
-- Explicitly exclude unwanted elements: "no blur, no artifacts, no text"
-- Effective for cleaning up outputs, especially with Recraft v4 and Flux.
-- Example: "professional headshot, studio lighting, no watermark, no distortion"
-
-CONSISTENCY
-- Use seeds for reproducible results. Same seed + same prompt = same image.
-- When creating a series, keep the style keywords consistent across prompts.
-- Reference BRIEF.md constraints to stay on-brand.
-
-FOR EDITS
-- Be specific about what to change: "make the lighting warmer" not "improve it".
-- Reference specific elements: "change the background to marble" not "change the background".
-- Additive edits work better than subtractive ones.
-- For faces/people: use "preserve facial features" or "maintain likeness" to keep identity.
-- One edit at a time yields better results than compound changes.
-
-REFERENCES
-- High-quality references (2K/4K) prevent artifacts like blurriness.
-- Tag inputs clearly for multi-image edits: @image1 for character, @image2 for style.
-
-MODEL STRENGTHS
-- Nano Banana: Best overall quality. Photorealism, complex scenes, multi-turn edits. Use "preserve facial features" for likeness consistency.
-- Recraft v4: Text rendering, design, vectors, marketing materials. Use negative prompts for text-heavy designs. Only model that reliably puts text in images.
-- Flux 2 Pro / Flux Kontext: Technical descriptions over vague adjectives. Specify camera settings (lens, aperture, angle) for best results. Kontext excels at targeted local edits.
-- GPT Image: Strong text rendering and surgical inpainting. Good for precise modifications.
-- Use default models unless you have a specific reason to override.`
-  },
-  brand: {
-    topic: "brand",
-    title: "Brand Identity Design",
-    content: `How to create a cohesive brand identity with Gunni:
-
-START WITH THE BRIEF
-- Read BRIEF.md for colors, style, constraints, and references.
-- If no BRIEF.md exists, ask what the brand represents before generating.
-
-LOGO EXPLORATION
-- Start with 1 logo concept. Show it, get feedback, then iterate or try a different approach.
-- Only generate multiple variants when the user asks for options.
-- ALWAYS include the exact brand/company name in the prompt when the logo should contain text.
-- Use Recraft v4 for logos that include text (only model that nails typography).
-- Use Nano Banana for abstract marks and iconic logos.
-- Always remove background after selecting a logo direction.
-
-COLOR PALETTE
-- Extract colors from the best generation and codify them in BRIEF.md.
-- Use consistent color keywords in all subsequent prompts.
-- Test colors across light and dark backgrounds.
-
-BUILDING THE KIT
-1. Logo (with and without background)
-2. Hero image (wide format, brand aesthetic)
-3. Social media templates (square, story, header sizes)
-4. Pattern or texture (for backgrounds)
-5. Product mockups (logo placed in context)
-
-CONSISTENCY
-- Save good seeds to seeds.json after each successful generation.
-- Reference the logo in subsequent prompts: "in the style of [brand], using [colors]"
-- Keep style keywords identical across all generations.`
-  },
-  "ui-design": {
-    topic: "ui-design",
-    title: "UI/UX Design",
-    content: `How to generate UI designs and interface assets with Gunni:
+    },
+    prompting: {
+      topic: "prompting",
+      title: "Prompt Craft",
+      content: 'How to write effective prompts for image generation:\n\nSTRUCTURE\n- Lead with the subject, then add style, lighting, and mood.\n- Be specific: subject + action + setting + style + technical elements.\n- Good: "ceramic mug on wooden table, morning light, editorial photography, shallow depth of field"\n- Weak: "a nice mug photo"\n\nSTYLE KEYWORDS THAT WORK\n- Photography: "editorial", "product photography", "studio lighting", "natural light", "shallow depth of field"\n- Design: "minimalist", "clean lines", "modern", "professional", "flat design"\n- Mood: "warm", "cinematic", "moody", "bright and airy", "dramatic lighting"\n- Quality: "high detail", "photorealistic", "4K", "professional grade"\n- Camera: "wide-angle", "f/2.8", "85mm portrait lens", "macro", "low angle shot", "dolly zoom"\n\nNEGATIVE PROMPTS\n- Explicitly exclude unwanted elements: "no blur, no artifacts, no text"\n- Effective for cleaning up outputs, especially with Recraft v4 and Flux.\n- Example: "professional headshot, studio lighting, no watermark, no distortion"\n\nCONSISTENCY\n- Use seeds for reproducible results. Same seed + same prompt = same image.\n- When creating a series, keep the style keywords consistent across prompts.\n- Reference BRIEF.md constraints to stay on-brand.\n\nFOR EDITS\n- Be specific about what to change: "make the lighting warmer" not "improve it".\n- Reference specific elements: "change the background to marble" not "change the background".\n- Additive edits work better than subtractive ones.\n- For faces/people: use "preserve facial features" or "maintain likeness" to keep identity.\n- One edit at a time yields better results than compound changes.\n\nREFERENCES\n- High-quality references (2K/4K) prevent artifacts like blurriness.\n- Tag inputs clearly for multi-image edits: @image1 for character, @image2 for style.\n\nMODEL STRENGTHS\n- Nano Banana: Best overall quality. Photorealism, complex scenes, multi-turn edits. Use "preserve facial features" for likeness consistency.\n- Recraft v4: Text rendering, design, vectors, marketing materials. Use negative prompts for text-heavy designs. Only model that reliably puts text in images.\n- Flux 2 Pro / Flux Kontext: Technical descriptions over vague adjectives. Specify camera settings (lens, aperture, angle) for best results. Kontext excels at targeted local edits.\n- GPT Image: Strong text rendering and surgical inpainting. Good for precise modifications.\n- Use default models unless you have a specific reason to override.'
+    },
+    brand: {
+      topic: "brand",
+      title: "Brand Identity Design",
+      content: 'How to create a cohesive brand identity with Gunni:\n\nSTART WITH THE BRIEF\n- Read BRIEF.md for colors, style, constraints, and references.\n- If no BRIEF.md exists, ask what the brand represents before generating.\n\nLOGO EXPLORATION\n- Start with 1 logo concept. Show it, get feedback, then iterate or try a different approach.\n- Only generate multiple variants when the user asks for options.\n- ALWAYS include the exact brand/company name in the prompt when the logo should contain text.\n- Use Recraft v4 for logos that include text (only model that nails typography).\n- Use Nano Banana for abstract marks and iconic logos.\n- Always remove background after selecting a logo direction.\n\nCOLOR PALETTE\n- Extract colors from the best generation and codify them in BRIEF.md.\n- Use consistent color keywords in all subsequent prompts.\n- Test colors across light and dark backgrounds.\n\nBUILDING THE KIT\n1. Logo (with and without background)\n2. Hero image (wide format, brand aesthetic)\n3. Social media templates (square, story, header sizes)\n4. Pattern or texture (for backgrounds)\n5. Product mockups (logo placed in context)\n\nCONSISTENCY\n- Save good seeds to seeds.json after each successful generation.\n- Reference the logo in subsequent prompts: "in the style of [brand], using [colors]"\n- Keep style keywords identical across all generations.'
+    },
+    "ui-design": {
+      topic: "ui-design",
+      title: "UI/UX Design",
+      content: `How to generate UI designs and interface assets with Gunni:
 
 SCREEN GENERATION
 - Nano Banana excels at generating realistic UI screenshots and mockups.
@@ -3255,143 +3210,31 @@ TIPS
 - Reference specific apps in prompts: "in the style of Linear" or "inspired by Stripe's dashboard"
 - For responsive design, generate the same screen at different widths.
 - Use describe to document what each screen shows for handoff.`
-  },
-  advertising: {
-    topic: "advertising",
-    title: "Ad Creative",
-    content: `How to create advertising assets with Gunni:
-
-CAMPAIGN STRUCTURE
-- Start with the hero image: the single strongest visual.
-- Generate platform-specific sizes from the same concept:
-  - Instagram: 1080x1080 (feed), 1080x1920 (story)
-  - Twitter/X: 1200x675 (post), 1500x500 (header)
-  - YouTube: 1280x720 (thumbnail)
-  - LinkedIn: 1200x627 (post)
-  - OG: 1200x630
-
-A/B TESTING
-- Start with 1 hero image. Only generate additional variants when the user wants to compare options.
-- Keep copy consistent, vary imagery. Or keep imagery consistent, vary composition.
-- Use describe on each to document the differences for the team.
-
-PRODUCT SHOTS
-- Start with a clean product image (generate or use existing).
-- Remove background for a clean cutout.
-- Use edit to place in different lifestyle scenes.
-- Upscale the winners for production use.
-
-VIDEO ADS
-- Generate a compelling still, then create a 5-10 second video.
-- Add voiceover with gunni audio for complete ad packages.
-- Different video styles: zoom in, pan, parallax, subtle motion.
-
-TIPS
-- Ad images should have clear focal points and work at small sizes.
-- Test thumbnails at actual display size (they're often tiny).
-- Keep text minimal in generated images. Add text in post-production or use Recraft v4.`
-  },
-  "product-photo": {
-    topic: "product-photo",
-    title: "Product Photography",
-    content: `How to create product photography with Gunni:
-
-FROM SCRATCH
-1. Generate the product: "ceramic mug, white background, studio lighting, product photography"
-2. Remove background: image --remove-bg
-3. Place in scenes: "place on marble countertop, morning light, coffee beans scattered nearby"
-4. Upscale the final: image --upscale
-
-FROM EXISTING PRODUCT PHOTO
-1. Remove background from the original photo.
-2. Use edit to place in new contexts and lighting.
-3. Generate multiple scene variants with --variants.
-4. Upscale winners.
-
-LIGHTING STYLES
-- "Studio lighting" \u2014 clean, professional, white background
-- "Natural light" \u2014 warm, lifestyle feel
-- "Dramatic lighting" \u2014 moody, high contrast, dark background
-- "Flat lay" \u2014 top-down arrangement with props
-- "Lifestyle" \u2014 product in use, real-world context
-
-SCENE TYPES
-- Hero shot (product as star, minimal background)
-- Lifestyle (product in use context)
-- Detail (close-up of texture, material, craftsmanship)
-- Group (multiple products arranged together)
-- Scale (product next to familiar objects for size reference)
-
-E-COMMERCE
-- Main image: white background, centered product, high resolution.
-- Use describe to generate alt text and product descriptions.
-- Generate 4-6 angles per product for a complete listing.`
-  },
-  video: {
-    topic: "video",
-    title: "Video Generation",
-    content: `How to create effective video content with Gunni:
-
-PROMPT STRUCTURE
-- Include: subject + action + motion style + setting + camera movement.
-- Good: "golden retriever running through autumn leaves, slow motion, tracking shot, warm afternoon light, cinematic"
-- Weak: "dog running"
-
-KLING V3 (default video model)
-- Structure prompts with subject, action, motion, and negative elements.
-- Use negative phrases to prevent common issues: "no flicker, no distortion, no blur".
-- Best for: dynamic scenes with fluid motion, product reveals, character animation.
-- Keep clips under 10 seconds for best quality.
-- Start from a still image for more control (image-to-video).
-
-VEO 3.1
-- Five-part prompt formula: narrative + characters + visuals + audio + camera controls.
-- Avoid quotes in prompts (they can trigger unwanted text rendering).
-- Stick to single scenes in short clips. Use jump-cuts for multi-scene narratives.
-- Specify camera techniques: "dolly zoom", "tracking shot", "aerial pullback".
-
-GENERAL VIDEO TIPS
-- Start with a strong still image first, then animate. More control than text-to-video.
-- Test with 5-second clips before committing to longer generations.
-- Camera motion keywords: "static", "slow pan", "tracking", "dolly", "crane", "handheld".
-- For product videos: start with hero shot, add subtle motion (rotation, parallax, zoom).
-- For social: keep under 6 seconds, strong first frame, works on mute.`
-  },
-  "concept-art": {
-    topic: "concept-art",
-    title: "Concept Art & Illustration",
-    content: `How to create concept art and illustrations with Gunni:
-
-ENVIRONMENT DESIGN
-- Start broad: "Pacific Northwest forest, morning mist, golden hour, cinematic"
-- Refine with edits: add structures, characters, atmospheric effects.
-- Use --variants to explore different moods and lighting for the same scene.
-
-CHARACTER CONCEPTS
-- Generate full-body character designs with clear descriptions.
-- Create expression sheets with edit: same character, different expressions.
-- Use consistent style keywords and seeds across a character series.
-
-ARCHITECTURAL CONCEPTS
-- Specify materials, era, and style: "modern lakehouse, cedar and glass, Olson Kundig inspired"
-- Generate multiple views: exterior, interior, aerial, detail.
-- Use edit to iterate on specific elements without regenerating the whole scene.
-
-ITERATION WORKFLOW
-- Round 1: Generate 1 concept. Show it and get feedback.
-- Round 2: Refine via edit, or try a different direction if needed.
-- Round 3: Use 2-3 variants only when exploring mood/lighting options the user requested.
-- Round 4: Upscale and describe for documentation.
-
-STYLE CONSISTENCY
-- Lock in style keywords early and reuse them.
-- Save the seed from your best generations.
-- Reference previous work in edit prompts: "maintaining the same art style"`
-  },
-  pipelines: {
-    topic: "pipelines",
-    title: "Pipeline Orchestration",
-    content: `How to execute Gunni pipelines. Pipelines are multi-step workflows that chain templates, presets, and tools into complete deliverables.
+    },
+    advertising: {
+      topic: "advertising",
+      title: "Ad Creative",
+      content: "How to create advertising assets with Gunni:\n\nCAMPAIGN STRUCTURE\n- Start with the hero image: the single strongest visual.\n- Generate platform-specific sizes from the same concept:\n  - Instagram: 1080x1080 (feed), 1080x1920 (story)\n  - Twitter/X: 1200x675 (post), 1500x500 (header)\n  - YouTube: 1280x720 (thumbnail)\n  - LinkedIn: 1200x627 (post)\n  - OG: 1200x630\n\nA/B TESTING\n- Start with 1 hero image. Only generate additional variants when the user wants to compare options.\n- Keep copy consistent, vary imagery. Or keep imagery consistent, vary composition.\n- Use describe on each to document the differences for the team.\n\nPRODUCT SHOTS\n- Start with a clean product image (generate or use existing).\n- Remove background for a clean cutout.\n- Use edit to place in different lifestyle scenes.\n- Upscale the winners for production use.\n\nVIDEO ADS\n- Generate a compelling still, then create a 5-10 second video.\n- Add voiceover with gunni audio for complete ad packages.\n- Different video styles: zoom in, pan, parallax, subtle motion.\n\nTIPS\n- Ad images should have clear focal points and work at small sizes.\n- Test thumbnails at actual display size (they're often tiny).\n- Keep text minimal in generated images. Add text in post-production or use Recraft v4."
+    },
+    "product-photo": {
+      topic: "product-photo",
+      title: "Product Photography",
+      content: 'How to create product photography with Gunni:\n\nFROM SCRATCH\n1. Generate the product: "ceramic mug, white background, studio lighting, product photography"\n2. Remove background: image --remove-bg\n3. Place in scenes: "place on marble countertop, morning light, coffee beans scattered nearby"\n4. Upscale the final: image --upscale\n\nFROM EXISTING PRODUCT PHOTO\n1. Remove background from the original photo.\n2. Use edit to place in new contexts and lighting.\n3. Generate multiple scene variants with --variants.\n4. Upscale winners.\n\nLIGHTING STYLES\n- "Studio lighting" \u2014 clean, professional, white background\n- "Natural light" \u2014 warm, lifestyle feel\n- "Dramatic lighting" \u2014 moody, high contrast, dark background\n- "Flat lay" \u2014 top-down arrangement with props\n- "Lifestyle" \u2014 product in use, real-world context\n\nSCENE TYPES\n- Hero shot (product as star, minimal background)\n- Lifestyle (product in use context)\n- Detail (close-up of texture, material, craftsmanship)\n- Group (multiple products arranged together)\n- Scale (product next to familiar objects for size reference)\n\nE-COMMERCE\n- Main image: white background, centered product, high resolution.\n- Use describe to generate alt text and product descriptions.\n- Generate 4-6 angles per product for a complete listing.'
+    },
+    video: {
+      topic: "video",
+      title: "Video Generation",
+      content: 'How to create effective video content with Gunni:\n\nPROMPT STRUCTURE\n- Include: subject + action + motion style + setting + camera movement.\n- Good: "golden retriever running through autumn leaves, slow motion, tracking shot, warm afternoon light, cinematic"\n- Weak: "dog running"\n\nKLING V3 (default video model)\n- Structure prompts with subject, action, motion, and negative elements.\n- Use negative phrases to prevent common issues: "no flicker, no distortion, no blur".\n- Best for: dynamic scenes with fluid motion, product reveals, character animation.\n- Keep clips under 10 seconds for best quality.\n- Start from a still image for more control (image-to-video).\n\nVEO 3.1\n- Five-part prompt formula: narrative + characters + visuals + audio + camera controls.\n- Avoid quotes in prompts (they can trigger unwanted text rendering).\n- Stick to single scenes in short clips. Use jump-cuts for multi-scene narratives.\n- Specify camera techniques: "dolly zoom", "tracking shot", "aerial pullback".\n\nGENERAL VIDEO TIPS\n- Start with a strong still image first, then animate. More control than text-to-video.\n- Test with 5-second clips before committing to longer generations.\n- Camera motion keywords: "static", "slow pan", "tracking", "dolly", "crane", "handheld".\n- For product videos: start with hero shot, add subtle motion (rotation, parallax, zoom).\n- For social: keep under 6 seconds, strong first frame, works on mute.'
+    },
+    "concept-art": {
+      topic: "concept-art",
+      title: "Concept Art & Illustration",
+      content: 'How to create concept art and illustrations with Gunni:\n\nENVIRONMENT DESIGN\n- Start broad: "Pacific Northwest forest, morning mist, golden hour, cinematic"\n- Refine with edits: add structures, characters, atmospheric effects.\n- Use --variants to explore different moods and lighting for the same scene.\n\nCHARACTER CONCEPTS\n- Generate full-body character designs with clear descriptions.\n- Create expression sheets with edit: same character, different expressions.\n- Use consistent style keywords and seeds across a character series.\n\nARCHITECTURAL CONCEPTS\n- Specify materials, era, and style: "modern lakehouse, cedar and glass, Olson Kundig inspired"\n- Generate multiple views: exterior, interior, aerial, detail.\n- Use edit to iterate on specific elements without regenerating the whole scene.\n\nITERATION WORKFLOW\n- Round 1: Generate 1 concept. Show it and get feedback.\n- Round 2: Refine via edit, or try a different direction if needed.\n- Round 3: Use 2-3 variants only when exploring mood/lighting options the user requested.\n- Round 4: Upscale and describe for documentation.\n\nSTYLE CONSISTENCY\n- Lock in style keywords early and reuse them.\n- Save the seed from your best generations.\n- Reference previous work in edit prompts: "maintaining the same art style"'
+    },
+    pipelines: {
+      topic: "pipelines",
+      title: "Pipeline Orchestration",
+      content: `How to execute Gunni pipelines. Pipelines are multi-step workflows that chain templates, presets, and tools into complete deliverables.
 
 DISCOVERY
 - Call pipelines() to list available pipelines with names and descriptions
@@ -3437,8 +3280,23 @@ KEY PRINCIPLES
 - Use refs to chain outputs: step 1 output becomes step 2 input via input_refs.
 - The preset auto-applies to every generation. Don't manually add framing/suffix.
 - Assembly notes (the text step) should include: edit sequence, scene order, timing, text overlay copy, CTAs.`
+    }
+  },
+  latest: {
+    version: "0.2.0",
+    date: "2026-02-22",
+    updates: [
+      "Unified image tool: generate, edit, describe, upscale, remove-bg. Routes by input.",
+      "Multi-image editing: pass array of URLs for multi-ref edits (flux-kontext, flux-2-pro-edit, nano-banana-edit, gpt-image-edit).",
+      "Ref system: ref_save + refs for saving/retrieving reference images.",
+      "Variants flag for creative exploration.",
+      "Latest updates merged into models (pass updates=true). refs now handles both list and get."
+    ]
   }
 };
+
+// src/core/knowledge.ts
+var TOPICS = knowledge_default.topics;
 function getLearnContent(topic) {
   if (!topic || topic === "overview") {
     return TOPICS.overview;
@@ -3451,17 +3309,7 @@ function getAvailableTopics() {
   return Object.keys(TOPICS);
 }
 function getLatestUpdates() {
-  return {
-    version: "0.2.0",
-    date: "2026-02-22",
-    updates: [
-      "Unified image tool: generate, edit, describe, upscale, remove-bg. Routes by input.",
-      "Multi-image editing: pass array of URLs for multi-ref edits (flux-kontext, flux-2-pro-edit, nano-banana-edit, gpt-image-edit).",
-      "Ref system: ref_save + refs for saving/retrieving reference images.",
-      "Variants flag for creative exploration.",
-      "Latest updates merged into models (pass updates=true). refs now handles both list and get."
-    ]
-  };
+  return knowledge_default.latest;
 }
 
 // src/commands/learn.ts
@@ -3852,12 +3700,10 @@ async function interactiveConfig(configManager, json) {
 }
 
 // src/commands/list.ts
-init_model_registry();
 import pc12 from "picocolors";
 
-// src/core/guide-registry.ts
-var GUIDES = [
-  // --- Branding ---
+// data/guides.json
+var guides_default = [
   {
     id: "brand-moodboard",
     title: "Brand Mood Board",
@@ -3897,15 +3743,7 @@ var GUIDES = [
         description: "Upscale the final mood board to presentation quality."
       }
     ],
-    tags: [
-      "brand",
-      "moodboard",
-      "mood-board",
-      "identity",
-      "grid",
-      "palette",
-      "branding"
-    ]
+    tags: ["brand", "moodboard", "mood-board", "identity", "grid", "palette", "branding"]
   },
   {
     id: "logo-concepts",
@@ -3948,15 +3786,7 @@ var GUIDES = [
         description: "Upscale final logo to high resolution."
       }
     ],
-    tags: [
-      "logo",
-      "brand",
-      "identity",
-      "mark",
-      "wordmark",
-      "vector",
-      "design"
-    ]
+    tags: ["logo", "brand", "identity", "mark", "wordmark", "vector", "design"]
   },
   {
     id: "color-palette-exploration",
@@ -3990,28 +3820,14 @@ var GUIDES = [
         description: "Generate a pattern using the palette to test it in a graphic design context."
       }
     ],
-    tags: [
-      "color",
-      "palette",
-      "colors",
-      "swatches",
-      "scheme",
-      "brand",
-      "design"
-    ]
+    tags: ["color", "palette", "colors", "swatches", "scheme", "brand", "design"]
   },
-  // --- Product ---
   {
     id: "product-photography",
     title: "Product Photography Pipeline",
     description: "Generate a product shot, remove its background, composite onto a scene, and upscale for production use.",
     category: "product",
-    models: [
-      "flux-2-pro",
-      "bria-bg-remove",
-      "flux-kontext",
-      "topaz-upscale"
-    ],
+    models: ["flux-2-pro", "bria-bg-remove", "flux-kontext", "topaz-upscale"],
     promptTemplate: "Professional product photography of {product_description}. {lighting_style} lighting, {surface_description} surface, {angle} angle. Sharp focus, commercial quality, 8K detail.",
     tips: [
       "Flux 2 Pro produces the most photorealistic product shots out of the box.",
@@ -4049,16 +3865,8 @@ var GUIDES = [
         description: "Verify the final image quality and composition before delivery."
       }
     ],
-    tags: [
-      "product",
-      "photography",
-      "ecommerce",
-      "packshot",
-      "studio",
-      "commercial"
-    ]
+    tags: ["product", "photography", "ecommerce", "packshot", "studio", "commercial"]
   },
-  // --- Social Media ---
   {
     id: "social-media-assets",
     title: "Social Media Asset Creation",
@@ -4094,29 +3902,14 @@ var GUIDES = [
         description: "Analyze the generated asset to verify brand alignment and visual quality."
       }
     ],
-    tags: [
-      "social",
-      "instagram",
-      "facebook",
-      "twitter",
-      "story",
-      "post",
-      "banner",
-      "marketing"
-    ]
+    tags: ["social", "instagram", "facebook", "twitter", "story", "post", "banner", "marketing"]
   },
-  // --- Iteration ---
   {
     id: "image-refinement",
     title: "Image Refinement and Iteration",
     description: "Systematically improve an image through describe-edit-verify cycles.",
     category: "iteration",
-    models: [
-      "florence-2",
-      "flux-kontext",
-      "nano-banana-edit",
-      "topaz-upscale"
-    ],
+    models: ["florence-2", "flux-kontext", "nano-banana-edit", "topaz-upscale"],
     promptTemplate: "This is a refinement workflow, not a single prompt. Start with gunni describe, then edit based on the analysis.",
     tips: [
       "Always describe before editing \u2014 the description reveals issues you might not notice visually.",
@@ -4156,17 +3949,8 @@ var GUIDES = [
         description: "Upscale the refined image to final production quality."
       }
     ],
-    tags: [
-      "refine",
-      "iterate",
-      "improve",
-      "fix",
-      "edit",
-      "quality",
-      "polish"
-    ]
+    tags: ["refine", "iterate", "improve", "fix", "edit", "quality", "polish"]
   },
-  // --- Workflow ---
   {
     id: "hero-image-pipeline",
     title: "Hero Image Pipeline",
@@ -4203,17 +3987,12 @@ var GUIDES = [
         description: "Upscale to retina/4K resolution for high-DPI screens."
       }
     ],
-    tags: [
-      "hero",
-      "banner",
-      "website",
-      "marketing",
-      "campaign",
-      "landing-page",
-      "header"
-    ]
+    tags: ["hero", "banner", "website", "marketing", "campaign", "landing-page", "header"]
   }
 ];
+
+// src/core/guide-registry.ts
+var GUIDES = guides_default;
 function getAllGuides() {
   return GUIDES;
 }
@@ -5726,532 +5505,9 @@ ${pc19.dim("Save as ref: gunni ref add <url> --name <name>")}
   });
 }
 
-// src/commands/generate.ts
+// src/ui/onboarding.ts
 import * as clack3 from "@clack/prompts";
 import pc20 from "picocolors";
-var DEFAULT_MODEL4 = "flux-2-pro";
-function registerGenerateCommand(program2) {
-  program2.command("generate").description("Generate an image from a text prompt").argument("[prompt]", "Text prompt for image generation").option("-m, --model <model>", "Model to use (see: gunni list models --type image)", DEFAULT_MODEL4).option("-o, --output <path>", "Output file path (default: auto-generated)").option("--width <pixels>", "Image width in pixels", parseInt).option("--height <pixels>", "Image height in pixels", parseInt).option("--seed <number>", "Random seed for reproducibility", parseInt).addHelpText(
-    "after",
-    `
-Examples:
-
-  Interactive mode (guided walkthrough):
-    $ gunni generate
-
-  Direct mode:
-    $ gunni generate "a ceramic mug on a wooden table, morning light"
-    $ gunni generate "a cat" --model flux-dev -o cat.png
-    $ gunni generate "hero banner" --width 1920 --height 1080 -o hero.png
-    $ gunni generate "abstract art" --seed 42 -o art.png
-
-  Agent usage (structured JSON output):
-    $ gunni --json generate "product photo" --model flux-2-pro -o product.png
-
-    Returns: { images: [{ path, url, width, height }], seed, requestId, model, prompt }
-
-  Reproduce a previous generation:
-    $ gunni generate "same prompt" --seed 12345 --model flux-2-pro -o v2.png
-
-Available image models: flux-2-pro (default), flux-dev, flux-2-flex, grok-imagine, recraft-v4
-Run 'gunni list models --type image' for details.
-`
-  ).action(async (prompt, opts) => {
-    const json = program2.opts().json ?? false;
-    try {
-      let finalPrompt;
-      let finalModel;
-      let finalOutput;
-      let width = opts.width;
-      let height = opts.height;
-      let seed = opts.seed;
-      if (prompt) {
-        finalPrompt = prompt;
-        finalModel = opts.model;
-        finalOutput = opts.output ?? generateDefaultFilename(finalModel);
-      } else {
-        if (json) {
-          throw new GunniError(
-            "Prompt is required with --json",
-            "MISSING_PROMPT"
-          );
-        }
-        const interactive = await interactiveFlow(opts.model);
-        finalPrompt = interactive.prompt;
-        finalModel = interactive.model;
-        finalOutput = interactive.output;
-        width = interactive.width ?? width;
-        height = interactive.height ?? height;
-        seed = interactive.seed ?? seed;
-      }
-      const router = new ModelRouter();
-      const result = await router.generate({
-        prompt: finalPrompt,
-        model: finalModel,
-        outputPath: finalOutput,
-        width,
-        height,
-        seed,
-        showSpinner: !json
-      });
-      const img = result.images[0];
-      logGeneration({
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        command: "generate",
-        model: result.model,
-        prompt: result.prompt,
-        outputPath: img.path,
-        outputUrl: img.url,
-        seed: result.seed,
-        width: img.width,
-        height: img.height,
-        requestId: result.requestId
-      }).catch(() => {
-      });
-      console.log(formatGenerateResult(result, json));
-    } catch (err) {
-      if (clack3.isCancel(err)) {
-        clack3.cancel("Generation cancelled.");
-        process.exit(0);
-      }
-      console.error(formatError(err, json));
-      process.exit(1);
-    }
-  });
-}
-async function interactiveFlow(defaultModel) {
-  clack3.intro(pc20.bold("gunni generate"));
-  const prompt = await clack3.text({
-    message: "What do you want to generate?",
-    placeholder: "A ceramic mug on a wooden table, morning light",
-    validate: (val) => {
-      if (!val.trim()) return "Prompt cannot be empty";
-    }
-  });
-  if (clack3.isCancel(prompt)) throw prompt;
-  const { getModelsByCategory: getModelsByCategory2 } = await Promise.resolve().then(() => (init_model_registry(), model_registry_exports));
-  const imageModels = getModelsByCategory2("image");
-  const model = await clack3.select({
-    message: "Which model?",
-    options: imageModels.map((m) => ({
-      value: m.id,
-      label: m.name,
-      hint: m.id === defaultModel ? "default" : m.description
-    })),
-    initialValue: defaultModel
-  });
-  if (clack3.isCancel(model)) throw model;
-  let width;
-  let height;
-  let seed;
-  const advanced = await clack3.confirm({
-    message: "Configure advanced options?",
-    initialValue: false
-  });
-  if (clack3.isCancel(advanced)) throw advanced;
-  if (advanced) {
-    const seedInput = await clack3.text({
-      message: "Seed (leave blank for random):",
-      placeholder: "42"
-    });
-    if (clack3.isCancel(seedInput)) throw seedInput;
-    if (seedInput) seed = parseInt(seedInput, 10);
-    const widthInput = await clack3.text({
-      message: "Width in pixels (leave blank for default):",
-      placeholder: "1024"
-    });
-    if (clack3.isCancel(widthInput)) throw widthInput;
-    if (widthInput) width = parseInt(widthInput, 10);
-    const heightInput = await clack3.text({
-      message: "Height in pixels (leave blank for default):",
-      placeholder: "1024"
-    });
-    if (clack3.isCancel(heightInput)) throw heightInput;
-    if (heightInput) height = parseInt(heightInput, 10);
-  }
-  const output = await clack3.text({
-    message: "Output file path:",
-    defaultValue: generateDefaultFilename(model),
-    placeholder: generateDefaultFilename(model)
-  });
-  if (clack3.isCancel(output)) throw output;
-  clack3.log.step("Starting generation\u2026");
-  return {
-    prompt,
-    model,
-    output: output || generateDefaultFilename(model),
-    width,
-    height,
-    seed
-  };
-}
-function generateDefaultFilename(model) {
-  const timestamp = Date.now();
-  return `gunni-${model}-${timestamp}.png`;
-}
-
-// src/commands/edit.ts
-import ora6 from "ora";
-init_model_registry();
-import pc21 from "picocolors";
-var DEFAULT_MODEL5 = "flux-kontext";
-function registerEditCommand(program2) {
-  program2.command("edit").description("Edit an image with text instructions").argument("<image>", "Path to input image").argument("<prompt>", "Edit instructions").option("-m, --model <model>", "Model to use (see: gunni list models --type edit)", DEFAULT_MODEL5).option("-o, --output <path>", "Output file path (default: auto-generated)").addHelpText(
-    "after",
-    `
-Examples:
-
-  Basic editing:
-    $ gunni edit photo.png "make the lighting warmer"
-    $ gunni edit logo.png "place on a coffee cup mockup, studio lighting" -o mockup.png
-    $ gunni edit hero.png "add subtle film grain and warmer tones" -o hero-v2.png
-
-  Chaining with generate:
-    $ gunni generate "a ceramic mug on a table" -o mug.png
-    $ gunni edit mug.png "add steam rising from the mug, morning light" -o mug-final.png
-
-  Agent usage (structured JSON output):
-    $ gunni --json edit input.png "make it more vibrant" -o output.png
-
-    Returns: { image: { path, url, width, height }, model, prompt, inputImage }
-
-Available edit models: flux-kontext (default), grok-edit
-Run 'gunni list models --type edit' for details.
-`
-  ).action(async (image, prompt, opts) => {
-    const json = program2.opts().json ?? false;
-    try {
-      const spinner = json ? void 0 : ora6("Starting\u2026").start();
-      const update = (s) => {
-        if (spinner) spinner.text = s;
-      };
-      const imageUrl = await uploadToFal(image, update);
-      update("Editing\u2026");
-      const provider = new FalProvider();
-      const result = await provider.call(
-        getEndpoint2(opts.model ?? DEFAULT_MODEL5),
-        { image_url: imageUrl, prompt },
-        update
-      );
-      const data = result.data;
-      const img = data.images?.[0];
-      if (!img) {
-        spinner?.fail("No image returned");
-        throw new GunniError("No image in response", "NO_IMAGE");
-      }
-      const requestedPath = opts.output ?? `gunni-edit-${Date.now()}.png`;
-      const finalPath = await downloadImage(img.url, requestedPath, update);
-      spinner?.succeed("Done");
-      const output = {
-        image: {
-          path: finalPath,
-          url: img.url,
-          width: img.width ?? 0,
-          height: img.height ?? 0
-        },
-        model: opts.model ?? DEFAULT_MODEL5,
-        prompt,
-        inputImage: image
-      };
-      logGeneration({
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        command: "edit",
-        model: output.model,
-        prompt,
-        inputImage: image,
-        outputPath: finalPath,
-        outputUrl: img.url,
-        width: output.image.width,
-        height: output.image.height
-      }).catch(() => {
-      });
-      if (json) {
-        console.log(JSON.stringify(output, null, 2));
-      } else {
-        console.log(`${pc21.green("\u2714")} Edited image saved to ${pc21.bold(finalPath)}`);
-        console.log(`  ${pc21.dim(`${output.image.width}\xD7${output.image.height} \xB7 ${output.model}`)}`);
-      }
-    } catch (err) {
-      console.error(formatError(err, json));
-      process.exit(1);
-    }
-  });
-}
-function getEndpoint2(modelId) {
-  const model = getModel(modelId);
-  if (!model) {
-    throw new GunniError(
-      `Unknown model: ${modelId}`,
-      "UNKNOWN_MODEL",
-      "Run `gunni list models --type edit` to see available models."
-    );
-  }
-  return model.endpoint;
-}
-
-// src/commands/describe.ts
-import ora7 from "ora";
-init_model_registry();
-var DEFAULT_MODEL6 = "florence-2";
-function registerDescribeCommand(program2) {
-  program2.command("describe").description("Describe an image (image-to-text)").argument("<image>", "Path to image file").option("-m, --model <model>", "Model to use", DEFAULT_MODEL6).addHelpText(
-    "after",
-    `
-Examples:
-
-  Describe an image:
-    $ gunni describe photo.png
-    $ gunni describe logo.png --model florence-2
-
-  Agent usage \u2014 understand what was generated, then iterate:
-    $ gunni generate "a logo for a coffee brand" -o logo.png
-    $ gunni --json describe logo.png
-    $ gunni edit logo.png "make the colors warmer" -o logo-v2.png
-
-  Structured JSON output:
-    $ gunni --json describe image.png
-
-    Returns: { description, model, inputImage }
-`
-  ).action(async (image, opts) => {
-    const json = program2.opts().json ?? false;
-    try {
-      const spinner = json ? void 0 : ora7("Starting\u2026").start();
-      const update = (s) => {
-        if (spinner) spinner.text = s;
-      };
-      const modelId = opts.model ?? DEFAULT_MODEL6;
-      const modelDef = getModel(modelId);
-      if (!modelDef) {
-        spinner?.fail();
-        throw new GunniError(
-          `Unknown model: ${modelId}`,
-          "UNKNOWN_MODEL",
-          "Run `gunni list models --type describe` to see available models."
-        );
-      }
-      const imageUrl = await uploadToFal(image, update);
-      update("Analyzing\u2026");
-      const provider = new FalProvider();
-      const result = await provider.call(
-        modelDef.endpoint,
-        { image_url: imageUrl },
-        update
-      );
-      const data = result.data;
-      const description = data.results ?? "";
-      spinner?.succeed("Done");
-      const output = {
-        description,
-        model: modelId,
-        inputImage: image
-      };
-      logGeneration({
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        command: "describe",
-        model: modelId,
-        inputImage: image,
-        outputPath: image,
-        metadata: { description }
-      }).catch(() => {
-      });
-      if (json) {
-        console.log(JSON.stringify(output, null, 2));
-      } else {
-        console.log(description);
-      }
-    } catch (err) {
-      console.error(formatError(err, json));
-      process.exit(1);
-    }
-  });
-}
-
-// src/commands/upscale.ts
-import ora8 from "ora";
-init_model_registry();
-import pc22 from "picocolors";
-var DEFAULT_MODEL7 = "topaz-upscale";
-function registerUpscaleCommand(program2) {
-  program2.command("upscale").description("Upscale an image to higher resolution").argument("<image>", "Path to input image").option("-o, --output <path>", "Output file path (default: auto-generated)").option("-s, --scale <factor>", "Scale factor (2 or 4)", parseInt, 2).option("-m, --model <model>", "Model to use", DEFAULT_MODEL7).addHelpText(
-    "after",
-    `
-Examples:
-
-  Upscale an image:
-    $ gunni upscale photo.png -o photo-hires.png
-    $ gunni upscale draft.png --scale 4 -o final.png
-
-  Chain with generate for production quality:
-    $ gunni generate "product photo" -o draft.png
-    $ gunni upscale draft.png -o production.png
-
-  Agent usage:
-    $ gunni --json upscale image.png -o hires.png
-
-    Returns: { image: { path, url, width, height }, scale, model, inputImage }
-`
-  ).action(async (image, opts) => {
-    const json = program2.opts().json ?? false;
-    try {
-      const spinner = json ? void 0 : ora8("Starting\u2026").start();
-      const update = (s) => {
-        if (spinner) spinner.text = s;
-      };
-      const modelId = opts.model ?? DEFAULT_MODEL7;
-      const modelDef = getModel(modelId);
-      if (!modelDef) {
-        spinner?.fail();
-        throw new GunniError(`Unknown model: ${modelId}`, "UNKNOWN_MODEL");
-      }
-      const imageUrl = await uploadToFal(image, update);
-      update("Upscaling\u2026");
-      const provider = new FalProvider();
-      const result = await provider.call(
-        modelDef.endpoint,
-        { image_url: imageUrl, scale: opts.scale },
-        update
-      );
-      const data = result.data;
-      const img = data.image;
-      if (!img) {
-        spinner?.fail("No image returned");
-        throw new GunniError("No image in response", "NO_IMAGE");
-      }
-      const requestedPath = opts.output ?? `gunni-upscale-${Date.now()}.png`;
-      const finalPath = await downloadImage(img.url, requestedPath, update);
-      spinner?.succeed("Done");
-      const output = {
-        image: {
-          path: finalPath,
-          url: img.url,
-          width: img.width ?? 0,
-          height: img.height ?? 0
-        },
-        scale: opts.scale,
-        model: modelId,
-        inputImage: image
-      };
-      logGeneration({
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        command: "upscale",
-        model: modelId,
-        inputImage: image,
-        outputPath: finalPath,
-        outputUrl: img.url,
-        width: output.image.width,
-        height: output.image.height,
-        metadata: { scale: opts.scale }
-      }).catch(() => {
-      });
-      if (json) {
-        console.log(JSON.stringify(output, null, 2));
-      } else {
-        console.log(`${pc22.green("\u2714")} Upscaled image saved to ${pc22.bold(finalPath)}`);
-        console.log(`  ${pc22.dim(`${output.image.width}\xD7${output.image.height} \xB7 ${opts.scale}x \xB7 ${modelId}`)}`);
-      }
-    } catch (err) {
-      console.error(formatError(err, json));
-      process.exit(1);
-    }
-  });
-}
-
-// src/commands/remove-bg.ts
-import ora9 from "ora";
-init_model_registry();
-import pc23 from "picocolors";
-var DEFAULT_MODEL8 = "bria-bg-remove";
-function registerRemoveBgCommand(program2) {
-  program2.command("remove-bg").description("Remove background from an image").argument("<image>", "Path to input image").option("-o, --output <path>", "Output file path (default: auto-generated)").option("-m, --model <model>", "Model to use", DEFAULT_MODEL8).addHelpText(
-    "after",
-    `
-Examples:
-
-  Remove background:
-    $ gunni remove-bg product.png -o product-clean.png
-    $ gunni remove-bg photo.jpg -o cutout.png
-
-  Chain with other commands:
-    $ gunni generate "a coffee bag product shot" -o bag.png
-    $ gunni remove-bg bag.png -o bag-clean.png
-    $ gunni edit bag-clean.png "place on a marble countertop" -o final.png
-
-  Agent usage:
-    $ gunni --json remove-bg input.png -o output.png
-
-    Returns: { image: { path, url, width, height }, model, inputImage }
-`
-  ).action(async (image, opts) => {
-    const json = program2.opts().json ?? false;
-    try {
-      const spinner = json ? void 0 : ora9("Starting\u2026").start();
-      const update = (s) => {
-        if (spinner) spinner.text = s;
-      };
-      const modelId = opts.model ?? DEFAULT_MODEL8;
-      const modelDef = getModel(modelId);
-      if (!modelDef) {
-        spinner?.fail();
-        throw new GunniError(`Unknown model: ${modelId}`, "UNKNOWN_MODEL");
-      }
-      const imageUrl = await uploadToFal(image, update);
-      update("Removing background\u2026");
-      const provider = new FalProvider();
-      const result = await provider.call(
-        modelDef.endpoint,
-        { image_url: imageUrl },
-        update
-      );
-      const data = result.data;
-      const img = data.image;
-      if (!img) {
-        spinner?.fail("No image returned");
-        throw new GunniError("No image in response", "NO_IMAGE");
-      }
-      const requestedPath = opts.output ?? `gunni-nobg-${Date.now()}.png`;
-      const finalPath = await downloadImage(img.url, requestedPath, update);
-      spinner?.succeed("Done");
-      const output = {
-        image: {
-          path: finalPath,
-          url: img.url,
-          width: img.width ?? 0,
-          height: img.height ?? 0
-        },
-        model: modelId,
-        inputImage: image
-      };
-      logGeneration({
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        command: "remove-bg",
-        model: modelId,
-        inputImage: image,
-        outputPath: finalPath,
-        outputUrl: img.url,
-        width: output.image.width,
-        height: output.image.height
-      }).catch(() => {
-      });
-      if (json) {
-        console.log(JSON.stringify(output, null, 2));
-      } else {
-        console.log(`${pc23.green("\u2714")} Background removed, saved to ${pc23.bold(finalPath)}`);
-        console.log(`  ${pc23.dim(`${output.image.width}\xD7${output.image.height} \xB7 ${modelId}`)}`);
-      }
-    } catch (err) {
-      console.error(formatError(err, json));
-      process.exit(1);
-    }
-  });
-}
-
-// src/index.ts
-init_model_registry();
-
-// src/ui/onboarding.ts
-import * as clack4 from "@clack/prompts";
-import pc24 from "picocolors";
 async function hasGunniKey() {
   const config = new ConfigManager();
   const key = await config.getGunniApiKey();
@@ -6259,47 +5515,47 @@ async function hasGunniKey() {
 }
 async function runOnboarding() {
   console.log("");
-  console.log(pc24.bold("Welcome to Gunni") + pc24.dim(" \u2014 AI media toolkit"));
+  console.log(pc20.bold("Welcome to Gunni") + pc20.dim(" \u2014 AI media toolkit"));
   console.log("");
   console.log("  Generate images, video, and audio from your terminal.");
   console.log("  One API key. 17 curated models. Zero config.");
   console.log("");
-  console.log(`  Opening ${pc24.bold("gunni.ai/keys")} in your browser...`);
+  console.log(`  Opening ${pc20.bold("gunni.ai/keys")} in your browser...`);
   console.log(`  Sign up (or log in), create an API key, and paste it below.`);
   console.log("");
   openUrl("https://gunni.ai/keys");
-  const apiKey = await clack4.text({
+  const apiKey = await clack3.text({
     message: "Paste your Gunni API key:",
     placeholder: "gn_live_...",
     validate: (val) => {
       if (!val.trim()) return "API key cannot be empty";
     }
   });
-  if (clack4.isCancel(apiKey)) return false;
+  if (clack3.isCancel(apiKey)) return false;
   const config = new ConfigManager();
   await config.setGunniApiKey(apiKey);
   console.log("");
-  console.log(`  ${pc24.green("\u2714")} API key saved. You're ready to go.`);
+  console.log(`  ${pc20.green("\u2714")} API key saved. You're ready to go.`);
   console.log("");
-  console.log(`  ${pc24.bold("Commands:")}`);
-  console.log(`    ${pc24.cyan("image")}    Generate, edit, describe, upscale, remove-bg`);
-  console.log(`    ${pc24.cyan("video")}    Image or text to video`);
-  console.log(`    ${pc24.cyan("audio")}    Text to speech`);
-  console.log(`    ${pc24.cyan("learn")}    Creative expertise and best practices`);
-  console.log(`    ${pc24.cyan("config")}   Manage API keys`);
+  console.log(`  ${pc20.bold("Commands:")}`);
+  console.log(`    ${pc20.cyan("image")}    Generate, edit, describe, upscale, remove-bg`);
+  console.log(`    ${pc20.cyan("video")}    Image or text to video`);
+  console.log(`    ${pc20.cyan("audio")}    Text to speech`);
+  console.log(`    ${pc20.cyan("learn")}    Creative expertise and best practices`);
+  console.log(`    ${pc20.cyan("config")}   Manage API keys`);
   console.log("");
-  console.log(`  ${pc24.bold("Quick start:")}`);
-  console.log(`    ${pc24.dim("$")} gunni image "coffee bag product shot" -o bag.png`);
-  console.log(`    ${pc24.dim("$")} gunni image bag.png --remove-bg -o bag-clean.png`);
-  console.log(`    ${pc24.dim("$")} gunni image bag-clean.png "on marble counter" -o hero.png`);
-  console.log(`    ${pc24.dim("$")} gunni video hero.png -p "slow cinematic zoom" -o hero.mp4`);
+  console.log(`  ${pc20.bold("Quick start:")}`);
+  console.log(`    ${pc20.dim("$")} gunni image "coffee bag product shot" -o bag.png`);
+  console.log(`    ${pc20.dim("$")} gunni image bag.png --remove-bg -o bag-clean.png`);
+  console.log(`    ${pc20.dim("$")} gunni image bag-clean.png "on marble counter" -o hero.png`);
+  console.log(`    ${pc20.dim("$")} gunni video hero.png -p "slow cinematic zoom" -o hero.mp4`);
   console.log("");
   return true;
 }
 
 // src/index.ts
 var program = new Command();
-program.name("gunni").description("AI media toolkit \u2014 give any agent the ability to create professional media").version("0.2.0").option("--json", "Output results as JSON").addHelpText(
+program.name("gunni").description("AI media toolkit \u2014 give any agent the ability to create professional media").version("0.3.3").option("--json", "Output results as JSON").addHelpText(
   "after",
   `
 Examples:
@@ -6343,6 +5599,32 @@ registerInitCommand(program);
 registerHistoryCommand(program);
 registerConfigCommand(program);
 registerListCommand(program);
+program.command("models").description("List available models (alias for: gunni list models)").option("-t, --type <category>", "Filter by category").action((opts) => {
+  const json = program.opts().json ?? false;
+  const models = opts.type ? getModelsByCategory(opts.type) : getAllModels();
+  if (json) {
+    console.log(JSON.stringify(models, null, 2));
+    return;
+  }
+  if (models.length === 0) {
+    console.log(`No models found${opts.type ? ` for category "${opts.type}"` : ""}.`);
+    return;
+  }
+  const grouped = /* @__PURE__ */ new Map();
+  for (const model of models) {
+    const list = grouped.get(model.category) ?? [];
+    list.push(model);
+    grouped.set(model.category, list);
+  }
+  for (const [category, catModels] of grouped) {
+    console.log(`
+${category.toUpperCase()}`);
+    for (const m of catModels) {
+      console.log(`  ${m.id}  ${m.description}`);
+    }
+  }
+  console.log();
+});
 registerGuideCommand(program);
 registerRefCommand(program);
 registerStyleCommand(program);
@@ -6350,11 +5632,6 @@ registerTemplateCommand(program);
 registerPresetCommand(program);
 registerPipelineCommand(program);
 registerResearchCommand(program);
-registerGenerateCommand(program);
-registerEditCommand(program);
-registerDescribeCommand(program);
-registerUpscaleCommand(program);
-registerRemoveBgCommand(program);
 program.action(async () => {
   const json = program.opts().json ?? false;
   if (json) {
@@ -6371,7 +5648,7 @@ program.action(async () => {
       { name: "list models", usage: "gunni list models [--type <category>]", description: "List available models" },
       { name: "config", usage: "gunni config", description: "Manage API keys" }
     ];
-    console.log(JSON.stringify({ version: "0.2.0", commands, categories, models }, null, 2));
+    console.log(JSON.stringify({ version: "0.3.3", commands, categories, models }, null, 2));
     return;
   }
   const configured = await hasGunniKey();
@@ -6381,49 +5658,49 @@ program.action(async () => {
     return;
   }
   console.log(`
-${pc25.bold("GUNNI")} ${pc25.dim("v0.2.0")} \u2014 AI media toolkit
-
-${pc25.bold("Media:")}
-  ${pc25.cyan("image")}       Generate, edit, describe, upscale, remove-bg   ${pc25.dim('gunni image "a cat" -o cat.png')}
-  ${pc25.cyan("video")}       Image/text \u2192 video                             ${pc25.dim('gunni video hero.png -p "zoom in"')}
-  ${pc25.cyan("audio")}       Text \u2192 speech                                  ${pc25.dim('gunni audio "Hello" -o hello.mp3')}
-
-${pc25.bold("Production:")}
-  ${pc25.cyan("template")}    Browse & manage prompt templates                ${pc25.dim("gunni template list --category ugc")}
-  ${pc25.cyan("preset")}      Platform presets (framing, aspect ratio)        ${pc25.dim("gunni preset get tiktok-ugc")}
-  ${pc25.cyan("pipeline")}    Multi-step production workflows                 ${pc25.dim("gunni pipeline get ugc-product-reel")}
-  ${pc25.cyan("style")}       Visual styles (brand identity)                  ${pc25.dim("gunni style list")}
-
-${pc25.bold("Context:")}
-  ${pc25.cyan("learn")}       Creative expertise & best practices             ${pc25.dim("gunni learn exploration")}
-  ${pc25.cyan("latest")}      New models, features, updates                   ${pc25.dim("gunni latest")}
-
-${pc25.bold("Utility:")}
-  ${pc25.cyan("init")}        Start a new project                             ${pc25.dim("gunni init --template brand")}
-  ${pc25.cyan("history")}     Search past work                                ${pc25.dim('gunni history "coffee"')}
-  ${pc25.cyan("list")}        Discover models                                 ${pc25.dim("gunni list models")}
-  ${pc25.cyan("config")}      API key setup                                   ${pc25.dim("gunni config")}
-
-${pc25.bold("Models:")} ${pc25.dim(`${getAllModels().length} curated models`)}`);
+${pc21.bold("GUNNI")} ${pc21.dim("v0.3.0")} \u2014 AI media toolkit
+
+${pc21.bold("Media:")}
+  ${pc21.cyan("image")}       Generate, edit, describe, upscale, remove-bg   ${pc21.dim('gunni image "a cat" -o cat.png')}
+  ${pc21.cyan("video")}       Image/text \u2192 video                             ${pc21.dim('gunni video hero.png -p "zoom in"')}
+  ${pc21.cyan("audio")}       Text \u2192 speech                                  ${pc21.dim('gunni audio "Hello" -o hello.mp3')}
+
+${pc21.bold("Production:")}
+  ${pc21.cyan("template")}    Browse & manage prompt templates                ${pc21.dim("gunni template list --category ugc")}
+  ${pc21.cyan("preset")}      Platform presets (framing, aspect ratio)        ${pc21.dim("gunni preset get tiktok-ugc")}
+  ${pc21.cyan("pipeline")}    Multi-step production workflows                 ${pc21.dim("gunni pipeline get ugc-product-reel")}
+  ${pc21.cyan("style")}       Visual styles (brand identity)                  ${pc21.dim("gunni style list")}
+
+${pc21.bold("Context:")}
+  ${pc21.cyan("learn")}       Creative expertise & best practices             ${pc21.dim("gunni learn exploration")}
+  ${pc21.cyan("latest")}      New models, features, updates                   ${pc21.dim("gunni latest")}
+
+${pc21.bold("Utility:")}
+  ${pc21.cyan("init")}        Start a new project                             ${pc21.dim("gunni init --template brand")}
+  ${pc21.cyan("history")}     Search past work                                ${pc21.dim('gunni history "coffee"')}
+  ${pc21.cyan("list")}        Discover models                                 ${pc21.dim("gunni list models")}
+  ${pc21.cyan("config")}      API key setup                                   ${pc21.dim("gunni config")}
+
+${pc21.bold("Models:")} ${pc21.dim(`${getAllModels().length} curated models`)}`);
   for (const cat of getCategories()) {
     const models = getModelsByCategory(cat);
     const defaultModel = models.find((m) => m.isDefault);
     const others = models.filter((m) => m !== defaultModel);
     if (defaultModel) {
-      console.log(`  ${pc25.bold(cat.toUpperCase())} ${pc25.dim("\u2014")} ${pc25.cyan(defaultModel.id)}${others.length ? pc25.dim(`, ${others.map((m) => m.id).join(", ")}`) : ""}`);
+      console.log(`  ${pc21.bold(cat.toUpperCase())} ${pc21.dim("\u2014")} ${pc21.cyan(defaultModel.id)}${others.length ? pc21.dim(`, ${others.map((m) => m.id).join(", ")}`) : ""}`);
     } else {
-      console.log(`  ${pc25.bold(cat.toUpperCase())} ${pc25.dim("\u2014")} ${models.map((m) => m.id).join(", ")}`);
+      console.log(`  ${pc21.bold(cat.toUpperCase())} ${pc21.dim("\u2014")} ${models.map((m) => m.id).join(", ")}`);
     }
   }
   console.log(`
-${pc25.bold("Quick start:")}
-  ${pc25.dim("$")} gunni image "coffee bag product shot" -o bag.png
-  ${pc25.dim("$")} gunni image bag.png --remove-bg -o bag-clean.png
-  ${pc25.dim("$")} gunni image bag-clean.png "on marble counter" -o hero.png
-  ${pc25.dim("$")} gunni image hero.png --upscale -o hero-final.png
-
-${pc25.dim("Add --json to any command for structured output.")}
-${pc25.dim("Run gunni learn to load creative expertise.")}
+${pc21.bold("Quick start:")}
+  ${pc21.dim("$")} gunni image "coffee bag product shot" -o bag.png
+  ${pc21.dim("$")} gunni image bag.png --remove-bg -o bag-clean.png
+  ${pc21.dim("$")} gunni image bag-clean.png "on marble counter" -o hero.png
+  ${pc21.dim("$")} gunni image hero.png --upscale -o hero-final.png
+
+${pc21.dim("Add --json to any command for structured output.")}
+${pc21.dim("Run gunni learn to load creative expertise.")}
 `);
 });
 process.on("uncaughtException", (err) => {