4runr-os 2.1.49 → 2.1.51

package/README.md

@@ -1,65 +1,256 @@
-# 4Runr OS
-
-Modern Terminal Interface for the 4Runr AI Agent OS.
-
-## Quick Start
-
-### One-Time Setup
-
-```bash
-npm install -g 4runr-os
-```
-
-### Daily Use
-
-```bash
-4r
-```
-
-**That's it!** No other setup needed.
-
----
-
-## Features
-
-- 🚀 **Modern TUI** - Beautiful Rust-based terminal interface
-- 🔄 **Auto-Updates** - Automatically updates when new versions are available
-- 🎯 **Zero Config** - Works out of the box
-- 🪶 **Lightweight** - Fast and efficient
-
-## Commands
-
-- `4r` - Launch the 4Runr OS terminal interface
-- `4runr` - Alias for `4r`
-- `4runr-os` - Alias for `4r`
-
-## Auto-Update
-
-The `4r` command automatically checks for updates and installs them if available. You can control this behavior:
-
-```bash
-# Disable auto-update (still checks)
-NO_AUTO_UPDATE=1 4r
-
-# Disable update check entirely
-NO_UPDATE_CHECK=1 4r
-
-# Or use the config command inside the OS
-4r
-# Then: config auto-update disable
-```
-
-## Requirements
-
-- **Node.js** 18.0.0 or higher
-- **npm** (comes with Node.js)
-
-**No Rust or build tools needed!** Pre-built binaries are included for Windows, Linux, and macOS.
-
-## Troubleshooting
-
-See [SETUP.md](./SETUP.md) for detailed setup instructions and troubleshooting.
-
-## License
-
-MIT
+# 4Runr OS
+
+<div align="center">
+
+![4Runr OS](https://img.shields.io/npm/v/4runr-os?style=for-the-badge)
+![License](https://img.shields.io/npm/l/4runr-os?style=for-the-badge)
+![Node](https://img.shields.io/node/v/4runr-os?style=for-the-badge)
+
+**Production-ready terminal interface for managing AI agents with real-time monitoring, safety controls, and enterprise features.**
+
+[Installation](#-installation) • [Features](#-features) • [Documentation](#-documentation) • [Support](#-support)
+
+</div>
+
+---
+
+## 📸 Screenshots
+
+### Boot Screen
+
+![4Runr OS Boot Screen](./images/screenshot-boot.png)
+
+*Initialization screen showing system startup and readiness status.*
+
+### Main Interface
+
+![4Runr OS Terminal Interface](./images/screenshot.png)
+
+*Full terminal interface showing system status, operations log, resources, and capabilities.*
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+npm install -g 4runr-os
+```
+
+### Usage
+
+```bash
+4r
+```
+
+**That's it!** The terminal interface launches automatically.
+
+---
+
+## ✨ Features
+
+### 🎨 Modern Terminal Interface
+- **Rust + Ratatui** - High-performance, native terminal UI
+- **Real-time Updates** - Live monitoring of agent runs, system resources, and network status
+- **Beautiful Design** - Clean, professional interface with 4Runr brand colors
+- **Cross-platform** - Works on Windows, macOS, and Linux
+
+### 🔒 Enterprise Safety Features
+- **Shield System** - PII detection, injection blocking, hallucination checks
+- **Sentinel Monitoring** - Real-time safety monitoring and alerting
+- **Policy Enforcement** - Configurable safety policies and controls
+- **Audit Logging** - Complete audit trail of all operations
+
+### 📊 Real-time Monitoring
+- **System Status** - CPU, memory, network monitoring
+- **Agent Operations** - Live log streaming and status updates
+- **Gateway Health** - Connection status and metrics
+- **Resource Tracking** - Active runs, connections, and capabilities
+
+### 🔄 Auto-Update System
+- **Automatic Updates** - Checks for and installs new versions automatically
+- **Configurable** - Enable/disable auto-updates via config command
+- **Zero Downtime** - Updates happen seamlessly in the background
+
+### 🛠️ Developer Experience
+- **Zero Configuration** - Works out of the box
+- **Pre-built Binaries** - No Rust or build tools required
+- **Fast Startup** - Optimized for quick launch times
+- **Comprehensive Logging** - Detailed logs for debugging
+
+---
+
+## 📋 Commands
+
+### Global Commands
+
+| Command | Description |
+|---------|-------------|
+| `4r` | Launch the 4Runr OS terminal interface (recommended) |
+| `4runr` | Alias for `4r` |
+| `4runr-os` | Alias for `4r` |
+| `4runr-setup` | Run initial setup wizard |
+
+### In-Terminal Commands
+
+Once the TUI is running, you can use these commands:
+
+- `help` - Show all available commands
+- `config` - Manage configuration settings
+- `status` - Show system status
+- `agents` - List available agents
+- `runs` - View agent run history
+- `exit` or `Ctrl+C` - Exit the terminal
+
+---
+
+## ⚙️ Configuration
+
+### Auto-Update Settings
+
+Control automatic updates from within the OS:
+
+```bash
+4r
+# Then in the terminal:
+config auto-update disable   # Disable automatic updates
+config auto-update enable    # Enable automatic updates
+config auto-update status    # Check current setting
+```
+
+### Environment Variables
+
+```bash
+# Disable auto-update (still checks for updates)
+NO_AUTO_UPDATE=1 4r
+
+# Disable update check entirely
+NO_UPDATE_CHECK=1 4r
+
+# Set custom gateway URL
+GATEWAY_URL=http://your-gateway:3001 4r
+```
+
+### Configuration File
+
+Settings are saved in `~/.4runr/config.json` and persist across sessions.
+
+---
+
+## 📦 Requirements
+
+- **Node.js** 18.0.0 or higher
+- **npm** (comes with Node.js)
+
+**No Rust or build tools needed!** Pre-built binaries are included for:
+- Windows (x64)
+- macOS (x64, ARM64)
+- Linux (x64, ARM64)
+
+---
+
+## 🏗️ Architecture
+
+4Runr OS is built with:
+
+- **Frontend**: Rust + Ratatui for the terminal interface
+- **Backend**: Node.js for orchestration and gateway communication
+- **Communication**: HTTP/SSE for real-time updates
+- **Safety**: Built-in Shield and Sentinel systems
+
+```
+┌─────────────────┐
+│   4Runr OS      │  ← Terminal Interface (Rust + Ratatui)
+│   (TUI)         │
+└────────┬────────┘
+         │ HTTP/SSE
+         ▼
+┌─────────────────┐
+│   4Runr Gateway │  ← API Gateway (Node.js)
+│   (Backend)     │
+└─────────────────┘
+```
+
+---
+
+## 📚 Documentation
+
+- **[Setup Guide](./SETUP.md)** - Detailed setup instructions and troubleshooting
+- **[User Privacy](./USER-PRIVACY.md)** - Privacy policy and data handling
+- **[Easy Usage](./EASY-USAGE.md)** - Quick reference guide
+- **[Contributing](./CONTRIBUTING-CLI.md)** - How to contribute to the project
+
+---
+
+## 🔧 Troubleshooting
+
+### "mk3-tui binary not found"
+
+The package will try to auto-install it. If that fails:
+
+```bash
+npm install -g 4runr-os-mk3
+```
+
+### "4r: command not found"
+
+Make sure npm global bin is in your PATH:
+
+```bash
+# Check PATH
+echo $PATH | grep npm
+
+# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
+export PATH=$PATH:$(npm config get prefix)/bin
+```
+
+### Terminal too small
+
+The TUI requires a minimum terminal size of 80x24. Resize your terminal window.
+
+### Connection issues
+
+Check your gateway URL:
+
+```bash
+# Test gateway connection
+curl http://your-gateway:3001/health
+
+# Set gateway URL
+export GATEWAY_URL=http://your-gateway:3001
+4r
+```
+
+---
+
+## 🤝 Support
+
+- **Issues**: [GitHub Issues](https://github.com/KyanBergeron4Runr/4Runr-AI-Agent-OS/issues)
+- **Documentation**: [Full Documentation](./SETUP.md)
+- **Website**: [4Runr.com](https://4runr.com)
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](../LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+Built with:
+- [Ratatui](https://github.com/ratatui-org/ratatui) - Terminal UI library
+- [Rust](https://www.rust-lang.org/) - Systems programming language
+- [Node.js](https://nodejs.org/) - JavaScript runtime
+
+---
+
+<div align="center">
+
+**Made with ❤️ by the 4Runr Team**
+
+[⬆ Back to Top](#4runr-os)
+
+</div>

package/SETUP.md

@@ -1,85 +1,85 @@
-# 4Runr OS - Quick Setup Guide
-
-## One-Time Setup
-
-**Step 1: Install**
-```bash
-npm install -g 4runr-os
-```
-
-**Step 2: Run Setup (Auto-detects and fixes everything)**
-```bash
-4runr-setup
-```
-
-Or if that doesn't work:
-```bash
-npm run -g setup
-```
-
-**That's it!** The setup script will:
-- ✅ Check Node.js and npm
-- ✅ Install Rust if needed
-- ✅ Fix Windows MSVC linker issues automatically
-- ✅ Build mk3-tui binary
-- ✅ Verify everything is ready
-
-## Daily Use
-
-```bash
-4r
-```
-
-**Done!** Just `4r` every time. It will verify everything is ready before launching.
-
----
-
-## After Setup
-
-Once installed, just run:
-
-```bash
-4r
-```
-
-That's all you need! The `4r` command will:
-- ✅ Launch the 4Runr OS terminal interface
-- ✅ Auto-update when new versions are available
-- ✅ Work immediately (no additional setup needed)
-
----
-
-## Troubleshooting
-
-### "4r: command not found"
-
-Make sure npm global bin is in your PATH:
-
-**Windows:**
-```powershell
-# Add to PATH (add to your PowerShell profile)
-$env:Path += ";$env:APPDATA\npm"
-```
-
-**Linux/macOS:**
-```bash
-# Add to PATH (add to ~/.bashrc or ~/.zshrc)
-export PATH=$PATH:$(npm config get prefix)/bin
-```
-
-### "mk3-tui binary not found"
-
-This shouldn't happen if binaries are included in the package. If you see this:
-
-1. Make sure you have the latest version: `npm install -g 4runr-os@latest`
-2. If still happening, the package will try to build from source automatically (requires Rust)
-
----
-
-## That's It!
-
-- **One-time setup**: `npm install -g 4runr-os`
-- **Daily use**: `4r`
-
-No other commands needed! 🚀
-
+# 4Runr OS - Quick Setup Guide
+
+## One-Time Setup
+
+**Step 1: Install**
+```bash
+npm install -g 4runr-os
+```
+
+**Step 2: Run Setup (Auto-detects and fixes everything)**
+```bash
+4runr-setup
+```
+
+Or if that doesn't work:
+```bash
+npm run -g setup
+```
+
+**That's it!** The setup script will:
+- ✅ Check Node.js and npm
+- ✅ Install Rust if needed
+- ✅ Fix Windows MSVC linker issues automatically
+- ✅ Build mk3-tui binary
+- ✅ Verify everything is ready
+
+## Daily Use
+
+```bash
+4r
+```
+
+**Done!** Just `4r` every time. It will verify everything is ready before launching.
+
+---
+
+## After Setup
+
+Once installed, just run:
+
+```bash
+4r
+```
+
+That's all you need! The `4r` command will:
+- ✅ Launch the 4Runr OS terminal interface
+- ✅ Auto-update when new versions are available
+- ✅ Work immediately (no additional setup needed)
+
+---
+
+## Troubleshooting
+
+### "4r: command not found"
+
+Make sure npm global bin is in your PATH:
+
+**Windows:**
+```powershell
+# Add to PATH (add to your PowerShell profile)
+$env:Path += ";$env:APPDATA\npm"
+```
+
+**Linux/macOS:**
+```bash
+# Add to PATH (add to ~/.bashrc or ~/.zshrc)
+export PATH=$PATH:$(npm config get prefix)/bin
+```
+
+### "mk3-tui binary not found"
+
+This shouldn't happen if binaries are included in the package. If you see this:
+
+1. Make sure you have the latest version: `npm install -g 4runr-os@latest`
+2. If still happening, the package will try to build from source automatically (requires Rust)
+
+---
+
+## That's It!
+
+- **One-time setup**: `npm install -g 4runr-os`
+- **Daily use**: `4r`
+
+No other commands needed! 🚀
+

package/USER-PRIVACY.md

@@ -1,81 +1,81 @@
-# User Privacy & System Cleanliness
-
-## What We Install
-
-4runr-os **only installs what's necessary** and **respects your system**:
-
-### ✅ What Gets Installed (Only if Missing)
-
-1. **Rust** (optional)
-   - Only if not already installed
-   - **User must install manually** (we provide instructions, don't auto-install)
-   - Required for building mk3-tui binary
-
-2. **MinGW/MSYS2** (Windows only, optional)
-   - Only if MSVC linker not available
-   - Only if not already installed
-   - Used for Rust GNU toolchain on Windows
-
-3. **mk3-tui Binary**
-   - Built from source included in package
-   - Only if pre-built binary not available
-   - Stored in package directory (not system directories)
-
-### ✅ What We Never Do
-
-- ❌ Never install system-wide software without user consent
-- ❌ Never modify system PATH permanently without asking
-- ❌ Never download large files unnecessarily
-- ❌ Never leave temporary files on your system
-- ❌ Never modify registry or system settings
-- ❌ Never auto-install Rust (user must do it manually)
-
-### 🧹 Automatic Cleanup
-
-The package automatically cleans up:
-
-1. **Build Artifacts** (after building)
-   - Removes Rust debug builds (~200-300MB saved)
-   - Removes incremental compilation artifacts
-   - Keeps only the final release binary
-
-2. **Old Versions** (during updates)
-   - Removes old npm package versions (keeps last 2)
-   - Prevents disk space overflow from version history
-
-3. **No Temporary Files**
-   - All operations use existing directories
-   - No temp files created or left behind
-
-### 📦 Package Contents
-
-The npm package includes:
-- ✅ Compiled TypeScript (dist/)
-- ✅ Rust source code (for building if needed)
-- ✅ Setup scripts (for one-time setup)
-- ❌ Build artifacts (excluded via .npmignore)
-- ❌ Source TypeScript (excluded - only dist/ included)
-- ❌ Development files
-
-### 🔒 What We Touch
-
-**User's System:**
-- ✅ npm global install directory (standard npm location)
-- ✅ PATH environment variable (session-only, unless user approves permanent)
-- ❌ System directories (we never touch system files)
-- ❌ Registry/configuration files (Windows)
-- ❌ User's home directory (except standard npm locations)
-
-**User's Data:**
-- ✅ Configuration file: `~/.4runr/config.json` (for user preferences)
-- ❌ User's files or documents (never accessed)
-- ❌ Browser data or history (never accessed)
-- ❌ Personal information (never collected)
-
-### 🛡️ Privacy Guarantee
-
-- No telemetry or tracking
-- No data collection
-- No external network calls (except npm registry for updates)
-- All operations are local
-
+# User Privacy & System Cleanliness
+
+## What We Install
+
+4runr-os **only installs what's necessary** and **respects your system**:
+
+### ✅ What Gets Installed (Only if Missing)
+
+1. **Rust** (optional)
+   - Only if not already installed
+   - **User must install manually** (we provide instructions, don't auto-install)
+   - Required for building mk3-tui binary
+
+2. **MinGW/MSYS2** (Windows only, optional)
+   - Only if MSVC linker not available
+   - Only if not already installed
+   - Used for Rust GNU toolchain on Windows
+
+3. **mk3-tui Binary**
+   - Built from source included in package
+   - Only if pre-built binary not available
+   - Stored in package directory (not system directories)
+
+### ✅ What We Never Do
+
+- ❌ Never install system-wide software without user consent
+- ❌ Never modify system PATH permanently without asking
+- ❌ Never download large files unnecessarily
+- ❌ Never leave temporary files on your system
+- ❌ Never modify registry or system settings
+- ❌ Never auto-install Rust (user must do it manually)
+
+### 🧹 Automatic Cleanup
+
+The package automatically cleans up:
+
+1. **Build Artifacts** (after building)
+   - Removes Rust debug builds (~200-300MB saved)
+   - Removes incremental compilation artifacts
+   - Keeps only the final release binary
+
+2. **Old Versions** (during updates)
+   - Removes old npm package versions (keeps last 2)
+   - Prevents disk space overflow from version history
+
+3. **No Temporary Files**
+   - All operations use existing directories
+   - No temp files created or left behind
+
+### 📦 Package Contents
+
+The npm package includes:
+- ✅ Compiled TypeScript (dist/)
+- ✅ Rust source code (for building if needed)
+- ✅ Setup scripts (for one-time setup)
+- ❌ Build artifacts (excluded via .npmignore)
+- ❌ Source TypeScript (excluded - only dist/ included)
+- ❌ Development files
+
+### 🔒 What We Touch
+
+**User's System:**
+- ✅ npm global install directory (standard npm location)
+- ✅ PATH environment variable (session-only, unless user approves permanent)
+- ❌ System directories (we never touch system files)
+- ❌ Registry/configuration files (Windows)
+- ❌ User's home directory (except standard npm locations)
+
+**User's Data:**
+- ✅ Configuration file: `~/.4runr/config.json` (for user preferences)
+- ❌ User's files or documents (never accessed)
+- ❌ Browser data or history (never accessed)
+- ❌ Personal information (never collected)
+
+### 🛡️ Privacy Guarantee
+
+- No telemetry or tracking
+- No data collection
+- No external network calls (except npm registry for updates)
+- All operations are local
+