fluxflow-cli 1.4.3 → 1.5.1

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.