fluxflow-cli 1.4.2 → 1.5.0

package/ARCHITECTURE.md

@@ -29,6 +29,15 @@ The execution flow of a single user prompt follows this loop:
    - **Multi-Stage Failover**: The loop features a sophisticated 8-attempt retry engine with random backoff (800ms - 2s).
    - **Critical Fallback Pivot**: If the primary model fails 5 consecutive times, the agent surgically pivots to a lighter, high-concurrency fallback model (`gemini-3.1-flash-lite-preview`) for the final 3 attempts to ensure session navigation through API congestion.
 
+## Multimodal Pipeline
+
+Flux Flow implements a native multimodal processing engine in `src/tools/view_file.js`. This allows the agent to move beyond text-based reasoning and analyze visual assets directly.
+
+- **Binary Detection**: The pipeline uses `is-binary-path` to distinguish between text and binary files.
+- **Visual Encoding**: If an image or PDF is detected, the engine reads the raw bytes and converts them into base64-encoded `InlineData` objects.
+- **PDF Extraction**: For PDF documents, the engine extracts visual representation of pages to provide the model with high-fidelity spatial and textual context simultaneously.
+- **Context Injection**: These multimodal assets are injected directly into the Gemini model's multimodal part array, allowing the model to "see" the file as if it were looking at a screenshot.
+
 ## The Dual-Model System
 
 To maintain a fast, snappy UI while still performing complex data management, Flux Flow employs two separate AI models for every interaction:
@@ -45,4 +54,12 @@ To maintain a fast, snappy UI while still performing complex data management, Fl
 ## Data Persistence & Safety
 
 - **High-Fidelity Lock**: Because both the UI and the Janitor model may attempt to write to the `history.json` file simultaneously, a Promise-based `WRITE_LOCK` (`src/utils/history.js`) is utilized. This prevents race conditions and ensures data integrity.
-- **Encryption**: User secrets and persistent memories (`secret/memories.json`) are handled by `src/utils/crypto.js` to ensure local privacy.
+- **Encryption**: User secrets and persistent memories (`secret/memories.json`) are handled by `src/utils/crypto.js` to ensure local privacy.
+
+## Redirection & The Anchor Strategy
+
+To support data portability (e.g., storing all app data on an external encrypted drive), Flux Flow utilizes a synchronous "Anchor" strategy in `src/utils/paths.js`.
+
+- **Synchronous Pivot**: Because many core modules (History, Secrets, Usage) initialize their file paths as constants during module loading, the application must determine the "Actual" data root before anything else.
+- **Boot-Sequence Priority**: On every launch, `paths.js` performs a synchronous file system check for `~/.fluxflow/settings.json`. If a redirection path is found (`useExternalData: true`), it immediately overrides the global `DATA_DIR` constant for the entire process.
+- **Sub-Coordinate Resolution**: All secondary directories (`LOGS_DIR`, `SECRET_DIR`) are derived dynamically from the redirected `DATA_DIR`, ensuring that all session data flows to the external sanctuary without requiring individual configuration updates across the codebase.

package/README.md

@@ -28,6 +28,16 @@ fluxflow-cli
 ### 🎨 **Premium Visual Sovereignty**
 Experience a terminal UI that feels alive. Built with **Ink** and **React**, Flux Flow features:
 - **Dynamic Status Bar**: Real-time telemetry showing your "Neural Headroom" (token usage), Thinking Level, and Session ID.
+
+### 👁️ **Native Multimodality**
+Flux Flow can now see! Use the `view_file` tool to analyze images (JPG, PNG) or deep-dive into PDF technical papers. The agent extracts high-fidelity visual context natively, making it a true multimodal companion.
+
+### 📑 **Autonomous PDF Generator**
+Need a report? Just ask. Flux Flow uses its internal "Printing Press" to generate professional, branded PDF documents from HTML/CSS, complete with consistent margins and a signature watermark.
+
+### 🚑 **Self-Healing Infrastructure**
+Zero setup means zero setup. On first run, Flux Flow performs an integrity check and autonomously installs its own Chromium engine if needed, ensuring features like PDF generation work 100% of the time without manual intervention.
+
 - **Archived Terminal Flow**: See execution outputs transform from live elements into permanent conversation records.
 - **Rich Aesthetics**: High-contrast, sleek design with smooth transitions and micro-animations.
 

package/TOOLS.md

@@ -8,6 +8,7 @@ Flux Flow provides a robust set of tools that allow the AI to interact with the
 | :--- | :---: | :---: |
 | **Web Search** | ✅ | ✅ |
 | **Web Scrape** | ✅ | ✅ |
+| **Write PDF** | ✅ | ✅ |
 | **View/Read Files** | ✅ | ❌ |
 | **Write/Update Files** | ✅ | ❌ |
 | **Execute Commands** | ✅ | ❌ |
@@ -19,11 +20,14 @@ Flux Flow provides a robust set of tools that allow the AI to interact with the
 ### 🌐 Web & Research
 - **`web_search`**: Uses DuckDuckGo to find up-to-date information on the internet. Crucial for answering questions about recent events or unlearned documentation.
 - **`web_scrape`**: Extracts the detailed text content from a specific URL, allowing the agent to read documentation or articles.
+- **`write_pdf`**: Generates high-fidelity, branded PDF documents from HTML/CSS. Features automatic watermarking and page-aware layout management.
 
 ### 📁 File System Operations
 - **`list_files`**: Lists the contents of a directory to help the agent understand the project structure.
 - **`read_folder`**: Provides detailed statistics and metadata about a directory's contents.
-- **`view_file`**: Reads the content of a file. Supports reading specific line ranges (`start_line`, `end_line`) to manage context size efficiently.
+- **`view_file`**: Reads the content of a file.
+  - **Native Multimodality**: Supports analyzing images (JPG, PNG, WEBP) and PDF documents. The tool automatically detects binary formats and encodes them for AI analysis.
+  - **Text Reading**: Supports specific line ranges (`start_line`, `end_line`) to manage context size efficiently.
 
 ### ✍️ Code Editing
 - **`write_file`**: Creates a new file or completely overwrites an existing one with new content.

package/UI_FEATURES.md

@@ -18,6 +18,15 @@ You can control the application using `/` commands directly in the chat input:
 - **/changelog**: Open the project's changelog in your default browser.
 - **/help**: List all available commands.
 
+## 📁 External Data Sanctuary (Redirection)
+
+Flux Flow allows you to "Anchor" your data outside of the default user directory. This is perfect for users who want to keep their logs, chat history, and encrypted memories on an external drive, a VeraCrypt volume, or a specific project folder.
+
+- **How to Enable**: Open `/settings` and toggle **Use External Data**. 
+- **Portability**: Once set, the application will synchronously "pivot" all data operations to your specified `externalDataPath` upon startup.
+- **Privacy**: Keeps sensitive data off your primary system drive.
+
+
 ### Command Shortcuts
 
 For power users, several commands support direct arguments to skip the menus:
@@ -81,4 +90,12 @@ The bottom of the screen features a dynamic status bar showing:
 - **Thinking Level**
 - **Token Usage**: Real-time tracking of tokens used in the current session.
 - **Agentic Loops**: Counters showing how many times the agent has "looped" to solve the current task.
-- **API Status**: Visual feedback when the model is thinking or executing a tool.
+- **API Status**: Visual feedback when the model is thinking or executing a tool.
+
+## 🚑 System Integrity & Self-Healing
+
+Flux Flow is a "Self-Healing" agent. It actively monitors its own environment to ensure all complex dependencies (like the Chromium engine for PDF generation) are ready for action.
+
+- **Startup Integrity Check**: On launch, Flux performs a "Heartbeat Check" on its internal engines.
+- **Automatic Recovery**: If a dependency is missing, you will see a `🔧 [SYSTEM] Initializing...` message. Flux will autonomously download and configure the required binaries using `pnpm` or `npx` fallbacks, keeping you informed every step of the way.
+- **Silent Maintenance**: Once the engine is ready, you'll receive a `✅ [SYSTEM] All dependencies installed successfully.` confirmation.

package/dist/fluxflow.js

@@ -77,7 +77,7 @@ var init_ChatLayout = __esm({
     };
     InlineMarkdown = React2.memo(({ text, color }) => {
       if (!text) return null;
-      const parts = text.split(/(\*\*.*?\*\*|\*.*?\*|`.*?`|\$\\viewtext\{.*?\}\$|\[.*?\]\s*\(.*?\)|\[.*?\]\s*\[.*?\]|https?:\/\/[^\s]+)/g);
+      const parts = text.split(/(\*\*.*?\*\*|\*.*?\*|`.*?`|\$.*?\$|\[.*?\]\s*\(.*?\)|\[.*?\]\s*\[.*?\]|https?:\/\/[^\s]+)/g);
       return /* @__PURE__ */ React2.createElement(Text2, { color, wrap: "anywhere" }, parts.map((part, j) => {
         if (!part) return null;
         if (part.startsWith("**") && part.endsWith("**")) {
@@ -89,9 +89,13 @@ var init_ChatLayout = __esm({
         if (part.startsWith("`") && part.endsWith("`")) {
           return /* @__PURE__ */ React2.createElement(Text2, { key: j, color: "cyan", backgroundColor: "#003333" }, " ", part.slice(1, -1), " ");
         }
-        if (part.startsWith("$\\viewtext{") && part.endsWith("}$")) {
-          const content = part.slice(11, -2);
-          return /* @__PURE__ */ React2.createElement(Text2, { key: j, color: "white", backgroundColor: "#4c0099", bold: true, italic: true }, " ", content, " ");
+        if (part.startsWith("$") && part.endsWith("$")) {
+          let content = part.slice(1, -1);
+          if (content.startsWith("\\text{") && content.endsWith("}")) {
+            content = content.slice(6, -1);
+          }
+          const mathContent = content.replace(/\\multiply/g, "\xD7").replace(/\\divide/g, "\xF7");
+          return /* @__PURE__ */ React2.createElement(Text2, { key: j, color: "white", backgroundColor: "#4c0099", bold: true, italic: true }, " ", mathContent, " ");
         }
         if (part.startsWith("[") && (part.includes("](") || part.includes("] ("))) {
           const match = part.match(/\[(.*?)\]\s*\((.*?)\)/);
@@ -511,15 +515,40 @@ var init_crypto = __esm({
 });
 
 // src/utils/paths.js
+var paths_exports = {};
+__export(paths_exports, {
+  DATA_DIR: () => DATA_DIR,
+  FLUXFLOW_DIR: () => FLUXFLOW_DIR,
+  HISTORY_FILE: () => HISTORY_FILE,
+  LOGS_DIR: () => LOGS_DIR,
+  MEMORIES_FILE: () => MEMORIES_FILE,
+  SECRET_DIR: () => SECRET_DIR,
+  SETTINGS_FILE: () => SETTINGS_FILE,
+  TEMP_MEM_FILE: () => TEMP_MEM_FILE,
+  USAGE_FILE: () => USAGE_FILE
+});
 import os from "os";
 import path2 from "path";
-var FLUXFLOW_DIR, LOGS_DIR, SECRET_DIR, SETTINGS_FILE, HISTORY_FILE, USAGE_FILE, MEMORIES_FILE, TEMP_MEM_FILE;
+import fs2 from "fs";
+var FLUXFLOW_DIR, SETTINGS_FILE, externalDir, DATA_DIR, LOGS_DIR, SECRET_DIR, HISTORY_FILE, USAGE_FILE, MEMORIES_FILE, TEMP_MEM_FILE;
 var init_paths = __esm({
   "src/utils/paths.js"() {
     FLUXFLOW_DIR = path2.join(os.homedir(), ".fluxflow");
-    LOGS_DIR = path2.join(FLUXFLOW_DIR, "logs");
-    SECRET_DIR = path2.join(FLUXFLOW_DIR, "secret");
     SETTINGS_FILE = path2.join(FLUXFLOW_DIR, "settings.json");
+    externalDir = null;
+    try {
+      if (fs2.existsSync(SETTINGS_FILE)) {
+        const settings = JSON.parse(fs2.readFileSync(SETTINGS_FILE, "utf8"));
+        const sys = settings.systemSettings || {};
+        if (sys.useExternalData && sys.externalDataPath) {
+          externalDir = sys.externalDataPath;
+        }
+      }
+    } catch (e) {
+    }
+    DATA_DIR = externalDir || FLUXFLOW_DIR;
+    LOGS_DIR = path2.join(DATA_DIR, "logs");
+    SECRET_DIR = path2.join(DATA_DIR, "secret");
     HISTORY_FILE = path2.join(SECRET_DIR, "history.json");
     USAGE_FILE = path2.join(SECRET_DIR, "usage.json");
     MEMORIES_FILE = path2.join(SECRET_DIR, "memories.json");
@@ -528,7 +557,7 @@ var init_paths = __esm({
 });
 
 // src/utils/secrets.js
-import fs2 from "fs-extra";
+import fs3 from "fs-extra";
 import path3 from "path";
 var SECRET_FILE, getAPIKey, saveSecret, saveAPIKey, removeSecret, removeAPIKey;
 var init_secrets = __esm({
@@ -545,7 +574,7 @@ var init_secrets = __esm({
       return null;
     };
     saveSecret = async (key, value) => {
-      await fs2.ensureDir(SECRET_DIR);
+      await fs3.ensureDir(SECRET_DIR);
       let current = readEncryptedJson(SECRET_FILE, {});
       current[key] = value;
       writeEncryptedJson(SECRET_FILE, current);
@@ -578,18 +607,22 @@ tool:functions.tool_name(arguments)
     3. Ask User: tool:functions.ask(question="...", optionA="Option::Desc", optionB="Option::Desc"). Generally use this tool for ANY ambiguity. Mandatory triggers include: 1) **Path Divergence**: When multiple architectural or technical solutions exist, present options via 'ask' instead of choosing arbitrarily. 2) **Security Boundaries**: Explicitly request permission via 'ask' before accessing sensitive files (e.g., .env, config keys, credentials). 3) **Ambiguity Resolution**: Use 'ask' to clarify vague prompts before executing terminal commands or writing code. 4) **Risk Mitigation**: Require a 'Yes/No' confirmation for any destructive or irreversible operations. Options must always follow the 'Short Label::Detailed Description' format. This tool is a non-terminating suspension so you can get guidance without losing context.
 ${mode === "Flux" ? `
 - DEV & FILE TOOLS (Available in FLUX MODE ONLY) -
-    1. View File: tool:functions.view_file(path="relative/path", start_line=number, end_line=number). Reads file content. Auto-truncates at 500 lines unless start_line and end_line are provided.
+    1. View File: tool:functions.view_file(path="relative/path", start_line=number, end_line=number). Reads file content. Auto-truncates at 500 lines unless start_line and end_line are provided. You can also use this tool to read images & documents.
     2. List Files: tool:functions.list_files(path="relative/path"). Lists content of a directory.
     3. Read Folder: tool:functions.read_folder(path="relative/path"). Detailed stats of a directory.
     4. Write File: tool:functions.write_file(path="path", content="content"). Creates/Overwrites. NO CODE BLOCKS. RETURNS: Disk verification + original content (if overwritten) for 100% reversibility.
     5. Update File: tool:functions.update_file(path="relative/path", content_to_replace="old", content_to_add="new"). Surgical patching. RETURNS: High-fidelity visual diff and old code block. You MUST verify that the change specifically matches your intent using the returned diff. PREFFER UPDATE FILE OVER WRITE FILE if file already exists for better reversal tracking (if a file has 500+ lines, try to stick with update_file over full-rewrite). DONT WRAP UPDATE FILE CALL CONTENT IN MARKDOWN CODE BLOCKS.
-    6. Execution: tool:functions.exec_command(command="terminal command"). Runs a shell command.`.trim() : `
-    - DEV & FILE TOOLS are not available in FLOW MODE. If you need to access files, tell the user to switch to FLUX MODE (manually by user).`.trim()}
+    6. Write PDF: tool:functions.write_pdf(path="path", content="<html/css content>", orientation="portrait/landscape"). Generates a professional PDF document. Orientation are optional. A4 size page will be used. DO NOT ADD FOOTER MANUALLY, the system will handle it automatically. USE CSS TO VISUALLY BEAUTIFY THE DOCUMENT.
+    7. Execution: tool:functions.exec_command(command="terminal command"). Runs a shell command.
+
+    **NOTE:** WHEN WRITING/UPDATING FILES, USE ACTUAL NEW LINE CHARACTER FOR LINE BREAKS RATHER THAN STRING '\\n'`.trim() : `
+    - DEV & FILE TOOLS ARE NOT AVAILABLE IN FLOW MODE. If you need to access files, tell the user to switch to FLUX MODE (manually by user).`.trim()}
 -----------------
 Results will be provided in the next loop as: [TOOL_RESULT]: [content]
 WHEN CALLING TOOLS, YOU **MUST** end your response with '[turn: continue]'. NEVER use '[turn: finish]' in the same turn as a tool call. After receiving the [TOOL_RESULT], acknowledge the output and verify if the goal is met; only then may you use '[turn: finish]', otherwise use '[turn: continue]'.
 Do NOT over-use tools. Use them only when strictly necessary for the user's objective. You can stack multiple tool calls 1-by-1.
 Distinguish clearly between tool discussion and execution. Use the 'tool:' prefix ONLY when calling a function. When discussing tools with the user, refer to them by name as nouns (e.g., 'write_file', 'list_files') to avoid accidental triggers and context bloat. Even in your <think> ... </think> tags, do not use the 'tool:' prefix when planning to select a tool.
+Use tools contextually when needed, don't flood with unnecessary tool calls.
 -- END FUNCTION CALLING PROTOCOL --`.trim();
   }
 });
@@ -751,7 +784,7 @@ Current date and Time: ${(/* @__PURE__ */ new Date()).toLocaleString()}
 });
 
 // src/utils/history.js
-import fs3 from "fs-extra";
+import fs4 from "fs-extra";
 import path4 from "path";
 import { nanoid } from "nanoid";
 var WRITE_LOCK, withLock, loadHistory, saveChat, saveChatTitle, deleteChat, generateChatId, cleanupOldHistory, getTruncatedHistory;
@@ -774,9 +807,9 @@ var init_history = __esm({
       return nextLock;
     };
     loadHistory = async () => {
-      if (await fs3.pathExists(HISTORY_FILE)) {
+      if (await fs4.pathExists(HISTORY_FILE)) {
         try {
-          return await fs3.readJson(HISTORY_FILE);
+          return await fs4.readJson(HISTORY_FILE);
         } catch (e) {
           return {};
         }
@@ -794,8 +827,8 @@ var init_history = __esm({
           messages: persistentMessages,
           updatedAt: Date.now()
         };
-        await fs3.ensureDir(path4.dirname(HISTORY_FILE));
-        await fs3.writeJson(HISTORY_FILE, history, { spaces: 2 });
+        await fs4.ensureDir(path4.dirname(HISTORY_FILE));
+        await fs4.writeJson(HISTORY_FILE, history, { spaces: 2 });
       });
     };
     saveChatTitle = async (id, title) => {
@@ -807,15 +840,15 @@ var init_history = __esm({
         } else {
           history[id] = { name: title, messages: [], updatedAt: Date.now() };
         }
-        await fs3.ensureDir(path4.dirname(HISTORY_FILE));
-        await fs3.writeJson(HISTORY_FILE, history, { spaces: 2 });
+        await fs4.ensureDir(path4.dirname(HISTORY_FILE));
+        await fs4.writeJson(HISTORY_FILE, history, { spaces: 2 });
       });
     };
     deleteChat = async (id) => {
       return withLock(async () => {
         const history = await loadHistory();
         delete history[id];
-        await fs3.writeJson(HISTORY_FILE, history, { spaces: 2 });
+        await fs4.writeJson(HISTORY_FILE, history, { spaces: 2 });
         const temp = readEncryptedJson(TEMP_MEM_FILE, {});
         if (temp[id]) {
           delete temp[id];
@@ -854,7 +887,7 @@ var init_history = __esm({
 });
 
 // src/utils/usage.js
-import fs4 from "fs-extra";
+import fs5 from "fs-extra";
 import path5 from "path";
 var getDailyUsage, incrementUsage, checkQuota;
 var init_usage = __esm({
@@ -863,8 +896,8 @@ var init_usage = __esm({
     getDailyUsage = async () => {
       const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
       try {
-        if (await fs4.exists(USAGE_FILE)) {
-          const data = await fs4.readJson(USAGE_FILE);
+        if (await fs5.exists(USAGE_FILE)) {
+          const data = await fs5.readJson(USAGE_FILE);
           if (data.date === today) {
             return data.stats;
           }
@@ -873,21 +906,21 @@ var init_usage = __esm({
         console.error("Failed to read usage:", err);
       }
       const defaultStats = { agent: 0, background: 0, search: 0 };
-      await fs4.ensureDir(path5.dirname(USAGE_FILE));
-      await fs4.writeJson(USAGE_FILE, { date: today, stats: defaultStats }, { spaces: 2 });
+      await fs5.ensureDir(path5.dirname(USAGE_FILE));
+      await fs5.writeJson(USAGE_FILE, { date: today, stats: defaultStats }, { spaces: 2 });
       return defaultStats;
     };
     incrementUsage = async (key) => {
       const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-      const data = await fs4.readJson(USAGE_FILE).catch(() => ({ date: today, stats: { agent: 0, background: 0, search: 0 } }));
+      const data = await fs5.readJson(USAGE_FILE).catch(() => ({ date: today, stats: { agent: 0, background: 0, search: 0 } }));
       if (data.date !== today) {
         data.date = today;
         data.stats = { agent: 0, background: 0, search: 0 };
       }
       if (data.stats[key] !== void 0) {
         data.stats[key]++;
-        await fs4.ensureDir(path5.dirname(USAGE_FILE));
-        await fs4.writeJson(USAGE_FILE, data, { spaces: 2 });
+        await fs5.ensureDir(path5.dirname(USAGE_FILE));
+        await fs5.writeJson(USAGE_FILE, data, { spaces: 2 });
       }
     };
     checkQuota = async (key, settings) => {
@@ -941,7 +974,7 @@ var init_arg_parser = __esm({
 
 // src/tools/web_search.js
 import * as cuimp from "cuimp";
-import fs5 from "fs";
+import fs6 from "fs";
 import path6 from "path";
 var web_search;
 var init_web_search = __esm({
@@ -976,10 +1009,10 @@ Snippet: ${snippet}`);
           count++;
         }
         const toolLogDir = path6.join(LOGS_DIR, "tools");
-        if (!fs5.existsSync(toolLogDir)) {
-          fs5.mkdirSync(toolLogDir, { recursive: true });
+        if (!fs6.existsSync(toolLogDir)) {
+          fs6.mkdirSync(toolLogDir, { recursive: true });
         }
-        fs5.appendFileSync(path6.join(toolLogDir, "search-results.log"), `RESULTS ${(/* @__PURE__ */ new Date()).toISOString()} - 
+        fs6.appendFileSync(path6.join(toolLogDir, "search-results.log"), `RESULTS ${(/* @__PURE__ */ new Date()).toISOString()} - 
 Query: [${query}]. Results Count: ${results.length}.
 Results: ${results}
 
@@ -988,10 +1021,10 @@ Results: ${results}
         if (results.length === 0) {
           if (html.includes("anomaly")) {
             const toolErrDir = path6.join(LOGS_DIR, "tools");
-            if (!fs5.existsSync(toolErrDir)) {
-              fs5.mkdirSync(toolErrDir, { recursive: true });
+            if (!fs6.existsSync(toolErrDir)) {
+              fs6.mkdirSync(toolErrDir, { recursive: true });
             }
-            fs5.appendFileSync(path6.join(toolErrDir, "error.log"), `ERROR ${(/* @__PURE__ */ new Date()).toISOString()} - DDG detected unusual activity. Cuimp impersonation might need adjustment.
+            fs6.appendFileSync(path6.join(toolErrDir, "error.log"), `ERROR ${(/* @__PURE__ */ new Date()).toISOString()} - DDG detected unusual activity. Cuimp impersonation might need adjustment.
 `);
             throw new Error("DDG detected unusual activity. Cuimp impersonation might need adjustment.");
           }
@@ -1009,7 +1042,7 @@ ${finalResults}`;
 });
 
 // src/tools/web_scrape.js
-import fs6 from "fs";
+import fs7 from "fs";
 import path7 from "path";
 import * as cuimp2 from "cuimp";
 var web_scrape;
@@ -1037,10 +1070,10 @@ var init_web_scrape = __esm({
         let text = html.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
         const finalContent = text.substring(0, 2e4);
         const toolLogDir = path7.join(LOGS_DIR, "tools");
-        if (!fs6.existsSync(toolLogDir)) {
-          fs6.mkdirSync(toolLogDir, { recursive: true });
+        if (!fs7.existsSync(toolLogDir)) {
+          fs7.mkdirSync(toolLogDir, { recursive: true });
         }
-        fs6.appendFileSync(path7.join(toolLogDir, "search-scraped.log"), `RESULTS ${(/* @__PURE__ */ new Date()).toISOString()} - 
+        fs7.appendFileSync(path7.join(toolLogDir, "search-scraped.log"), `RESULTS ${(/* @__PURE__ */ new Date()).toISOString()} - 
 Query: [${url}].
 Results: ${finalContent}
 
@@ -1151,7 +1184,7 @@ var init_chat = __esm({
 });
 
 // src/tools/list_files.js
-import fs7 from "fs";
+import fs8 from "fs";
 import path8 from "path";
 var list_files;
 var init_list_files = __esm({
@@ -1161,14 +1194,14 @@ var init_list_files = __esm({
       const { path: targetPath = "." } = parseArgs(args);
       const absolutePath = path8.resolve(process.cwd(), targetPath);
       try {
-        if (!fs7.existsSync(absolutePath)) {
+        if (!fs8.existsSync(absolutePath)) {
           return `ERROR: Path [${targetPath}] does not exist.`;
         }
-        const stats = fs7.statSync(absolutePath);
+        const stats = fs8.statSync(absolutePath);
         if (!stats.isDirectory()) {
           return `ERROR: Path [${targetPath}] is a file, not a directory. Use view_file instead.`;
         }
-        const files = fs7.readdirSync(absolutePath);
+        const files = fs8.readdirSync(absolutePath);
         if (files.length === 0) {
           return `Directory [${targetPath}] is empty.`;
         }
@@ -1180,7 +1213,7 @@ var init_list_files = __esm({
           let indicator = "\u{1F4C4}";
           let metaPart = "";
           try {
-            const fStats = fs7.statSync(fPath);
+            const fStats = fs8.statSync(fPath);
             indicator = fStats.isDirectory() ? "\u{1F4C1}" : "\u{1F4C4}";
             const sizeKB = (fStats.size / 1024).toFixed(1);
             metaPart = fStats.isFile() ? ` - [${sizeKB} KB]` : "";
@@ -1212,7 +1245,7 @@ ${list}${footer}`;
 });
 
 // src/tools/view_file.js
-import fs8 from "fs";
+import fs9 from "fs";
 import path9 from "path";
 var view_file;
 var init_view_file = __esm({
@@ -1223,14 +1256,38 @@ var init_view_file = __esm({
       if (!targetPath) return 'ERROR: Missing "path" argument for view_file.';
       const absolutePath = path9.resolve(process.cwd(), targetPath);
       try {
-        if (!fs8.existsSync(absolutePath)) {
+        if (!fs9.existsSync(absolutePath)) {
           return `ERROR: File [${targetPath}] does not exist.`;
         }
-        const stats = fs8.statSync(absolutePath);
+        const stats = fs9.statSync(absolutePath);
         if (stats.isDirectory()) {
           return `ERROR: Path [${targetPath}] is a directory. Use list_files instead.`;
         }
-        const content = fs8.readFileSync(absolutePath, "utf8");
+        const ext = path9.extname(targetPath).toLowerCase();
+        const mimeMap = {
+          ".pdf": "application/pdf",
+          ".jpg": "image/jpeg",
+          ".jpeg": "image/jpeg",
+          ".png": "image/png",
+          ".webp": "image/webp",
+          ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+          ".doc": "application/msword"
+        };
+        if (mimeMap[ext]) {
+          const buffer = fs9.readFileSync(absolutePath);
+          const base64 = buffer.toString("base64");
+          const mimeType = mimeMap[ext];
+          return {
+            text: `[BINARY_FILE]: ${targetPath} (${mimeType}) - Loaded as multimodal part.`,
+            binaryPart: {
+              inlineData: {
+                data: base64,
+                mimeType
+              }
+            }
+          };
+        }
+        const content = fs9.readFileSync(absolutePath, "utf8");
         const lines = content.split("\n");
         const totalLines = lines.length;
         const start = Math.max(0, start_line - 1);
@@ -1249,7 +1306,7 @@ ${code}`;
 });
 
 // src/tools/write_file.js
-import fs9 from "fs";
+import fs10 from "fs";
 import path10 from "path";
 var write_file;
 var init_write_file = __esm({
@@ -1264,9 +1321,9 @@ var init_write_file = __esm({
       const parentDir = path10.dirname(absolutePath);
       try {
         let ancestry = "";
-        if (fs9.existsSync(absolutePath)) {
+        if (fs10.existsSync(absolutePath)) {
           try {
-            const oldData = fs9.readFileSync(absolutePath, "utf8");
+            const oldData = fs10.readFileSync(absolutePath, "utf8");
             const lines = oldData.split(/\r?\n/);
             ancestry = `Old File contents:
 ${lines.map((l, i) => `${i + 1} | ${l}`).join("\n")}
@@ -1278,13 +1335,13 @@ ${lines.map((l, i) => `${i + 1} | ${l}`).join("\n")}
 `;
           }
         }
-        if (!fs9.existsSync(parentDir)) {
-          fs9.mkdirSync(parentDir, { recursive: true });
+        if (!fs10.existsSync(parentDir)) {
+          fs10.mkdirSync(parentDir, { recursive: true });
         }
         const lineCount = content.split(/\r?\n/).length;
         const originalSize = Buffer.byteLength(content, "utf8");
-        fs9.writeFileSync(absolutePath, content, "utf8");
-        let verifiedContent = fs9.readFileSync(absolutePath, "utf8");
+        fs10.writeFileSync(absolutePath, content, "utf8");
+        let verifiedContent = fs10.readFileSync(absolutePath, "utf8");
         const verifiedSize = Buffer.byteLength(verifiedContent, "utf8");
         const verifiedLines = verifiedContent.split(/\r?\n/);
         const verifiedLineCount = verifiedLines.length;
@@ -1318,7 +1375,7 @@ ${snippet}`;
 });
 
 // src/tools/update_file.js
-import fs10 from "fs";
+import fs11 from "fs";
 import path11 from "path";
 var update_file;
 var init_update_file = __esm({
@@ -1334,10 +1391,10 @@ var init_update_file = __esm({
       content_to_add = strip(content_to_add);
       const absolutePath = path11.resolve(process.cwd(), targetPath);
       try {
-        if (!fs10.existsSync(absolutePath)) {
+        if (!fs11.existsSync(absolutePath)) {
           return `ERROR: File [${targetPath}] does not exist. Use write_file instead.`;
         }
-        const currentContent = fs10.readFileSync(absolutePath, "utf8");
+        const currentContent = fs11.readFileSync(absolutePath, "utf8");
         if (!currentContent.includes(content_to_replace)) {
           return `ERROR: Could not find exact match for the specified "content_to_replace" in [${targetPath}]. Check indentation/whitespace/line breaks(LF or CRLF)/string. Try re-reading the file for latest changes.`;
         }
@@ -1345,7 +1402,7 @@ var init_update_file = __esm({
         const startLine = currentContent.substring(0, startPos).split(/\r?\n/).length;
         const instances = currentContent.split(content_to_replace).length - 1;
         const newFileContent = currentContent.split(content_to_replace).join(content_to_add);
-        fs10.writeFileSync(absolutePath, newFileContent, "utf8");
+        fs11.writeFileSync(absolutePath, newFileContent, "utf8");
         const allOriginalLines = currentContent.split(/\r?\n/);
         const oldLines = content_to_replace.split(/\r?\n/);
         const newLines = content_to_add.split(/\r?\n/);
@@ -1467,7 +1524,7 @@ ${finalOutput}`);
 });
 
 // src/tools/read_folder.js
-import fs11 from "fs";
+import fs12 from "fs";
 import path12 from "path";
 var read_folder;
 var init_read_folder = __esm({
@@ -1477,14 +1534,14 @@ var init_read_folder = __esm({
       const { path: targetPath = "." } = parseArgs(args);
       const absolutePath = path12.resolve(process.cwd(), targetPath);
       try {
-        if (!fs11.existsSync(absolutePath)) {
+        if (!fs12.existsSync(absolutePath)) {
           return `ERROR: Path [${targetPath}] does not exist.`;
         }
-        const stats = fs11.statSync(absolutePath);
+        const stats = fs12.statSync(absolutePath);
         if (!stats.isDirectory()) {
           return `ERROR: Path [${targetPath}] is a file, not a directory. Use view_file instead.`;
         }
-        const files = fs11.readdirSync(absolutePath);
+        const files = fs12.readdirSync(absolutePath);
         const totalItems = files.length;
         const maxDisplay = 100;
         const displayItems = files.slice(0, maxDisplay);
@@ -1494,7 +1551,7 @@ var init_read_folder = __esm({
           let indicator = "\u{1F4C4}";
           let info = { name: file, type: "unknown", size: "N/A", mtime: "N/A" };
           try {
-            const fStats = fs11.statSync(fPath);
+            const fStats = fs12.statSync(fPath);
             info = {
               name: file,
               type: fStats.isDirectory() ? "directory" : "file",
@@ -1575,6 +1632,78 @@ var init_ask_user = __esm({
   }
 });
 
+// src/tools/write_pdf.js
+import puppeteer from "puppeteer";
+import path13 from "path";
+import fs13 from "fs-extra";
+var write_pdf;
+var init_write_pdf = __esm({
+  "src/tools/write_pdf.js"() {
+    init_arg_parser();
+    write_pdf = async (args) => {
+      const { path: targetPath, content, orientation = "portrait", margin = "10px" } = parseArgs(args);
+      if (!targetPath) return 'ERROR: Missing "path" argument for write_pdf.';
+      if (!content) return 'ERROR: Missing "content" (HTML/CSS) for write_pdf.';
+      const absolutePath = path13.resolve(process.cwd(), targetPath);
+      let browser = null;
+      try {
+        await fs13.ensureDir(path13.dirname(absolutePath));
+        browser = await puppeteer.launch({
+          headless: true,
+          args: [
+            "--no-sandbox",
+            "--disable-setuid-sandbox",
+            "--disable-gpu",
+            "--disable-dev-shm-usage"
+          ]
+        });
+        const page = await browser.newPage();
+        const styledContent = `
+            <style>
+                @page { 
+                    margin: ${margin}; 
+                }
+                body { 
+                    margin: 0; 
+                    padding: 0;
+                    font-family: system-ui, -apple-system, sans-serif;
+                }
+                * { box-sizing: border-box; }
+            </style>
+            ${content}
+        `;
+        await page.setContent(styledContent, { waitUntil: "networkidle0" });
+        await page.pdf({
+          path: absolutePath,
+          format: "A4",
+          landscape: orientation.toLowerCase() === "landscape",
+          margin: {
+            top: margin,
+            right: margin,
+            bottom: "15mm",
+            // Space for watermark
+            left: margin
+          },
+          displayHeaderFooter: true,
+          headerTemplate: "<span></span>",
+          footerTemplate: `
+                <div style="font-size: 9px; color: rgba(0,0,0,0.2); width: 100%; text-align: right; padding-right: 15mm; font-family: system-ui, sans-serif; -webkit-print-color-adjust: exact;">
+                    FluxFlow CLI
+                </div>
+            `,
+          printBackground: true
+        });
+        const stats = await fs13.stat(absolutePath);
+        return `SUCCESS: PDF generated successfully at [${targetPath}] (${(stats.size / 1024).toFixed(2)} KB).`;
+      } catch (err) {
+        return `ERROR: Failed to generate PDF [${targetPath}]: ${err.message}`;
+      } finally {
+        if (browser) await browser.close();
+      }
+    };
+  }
+});
+
 // src/utils/tools.js
 var TOOL_MAP, dispatchTool;
 var init_tools = __esm({
@@ -1590,6 +1719,7 @@ var init_tools = __esm({
     init_exec_command();
     init_read_folder();
     init_ask_user();
+    init_write_pdf();
     TOOL_MAP = {
       web_search,
       web_scrape,
@@ -1601,6 +1731,7 @@ var init_tools = __esm({
       update_file,
       exec_command,
       read_folder,
+      write_pdf,
       ask: ask_user
     };
     dispatchTool = async (toolName, args, context = {}) => {
@@ -1617,10 +1748,32 @@ var init_tools = __esm({
   }
 });
 
+// src/utils/terminal.js
+var getTerminalEnv, emojiSpace;
+var init_terminal = __esm({
+  "src/utils/terminal.js"() {
+    getTerminalEnv = () => {
+      if (process.env.TERM_PROGRAM === "vscode") return "vscode";
+      if (process.env.WT_SESSION) return "wt";
+      return "default";
+    };
+    emojiSpace = (baseSpaces = 2) => {
+      const env = getTerminalEnv();
+      if (env === "wt") {
+        return " ".repeat(Math.max(1, baseSpaces - 1));
+      }
+      if (env === "vscode") {
+        return " ".repeat(baseSpaces);
+      }
+      return " ".repeat(baseSpaces);
+    };
+  }
+});
+
 // src/utils/ai.js
 import { GoogleGenAI, ThinkingLevel } from "@google/genai";
-import path13 from "path";
-import fs12 from "fs";
+import path14 from "path";
+import fs14 from "fs";
 var client, TERMINATION_SIGNAL, signalTermination, detectToolCalls, initAI, getAIStream;
 var init_ai = __esm({
   "src/utils/ai.js"() {
@@ -1630,6 +1783,7 @@ var init_ai = __esm({
     init_tools();
     init_crypto();
     init_arg_parser();
+    init_terminal();
     init_paths();
     client = null;
     TERMINATION_SIGNAL = false;
@@ -1733,10 +1887,16 @@ USER_PROMPT: ${agentText}`.trim();
           }
         }
         yield { type: "turn_reset", content: true };
-        const contents = modifiedHistory.filter((msg) => (msg.role === "user" || msg.role === "agent" || msg.role === "system") && !String(msg.id).startsWith("welcome") && !msg.isMeta).map((msg) => ({
-          role: msg.role === "user" || msg.role === "system" ? "user" : "model",
-          parts: [{ text: msg.text }]
-        }));
+        const contents = modifiedHistory.filter((msg) => (msg.role === "user" || msg.role === "agent" || msg.role === "system") && !String(msg.id).startsWith("welcome") && !msg.isMeta).map((msg) => {
+          const parts = [{ text: msg.text }];
+          if (msg.binaryPart) {
+            parts.push(msg.binaryPart);
+          }
+          return {
+            role: msg.role === "user" || msg.role === "system" ? "user" : "model",
+            parts
+          };
+        });
         let stream;
         let success = false;
         let retryCount = 0;
@@ -1770,9 +1930,9 @@ USER_PROMPT: ${agentText}`.trim();
           } catch (err) {
             const errMsg = err.status || err.error && err.error.message || String(err);
             const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace("T", " ");
-            const agentErrDir = path13.join(LOGS_DIR, "agent");
-            if (!fs12.existsSync(agentErrDir)) fs12.mkdirSync(agentErrDir, { recursive: true });
-            fs12.appendFileSync(path13.join(agentErrDir, "error.log"), `ERROR [${date}]: ${errMsg}
+            const agentErrDir = path14.join(LOGS_DIR, "agent");
+            if (!fs14.existsSync(agentErrDir)) fs14.mkdirSync(agentErrDir, { recursive: true });
+            fs14.appendFileSync(path14.join(agentErrDir, "error.log"), `ERROR [${date}]: ${errMsg}
 `);
             if (retryCount < MAX_RETRIES) {
               retryCount++;
@@ -1832,9 +1992,9 @@ USER_PROMPT: ${agentText}`.trim();
               let totalLines = "...";
               let actualEndLine = end_line;
               try {
-                const absPath = path13.resolve(process.cwd(), targetPath2);
-                if (fs12.existsSync(absPath)) {
-                  const content = fs12.readFileSync(absPath, "utf8");
+                const absPath = path14.resolve(process.cwd(), targetPath2);
+                if (fs14.existsSync(absPath)) {
+                  const content = fs14.readFileSync(absPath, "utf8");
                   const lines = content.split("\n").length;
                   totalLines = lines;
                   actualEndLine = Math.min(end_line, lines);
@@ -1848,6 +2008,8 @@ USER_PROMPT: ${agentText}`.trim();
             } else if (toolCall.toolName === "write_file" || toolCall.toolName === "update_file") {
               const action = toolCall.toolName === "write_file" ? "WRITING" : "PATCHING";
               label = `\u{1F4BE} ${action} FILE: ${parseArgs(toolCall.args).path || "..."}`.toUpperCase();
+            } else if (toolCall.toolName === "write_pdf") {
+              label = `\u{1F4D1} GENERATING PDF: ${parseArgs(toolCall.args).path || "..."}`.toUpperCase();
             } else if (toolCall.toolName === "exec_command" || toolCall.toolName === "ask") {
               label = "";
             } else {
@@ -1882,7 +2044,7 @@ ${boxBottom}
                   /\/usr\//
                   // Sensitive Linux paths
                 ];
-                const currentDrive = path13.resolve(process.cwd()).substring(0, 3).toLowerCase();
+                const currentDrive = path14.resolve(process.cwd()).substring(0, 3).toLowerCase();
                 const isViolating = riskyPatterns.some((pattern) => {
                   if (pattern.source === "[a-zA-Z]:[\\\\\\/]") {
                     const driveMatch = command.match(/[a-zA-Z]:[\\\/]/i);
@@ -1904,8 +2066,8 @@ ${boxBottom}
             const targetPath = parsedArgs.path || parsedArgs.targetPath || null;
             if (targetPath) {
               const isExternalOff = settings.systemSettings && settings.systemSettings.allowExternalAccess === false;
-              const absoluteTarget = path13.resolve(targetPath);
-              const absoluteCwd = path13.resolve(process.cwd());
+              const absoluteTarget = path14.resolve(targetPath);
+              const absoluteCwd = path14.resolve(process.cwd());
               if (isExternalOff && !absoluteTarget.startsWith(absoluteCwd)) {
                 const denyMsg = `Access Denied. You are not allowed to access files outside the current workspace. To enable this, ask the user to turn on "External Workspace Access" in /settings.`;
                 toolResults.push(`[TOOL_RESULT]: ERROR: ${denyMsg}`);
@@ -1931,12 +2093,17 @@ ${boxBottom}
                 }
               }
             }
-            const result = await dispatchTool(toolCall.toolName, toolCall.args, {
+            let result = await dispatchTool(toolCall.toolName, toolCall.args, {
               chatId,
               history,
               onChunk: (chunk) => settings.onExecChunk ? settings.onExecChunk(chunk) : null,
               onAskUser: settings.onAskUser
             });
+            let binaryPart = null;
+            if (typeof result === "object" && result.binaryPart) {
+              binaryPart = result.binaryPart;
+              result = result.text;
+            }
             if (toolCall.toolName === "exec_command" && settings.onExecEnd) {
               await new Promise((resolve) => setTimeout(resolve, 800));
               settings.onExecEnd();
@@ -1945,17 +2112,17 @@ ${boxBottom}
               const timestamp = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace("T", " ");
               const isErr = result.startsWith("ERROR:");
               const logStatus = isErr ? result.trim() : "SUCCESS";
-              const toolHistDir = path13.join(LOGS_DIR, "tools");
-              if (!fs12.existsSync(toolHistDir)) {
-                fs12.mkdirSync(toolHistDir, { recursive: true });
+              const toolHistDir = path14.join(LOGS_DIR, "tools");
+              if (!fs14.existsSync(toolHistDir)) {
+                fs14.mkdirSync(toolHistDir, { recursive: true });
               }
-              fs12.appendFileSync(path13.join(toolHistDir, "history.log"), `HISTORY [${timestamp}]: ${toolCall.toolName} [${logStatus}]
+              fs14.appendFileSync(path14.join(toolHistDir, "history.log"), `HISTORY [${timestamp}]: ${toolCall.toolName} [${logStatus}]
 `);
             } catch (logErr) {
             }
             const cleanResultForAI = result.split(/\r?\n/).filter((line) => !line.includes("[UI_CONTEXT]")).join("\n");
             const aiContent = `[TOOL_RESULT]: ${cleanResultForAI}`;
-            toolResults.push(aiContent);
+            toolResults.push({ role: "user", text: aiContent, binaryPart });
             let uiContent = `[TOOL_RESULT]: ${result}`;
             if (toolCall.toolName === "view_file" || toolCall.toolName === "web_scrape") {
               uiContent = `[TOOL_RESULT]: ${label} (Context Locked for UI Clarity)`;
@@ -1963,7 +2130,9 @@ ${boxBottom}
             yield {
               type: "tool_result",
               content: uiContent,
-              aiContent
+              aiContent,
+              binaryPart
+              // Multi-modal stage (v1.5.0)
             };
             if (toolCall.toolName === "memory" && result.includes("SUCCESS")) {
               yield { type: "memory_updated" };
@@ -2009,11 +2178,11 @@ ${boxBottom}
             if (parts && parts[1]?.text) {
               finalSynthesis = parts[1].text;
               const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace("T", " ");
-              const janitorLogDir = path13.join(LOGS_DIR, "janitor");
-              if (!fs12.existsSync(janitorLogDir)) {
-                fs12.mkdirSync(janitorLogDir, { recursive: true });
+              const janitorLogDir = path14.join(LOGS_DIR, "janitor");
+              if (!fs14.existsSync(janitorLogDir)) {
+                fs14.mkdirSync(janitorLogDir, { recursive: true });
               }
-              fs12.appendFileSync(path13.join(janitorLogDir, "debug.log"), `DEBUG [${date}]: ${finalSynthesis}
+              fs14.appendFileSync(path14.join(janitorLogDir, "debug.log"), `DEBUG [${date}]: ${finalSynthesis}
 `);
             } else if (parts && parts[0]?.text) finalSynthesis = parts[0].text;
             else if (janitorResult.response && janitorResult.response.text) finalSynthesis = janitorResult.response.text();
@@ -2025,8 +2194,8 @@ ${boxBottom}
               const toolContext = { chatId, sessionId: chatId, history };
               const result = await dispatchTool(janitorToolCall.toolName, janitorToolCall.args, toolContext);
               const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace("T", " ");
-              const janitorLogDir = path13.join(LOGS_DIR, "janitor");
-              fs12.appendFileSync(path13.join(janitorLogDir, "debug.log"), `DEBUG [${date}]: RESULT [${janitorToolCall.toolName}]: ${result}
+              const janitorLogDir = path14.join(LOGS_DIR, "janitor");
+              fs14.appendFileSync(path14.join(janitorLogDir, "debug.log"), `DEBUG [${date}]: RESULT [${janitorToolCall.toolName}]: ${result}
 `);
               if (janitorToolCall.toolName === "memory" && !janitorToolCall.args.includes("action='temp'")) {
                 yield { type: "memory_updated" };
@@ -2034,11 +2203,11 @@ ${boxBottom}
             }
           } catch (janitorErr) {
             const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19).replace("T", " ");
-            const janitorErrDir = path13.join(LOGS_DIR, "janitor");
-            if (!fs12.existsSync(janitorErrDir)) {
-              fs12.mkdirSync(janitorErrDir, { recursive: true });
+            const janitorErrDir = path14.join(LOGS_DIR, "janitor");
+            if (!fs14.existsSync(janitorErrDir)) {
+              fs14.mkdirSync(janitorErrDir, { recursive: true });
             }
-            fs12.appendFileSync(path13.join(janitorErrDir, "error.log"), `ERROR [${date}]: ${janitorErr.message}
+            fs14.appendFileSync(path14.join(janitorErrDir, "error.log"), `ERROR [${date}]: ${janitorErr.message}
 `);
             console.error("Janitor Background Tasks Failed:", janitorErr.message);
           }
@@ -2055,8 +2224,11 @@ ${timestamp}`;
         if (isActuallyFinished) break;
         const nextAgentMsg = cleanedTurnText.trim() || "*Working...*";
         modifiedHistory.push({ role: "agent", text: nextAgentMsg });
-        const nextUserMsg = toolResults.length > 0 ? toolResults.join("\n") : "[turn: continue]";
-        modifiedHistory.push({ role: "user", text: nextUserMsg });
+        if (toolResults.length > 0) {
+          toolResults.forEach((tr) => modifiedHistory.push(tr));
+        } else {
+          modifiedHistory.push({ role: "user", text: "[turn: continue]" });
+        }
       }
       yield { type: "status", content: null };
     };
@@ -2064,9 +2236,9 @@ ${timestamp}`;
 });
 
 // src/utils/settings.js
-import fs13 from "fs-extra";
-import path14 from "path";
-var DEFAULT_SETTINGS, loadSettings, saveSettings;
+import fs15 from "fs-extra";
+import path15 from "path";
+var DEFAULT_SETTINGS, loadSettings, migrateToExternal, saveSettings;
 var init_settings = __esm({
   "src/utils/settings.js"() {
     init_paths();
@@ -2088,7 +2260,9 @@ var init_settings = __esm({
         compression: 0,
         autoExec: false,
         allowExternalAccess: false,
-        autoDeleteHistory: "7d"
+        autoDeleteHistory: "7d",
+        useExternalData: false,
+        externalDataPath: ""
       },
       profileData: {
         name: null,
@@ -2098,8 +2272,8 @@ var init_settings = __esm({
     };
     loadSettings = async () => {
       try {
-        if (await fs13.exists(SETTINGS_FILE)) {
-          const saved = await fs13.readJson(SETTINGS_FILE);
+        if (await fs15.exists(SETTINGS_FILE)) {
+          const saved = await fs15.readJson(SETTINGS_FILE);
           return {
             ...DEFAULT_SETTINGS,
             ...saved,
@@ -2113,12 +2287,31 @@ var init_settings = __esm({
       }
       return DEFAULT_SETTINGS;
     };
+    migrateToExternal = async (newPath) => {
+      const { FLUXFLOW_DIR: FLUXFLOW_DIR2 } = await Promise.resolve().then(() => (init_paths(), paths_exports));
+      const folders = ["logs", "secret"];
+      for (const folder of folders) {
+        const src = path15.join(FLUXFLOW_DIR2, folder);
+        const dest = path15.join(newPath, folder);
+        try {
+          if (await fs15.exists(src)) {
+            await fs15.ensureDir(dest);
+            await fs15.copy(src, dest, { overwrite: false });
+          }
+        } catch (err) {
+          console.error(`Migration failed for ${folder}:`, err);
+        }
+      }
+    };
     saveSettings = async (settings) => {
       try {
         const current = await loadSettings();
+        if (!current.systemSettings.useExternalData && settings.systemSettings?.useExternalData && settings.systemSettings?.externalDataPath) {
+          await migrateToExternal(settings.systemSettings.externalDataPath);
+        }
         const updated = { ...current, ...settings };
-        await fs13.ensureDir(path14.dirname(SETTINGS_FILE));
-        await fs13.writeJson(SETTINGS_FILE, updated, { spaces: 2 });
+        await fs15.ensureDir(path15.dirname(SETTINGS_FILE));
+        await fs15.writeJson(SETTINGS_FILE, updated, { spaces: 2 });
         return true;
       } catch (err) {
         console.error("Failed to save settings:", err);
@@ -2267,24 +2460,39 @@ var init_UpdateProcessor = __esm({
   }
 });
 
-// src/utils/terminal.js
-var getTerminalEnv, emojiSpace;
-var init_terminal = __esm({
-  "src/utils/terminal.js"() {
-    getTerminalEnv = () => {
-      if (process.env.TERM_PROGRAM === "vscode") return "vscode";
-      if (process.env.WT_SESSION) return "wt";
-      return "default";
-    };
-    emojiSpace = (baseSpaces = 2) => {
-      const env = getTerminalEnv();
-      if (env === "wt") {
-        return " ".repeat(Math.max(1, baseSpaces - 1));
+// src/utils/setup.js
+import puppeteer2 from "puppeteer";
+import { exec as exec2 } from "child_process";
+import { promisify } from "util";
+import fs16 from "fs";
+var execAsync, checkPuppeteerReady, installPuppeteerBrowser;
+var init_setup = __esm({
+  "src/utils/setup.js"() {
+    execAsync = promisify(exec2);
+    checkPuppeteerReady = () => {
+      try {
+        const exePath = puppeteer2.executablePath();
+        const exists = exePath && fs16.existsSync(exePath);
+        if (exists) return true;
+      } catch (e) {
+        return false;
       }
-      if (env === "vscode") {
-        return " ".repeat(baseSpaces);
+      return false;
+    };
+    installPuppeteerBrowser = async (onStatus) => {
+      if (onStatus) onStatus("\u{1F4E5} Downloading Chromium engine (Wait a moment)...");
+      try {
+        try {
+          await execAsync("pnpm exec puppeteer browsers install chrome");
+        } catch (pnpmErr) {
+          await execAsync("npx -y puppeteer browsers install chrome");
+        }
+        await new Promise((r) => setTimeout(r, 1e3));
+        return { success: true };
+      } catch (err) {
+        console.error("[SETUP ERROR]", err);
+        return { success: false, error: err.message };
       }
-      return " ".repeat(baseSpaces);
     };
   }
 });
@@ -2297,8 +2505,8 @@ __export(app_exports, {
 import React10, { useState as useState6, useEffect as useEffect4, useRef, useMemo } from "react";
 import { Box as Box10, Text as Text10, useInput as useInput4, useStdout } from "ink";
 import Spinner2 from "ink-spinner";
-import fs14 from "fs-extra";
-import { exec as exec2 } from "child_process";
+import fs17 from "fs-extra";
+import { exec as exec3 } from "child_process";
 import { MultilineInput } from "ink-multiline-input";
 import TextInput3 from "ink-text-input";
 import gradient from "gradient-string";
@@ -2353,7 +2561,7 @@ Check what's new using \`/changelog\` command.`,
       if (manual) {
         setMessages((prev) => {
           setCompletedIndex(prev.length + 1);
-          return [...prev, { id: "check-err-" + Date.now(), role: "system", text: `\u274C ERROR: Failed to check for updates: ${err.message}` }];
+          return [...prev, { id: "check-err-" + Date.now(), role: "system", text: `\u274C ERROR: Failed to check for updates: ${err.message}`, isMeta: true }];
         });
       }
     }
@@ -2430,7 +2638,7 @@ Check what's new using \`/changelog\` command.`,
   const [resolutionData, setResolutionData] = useState6(null);
   const [tempModelOverride, setTempModelOverride] = useState6(null);
   const [messages, setMessages] = useState6([
-    { id: "welcome", role: "system", text: FLUX_LOGO + "\n\n\u{1F30A}\u26A1 Welcome to Flux Flow! Type /help for commands.\n" }
+    { id: "welcome", role: "system", text: FLUX_LOGO + "\n\n\u{1F30A}\u26A1 Welcome to Flux Flow! Type /help for commands.\n", isMeta: true }
   ]);
   const queuedPromptRef = useRef(null);
   const [completedIndex, setCompletedIndex] = useState6(1);
@@ -2537,6 +2745,17 @@ Check what's new using \`/changelog\` command.`,
   });
   useEffect4(() => {
     async function init() {
+      if (!checkPuppeteerReady()) {
+        setMessages((prev) => {
+          setCompletedIndex(prev.length + 1);
+          return [...prev, { id: "setup-" + Date.now(), role: "system", text: "\u{1F527} [SYSTEM] Installing Required dependencies... (One-time setup)", isMeta: true }];
+        });
+        await installPuppeteerBrowser();
+        setMessages((prev) => {
+          setCompletedIndex(prev.length + 1);
+          return [...prev, { id: "setup-done-" + Date.now(), role: "system", text: "\u2705 [SYSTEM] All dependencies installed successfully.", isMeta: true }];
+        });
+      }
       const saved = await loadSettings();
       setMode(saved.mode);
       setThinkingLevel(saved.thinkingLevel);
@@ -2587,9 +2806,9 @@ Check what's new using \`/changelog\` command.`,
       await saveAPIKey(key);
       setApiKey(key);
       initAI(key);
-      setMessages((prev) => [...prev, { role: "system", text: "\u2705 API Key saved successfully! Initialization complete." }]);
+      setMessages((prev) => [...prev, { role: "system", text: "\u2705 API Key saved successfully! Initialization complete.", isMeta: true }]);
     } else {
-      setMessages((prev) => [...prev, { role: "system", text: `\u274C INVALID KEY: Gemini API keys must be at least 30 characters.` }]);
+      setMessages((prev) => [...prev, { role: "system", text: `\u274C INVALID KEY: Gemini API keys must be at least 30 characters.`, isMeta: true }]);
       setTempKey("");
     }
   };
@@ -2704,7 +2923,7 @@ ${hintText}`, color: "magenta" }];
         }
         case "/clear": {
           stdout.write("\x1B[2J\x1B[3J\x1B[H");
-          setMessages([{ id: "welcome-" + Date.now(), role: "system", text: FLUX_LOGO + "\n\n\u{1F30A}\u26A1 Welcome back to Flux Flow! Context cleared.\n" }]);
+          setMessages([{ id: "welcome-" + Date.now(), role: "system", text: FLUX_LOGO + "\n\n\u{1F30A}\u26A1 Welcome back to Flux Flow! Context cleared.\n", isMeta: true }]);
           setCompletedIndex(0);
           setChatId(generateChatId());
           setSessionStats({ tokens: 0 });
@@ -2831,12 +3050,12 @@ ${list || "No saved chats found."}`, isMeta: true }];
                 setCompletedIndex(prev.length + 1);
                 return [...prev, { id: Date.now(), role: "system", text: "\u2622\uFE0F [NUCLEAR] Initiating reset...", isMeta: true }];
               });
-              if (fs14.existsSync(LOGS_DIR)) fs14.removeSync(LOGS_DIR);
-              if (fs14.existsSync(SECRET_DIR)) fs14.removeSync(SECRET_DIR);
-              if (fs14.existsSync(SETTINGS_FILE)) fs14.removeSync(SETTINGS_FILE);
+              if (fs17.existsSync(LOGS_DIR)) fs17.removeSync(LOGS_DIR);
+              if (fs17.existsSync(SECRET_DIR)) fs17.removeSync(SECRET_DIR);
+              if (fs17.existsSync(SETTINGS_FILE)) fs17.removeSync(SETTINGS_FILE);
               try {
-                const items = fs14.readdirSync(FLUXFLOW_DIR);
-                if (items.length === 0) fs14.removeSync(FLUXFLOW_DIR);
+                const items = fs17.readdirSync(FLUXFLOW_DIR);
+                if (items.length === 0) fs17.removeSync(FLUXFLOW_DIR);
               } catch (e) {
               }
               setTimeout(() => {
@@ -2868,7 +3087,7 @@ ${list || "No saved chats found."}`, isMeta: true }];
         case "/changelog": {
           const platform = process.platform;
           const command = platform === "win32" ? "start" : platform === "darwin" ? "open" : "xdg-open";
-          exec2(`${command} ${CHANGELOG_URL}`);
+          exec3(`${command} ${CHANGELOG_URL}`);
           setMessages((prev) => {
             setCompletedIndex(prev.length + 1);
             return [...prev, { id: Date.now(), role: "system", text: `\u{1F310} [BROWSER] Opening changelog: ${CHANGELOG_URL}`, isMeta: true }];
@@ -3063,8 +3282,10 @@ Selection: ${val}`,
                 id: "tool-" + Date.now(),
                 role: "system",
                 text: packet.content,
-                fullText: packet.aiContent
+                fullText: packet.aiContent,
                 // Preserve raw data for next turn
+                binaryPart: packet.binaryPart
+                // v1.5.0 Multimodal Support
               }]);
               continue;
             }
@@ -3251,6 +3472,7 @@ Selection: ${val}`,
               { label: `API Tier                                [ ${apiTier} ]`, value: "apiTier" },
               { label: `Auto-Update                             [ ${systemSettings.autoUpdate ? "ON" : "OFF"} ]`, value: "autoUpdate" },
               { label: `Preferred Updater                       [ ${(systemSettings.updateManager || "npm") === "custom" ? "Custom" : (systemSettings.updateManager || "npm").toUpperCase()} ]`, value: "updateManager" },
+              { label: `Save AppData Externally                 [ ${systemSettings.useExternalData ? "ON" : "OFF"} ]`, value: "externalData" },
               { label: "Exit Settings", value: "Cancel" }
             ],
             onSelect: (item) => {
@@ -3283,6 +3505,22 @@ Selection: ${val}`,
                 setSystemSettings((s) => ({ ...s, autoDeleteHistory: options[nextIndex] }));
               } else if (item.value === "autoUpdate") {
                 setSystemSettings((s) => ({ ...s, autoUpdate: !s.autoUpdate }));
+              } else if (item.value === "externalData") {
+                if (!systemSettings.useExternalData) {
+                  setInputConfig({
+                    label: "Enter absolute path for External AppData:",
+                    note: "All history, logs and secrets will be stored here. ~/.fluxflow/settings.json stays as anchor.",
+                    key: "externalDataPath",
+                    value: systemSettings.externalDataPath || ""
+                  });
+                  setActiveView("input");
+                } else {
+                  const newSettings = { ...systemSettings, useExternalData: false };
+                  setSystemSettings(newSettings);
+                  saveSettings({ systemSettings: newSettings, apiTier, quotas });
+                  setMessages((prev) => [...prev, { id: Date.now(), role: "system", text: "\u{1F3E0} [STORAGE RESET] Flux Flow will return to default ~/.fluxflow after restart." }]);
+                  setActiveView("chat");
+                }
               } else if (item.value === "updateManager") {
                 setActiveView("updateManager");
               } else if (item.value === "Cancel") setActiveView("chat");
@@ -3375,6 +3613,11 @@ Selection: ${val}`,
               } else if (key === "janitorModel") {
                 setJanitorModel(val);
                 newSettings.janitorModel = val;
+              } else if (key === "externalDataPath") {
+                const newSysSettings = { ...systemSettings, useExternalData: true, externalDataPath: val.trim() };
+                setSystemSettings(newSysSettings);
+                newSettings.systemSettings = newSysSettings;
+                setMessages((prev) => [...prev, { id: Date.now(), role: "system", text: "\u{1F4C1} [EXTERNAL STORAGE] Flux Flow will use " + val.trim() + " for data after restart." }]);
               }
               if (next) {
                 setInputConfig(next(key === "quotas" ? newQuotas : val));
@@ -3793,10 +4036,11 @@ var init_app = __esm({
     init_paths();
     init_terminal();
     init_exec_command();
+    init_setup();
     SESSION_START_TIME = Date.now();
     CHANGELOG_URL = "https://fluxflow-cli.onrender.com/changelog.html";
-    versionFluxflow = "1.4.2";
-    updatedOn = "2026-04-30";
+    versionFluxflow = "1.5.0";
+    updatedOn = "2026-05-01";
     ResolutionModal = ({ data, onResolve, onEdit }) => /* @__PURE__ */ React10.createElement(Box10, { flexDirection: "column", borderStyle: "round", borderColor: "magenta", paddingX: 2, paddingY: 1, width: "100%" }, /* @__PURE__ */ React10.createElement(Text10, { color: "magenta", bold: true, underline: true }, "\u{1F7E3} STEERING HINT RESOLUTION"), /* @__PURE__ */ React10.createElement(Text10, { marginTop: 1 }, "The agent already finished the task (turn: finish) before your hint was consumed."), /* @__PURE__ */ React10.createElement(Box10, { marginTop: 1, backgroundColor: "#222", paddingX: 1, width: "100%" }, /* @__PURE__ */ React10.createElement(Text10, { italic: true, color: "gray" }, '"', data, '"')), /* @__PURE__ */ React10.createElement(Box10, { marginTop: 1 }, /* @__PURE__ */ React10.createElement(Text10, { color: "cyan" }, "How would you like to proceed?")), /* @__PURE__ */ React10.createElement(Box10, { marginTop: 1 }, /* @__PURE__ */ React10.createElement(
       CommandMenu,
       {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "fluxflow-cli",
-	"version": "1.4.2",
+	"version": "1.5.0",
 	"description": "A high-fidelity agentic terminal assistant for the Flux Era.",
 	"keywords": [
 		"ai",
@@ -34,7 +34,7 @@
 	},
 	"scripts": {
 		"start": "tsx ./src/cli.jsx",
-		"build": "esbuild ./src/cli.jsx --bundle --platform=node --format=esm --outfile=./dist/fluxflow.js --external:react --external:ink --external:chalk --external:fs-extra --external:gradient-string --external:ink-text-input --external:ink-select-input --external:ink-spinner --external:ink-multiline-input --external:@google/genai --external:zod --external:duck-duck-scrape --external:nanoid --external:cuimp"
+		"build": "esbuild ./src/cli.jsx --bundle --platform=node --format=esm --outfile=./dist/fluxflow.js --external:react --external:ink --external:chalk --external:fs-extra --external:gradient-string --external:ink-text-input --external:ink-select-input --external:ink-spinner --external:ink-multiline-input --external:@google/genai --external:zod --external:duck-duck-scrape --external:nanoid --external:cuimp --external:puppeteer --external:typescript"
 	},
 	"dependencies": {
 		"@google/genai": "^1.50.1",
@@ -48,6 +48,7 @@
 		"ink-spinner": "^5.0.0",
 		"ink-text-input": "^6.0.0",
 		"nanoid": "^5.1.9",
+		"puppeteer": "^24.42.0",
 		"react": "^19.2.5",
 		"zod": "^4.3.6"
 	},