samarthya-bot 2.2.0 → 2.3.0

package/README.md

@@ -1,336 +1,341 @@
+<!-- ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ HERO ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ -->
+
 <div align="center">
-  <img src="https://raw.githubusercontent.com/mebishnusahu0595/SamarthyaBot/main/backend/public/logo.png" width="180" height="180" alt="SamarthyaBot Logo — Privacy-First AI Agent OS">
-
-  <h1>🇮🇳 SamarthyaBot — Privacy-First Local Agentic AI Operating System</h1>
-
-  <h3>The Best Open-Source Self-Hosted AI Agent for Indian Developers</h3>
-  <p><strong>Multi-Agent · Autonomous · Privacy-First · Offline-Capable · Made in India 🇮🇳</strong></p>
-
-  <p>
-    <a href="https://www.npmjs.com/package/samarthya-bot"><img src="https://img.shields.io/npm/v/samarthya-bot?color=FF9933&style=for-the-badge&logo=npm&logoColor=white&label=NPM" alt="NPM Version"></a>
-    <a href="https://www.npmjs.com/package/samarthya-bot"><img src="https://img.shields.io/npm/dm/samarthya-bot?color=138808&style=for-the-badge&logo=npm&logoColor=white&label=Downloads" alt="NPM Downloads"></a>
-    <a href="https://github.com/mebishnusahu0595/SamarthyaBot"><img src="https://img.shields.io/github/stars/mebishnusahu0595/SamarthyaBot?style=for-the-badge&color=FFD600&logo=github" alt="GitHub Stars"></a>
-    <a href="https://github.com/mebishnusahu0595/SamarthyaBot/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-138808?style=for-the-badge" alt="MIT License"></a>
-  </p>
-
-  <p>
-    <img src="https://img.shields.io/badge/Node.js-20_LTS-339933?style=flat&logo=nodedotjs&logoColor=white" alt="Node.js 20 LTS">
-    <img src="https://img.shields.io/badge/Go-1.22+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go Worker">
-    <img src="https://img.shields.io/badge/React-19-61DAFB?style=flat&logo=react&logoColor=black" alt="React 19">
-    <img src="https://img.shields.io/badge/MongoDB-Local-47A248?style=flat&logo=mongodb&logoColor=white" alt="MongoDB">
-    <img src="https://img.shields.io/badge/Express-5-000000?style=flat&logo=express&logoColor=white" alt="Express 5">
-    <img src="https://img.shields.io/badge/Socket.IO-Realtime-010101?style=flat&logo=socketdotio&logoColor=white" alt="Socket.IO">
-    <img src="https://img.shields.io/badge/Puppeteer-Browser-40B5A4?style=flat&logo=puppeteer&logoColor=white" alt="Puppeteer">
-    <img src="https://img.shields.io/badge/PRs-welcome-FF9933?style=flat" alt="PRs Welcome">
-  </p>
-
-  <p>
-    <a href="#-quick-start-install-in-60-seconds">Quick Start</a> ·
-    <a href="#-features--capabilities">Features</a> ·
-    <a href="#-supported-ai-providers">AI Providers</a> ·
-    <a href="#-chat-channels--integrations">Integrations</a> ·
-    <a href="#-frequently-asked-questions-faq">FAQ</a> ·
-    <a href="CONTRIBUTING.md">Contributing</a>
-  </p>
+
+<img src="https://capsule-render.vercel.app/api?type=waving&color=0:FF9933,50:FFFFFF,100:138808&height=200&section=header&text=SamarthyaBot&fontSize=70&fontColor=222222&animation=fadeIn&fontAlignY=38&desc=Privacy-First%20Local%20Agentic%20AI%20Operating%20System&descAlignY=60&descSize=18" width="100%" alt="SamarthyaBot"/>
+
+<a href="https://github.com/mebishnusahu0595/SamarthyaBot">
+  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=22&pause=1000&color=FF9933&center=true&vCenter=true&width=720&lines=Self-hosted+multi-agent+RPA+for+Windows%2C+macOS+%26+Linux;Writes+code+%E2%80%A2+Deploys+via+SSH+%E2%80%A2+Controls+browsers;34%2B+skills+%E2%80%A2+9+AI+providers+%E2%80%A2+100%25+offline+with+Ollama;Made+in+India+%F0%9F%87%AE%F0%9F%87%B3+for+the+world" alt="Typing SVG" />
+</a>
+
+<p>
+  <strong>Multi-Agent · Autonomous · Privacy-First · Offline-Capable · Cross-Platform · Made in India 🇮🇳</strong>
+</p>
+
+<p>
+  <a href="https://www.npmjs.com/package/samarthya-bot"><img src="https://img.shields.io/npm/v/samarthya-bot?color=FF9933&style=for-the-badge&logo=npm&logoColor=white&label=NPM" alt="NPM Version"></a>
+  <a href="https://www.npmjs.com/package/samarthya-bot"><img src="https://img.shields.io/npm/dm/samarthya-bot?color=138808&style=for-the-badge&logo=npm&logoColor=white&label=Downloads" alt="NPM Downloads"></a>
+  <a href="https://github.com/mebishnusahu0595/SamarthyaBot/stargazers"><img src="https://img.shields.io/github/stars/mebishnusahu0595/SamarthyaBot?style=for-the-badge&color=FFD600&logo=github" alt="GitHub Stars"></a>
+  <a href="https://github.com/mebishnusahu0595/SamarthyaBot/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-138808?style=for-the-badge" alt="MIT License"></a>
+</p>
+
+<p>
+  <img src="https://img.shields.io/badge/Windows-0078D6?style=flat&logo=windows&logoColor=white" alt="Windows">
+  <img src="https://img.shields.io/badge/macOS-000000?style=flat&logo=apple&logoColor=white" alt="macOS">
+  <img src="https://img.shields.io/badge/Linux-FCC624?style=flat&logo=linux&logoColor=black" alt="Linux">
+  <img src="https://img.shields.io/badge/Node.js-20_LTS-339933?style=flat&logo=nodedotjs&logoColor=white" alt="Node.js 20 LTS">
+  <img src="https://img.shields.io/badge/Go-Worker-00ADD8?style=flat&logo=go&logoColor=white" alt="Go Worker">
+  <img src="https://img.shields.io/badge/React-19-61DAFB?style=flat&logo=react&logoColor=black" alt="React 19">
+  <img src="https://img.shields.io/badge/MongoDB-Local-47A248?style=flat&logo=mongodb&logoColor=white" alt="MongoDB">
+</p>
+
+<p>
+  <a href="#-quick-start-60-seconds">Quick Start</a> ·
+  <a href="#️-cross-platform-by-design">Cross-Platform</a> ·
+  <a href="#-skills-catalog-34-built-in-tools">Skills</a> ·
+  <a href="#-chat-slash-commands">Commands</a> ·
+  <a href="#-supported-ai-providers">AI Providers</a> ·
+  <a href="#-frequently-asked-questions">FAQ</a> ·
+  <a href="CONTRIBUTING.md">Contribute</a>
+</p>
+
 </div>
 
 ---
 
 ## 🤔 What is SamarthyaBot?
 
-**SamarthyaBot** (समर्थ्य बोट) is a **privacy-first, self-hosted, multi-agent AI operating system** that runs entirely on YOUR machine. Unlike cloud-based AI assistants, SamarthyaBot keeps all your data local, encrypted, and under your control.
+**SamarthyaBot** (समर्थ्य बोट) is a **privacy-first, self-hosted, multi-agent AI operating system** that runs entirely on **your** machine — Windows, macOS, or Linux. Unlike cloud assistants, it keeps your data local, encrypted, and under your control.
 
-It is **not just a chatbot** — it's a **Full RPA (Robotic Process Automation) Agent** that can:
+It is **not just a chatbot** — it's a full **RPA (Robotic Process Automation) agent** that can:
 
-- ✍️ **Write code** and commit to GitHub automatically
+- ✍️ **Write code** and commit to GitHub
 - 🚀 **Deploy to servers** via SSH (password or PEM key)
-- 🌐 **Control real browsers** with Puppeteer (scrape, click, navigate, fill forms)
-- 📧 **Send real emails** via SMTP — not simulations
-- 🇮🇳 **Handle Indian workflows** — GST calculations, UPI payment links, IRCTC queries
-- 🧠 **Think autonomously** using a ReAct planning engine
-- 💬 **Chat on Telegram, Discord, and Web Dashboard**
-- 🎙️ **Understand voice messages** via Groq/Whisper transcription
-- 🔌 **Extend with plugins** — drop a `.js` file for new AI capabilities
-
-> **SamarthyaBot is the most feature-rich, self-hosted AI agent built specifically for Indian developers.** It supports Hindi, Hinglish, and English seamlessly, and works with 9 AI providers including free options like Gemini and Ollama (fully offline).
+- 🌐 **Control real browsers** with Puppeteer (scrape, click, fill forms)
+- 📧 **Send real emails** via SMTP
+- 🇮🇳 **Handle Indian workflows** — GST, UPI, IRCTC, QR codes, Hindi/Hinglish
+- 🧠 **Think autonomously** with a 20-step ReAct planning loop
+- 💬 **Chat on Telegram, Discord & a Web Dashboard** — with `/slash` commands
+- 🎙️ **Understand voice** via Groq/Whisper transcription
+- 🔌 **Extend with plugins** — drop a `.js` file for a new skill
 
----
-
-## 🌟 Why SamarthyaBot? (Key Differentiators)
-
-| Why Choose SamarthyaBot | Details |
-| :--- | :--- |
-| 🔒 **100% Privacy** | Your data NEVER leaves your machine. All memories encrypted with AES-256-CBC |
-| 🇮🇳 **Built for India** | GST, UPI, IRCTC, Hindi/Hinglish — first-class Indian workflow support |
-| 🤖 **True RPA Agent** | Not just chat — writes code, deploys servers, controls browsers autonomously |
-| ⚡ **9 AI Providers** | Gemini (free), Claude, GPT, Ollama (offline), DeepSeek, Qwen, OpenRouter, Groq, Mistral |
-| 📦 **One-Command Install** | `npm install -g samarthya-bot` — ready in 60 seconds |
-| 🔌 **Plugin System** | Drop a `.js` file → instant new AI capability. Zero restart |
-| 💻 **Beautiful Dashboard** | Modern React UI with dark theme, glassmorphism, and realtime updates |
-| 🌐 **Multi-Channel** | Telegram + Discord + Web Dashboard — chat from anywhere |
-| 🔧 **Go Micro-Worker** | Live terminal streaming — run `npm build`, `git push` without freezing Node.js |
+> **The most feature-rich, self-hosted AI agent that runs identically on all three OSes** — with 34 built-in skills, 9 AI providers, and a free fully-offline mode via Ollama.
 
 ---
 
-## ✨ Features & Capabilities
+## 🖥️ Cross-Platform by Design
 
-| Feature | Description | Status |
-| :--- | :--- | :---: |
-| 🤖 **Full RPA Engine** | Writes code, commits to GitHub, deploys to VPS autonomously | ✅ Live |
-| ⚡ **Go Micro-Worker** | Live terminal streaming — `npm build`, `git push` without freezing Node.js | ✅ Live |
-| 🌍 **SSH Deployments** | Deploy to remote servers via password or PEM key from a chat prompt | ✅ Live |
-| 🕸️ **Browser Controller** | Puppeteer-based real DOM interaction — scrape, click, navigate websites | ✅ Live |
-| 🛡️ **Zero-Harm Blacklists** | OS regex block-layer protects against dangerous commands like `rm -rf` | ✅ Live |
-| 🧠 **Autonomous Planner** | ReAct engine breaks complex requests into discrete executable steps | ✅ Live |
-| 🔐 **Encrypted Memory** | AES-256-CBC encrypted local memory stored in MongoDB | ✅ Live |
-| 🇮🇳 **Indian Localization** | GST calculator, UPI payment links, IRCTC, Hindi/Hinglish fluency | ✅ Live |
-| 📧 **Real Email** | Send actual emails via Nodemailer SMTP — not a simulation | ✅ Live |
-| 📁 **File Manager** | Read, write, edit, append, list files in your workspace | ✅ Live |
-| 👁️ **Screen Vision** | Gemini Vision analyzes screenshots for UI/UX understanding | ✅ Live |
-| 📱 **Telegram Bot** | Full two-way Telegram integration with webhook + tunnel | ✅ Live |
-| 🌐 **Web Dashboard** | Beautiful React UI to manage agent, view logs, chat live | ✅ Live |
-| 🔌 **Plugin System** | Drop a `.js` file → new AI skill. Zero restart needed | ✅ Live |
-| 🤖 **Multi-LLM Support** | Gemini, Claude, GPT, DeepSeek, Qwen, OpenRouter, Ollama, Groq, Mistral | ✅ Live |
-| 🎙️ **Voice (Whisper)** | Groq/Whisper transcription for Telegram voice notes | ✅ Live |
-| 💬 **Discord Bot** | Full Discord integration with mention-only mode | ✅ Live |
-| 🔒 **Workspace Sandbox** | File ops restricted to workspace, configurable security | ✅ Live |
-| 💓 **Heartbeat Tasks** | Periodic autonomous tasks from `HEARTBEAT.md` | ✅ Live |
-| 🚀 **Sub-Agent Spawn** | Non-blocking background agents for long-running tasks | ✅ Live |
-
----
+SamarthyaBot **detects your OS at runtime** and adapts every shell command, file path, browser launch, and "open" action accordingly. No more "works on Linux, breaks on Windows."
 
-## 🧠 Supported AI Providers
+| Capability | 🪟 Windows | 🍎 macOS | 🐧 Linux |
+| :--- | :---: | :---: | :---: |
+| **Shell execution** | `cmd.exe` | `/bin/sh` | `/bin/sh` |
+| **Open URL/file/app** | `start` | `open` | `xdg-open` |
+| **Live terminal streaming** | ✅ Go worker → **Node fallback** | ✅ Go worker → **Node fallback** | ✅ Go worker |
+| **Browser discovery** | Chrome / Edge / Brave | Chrome / Chromium / Edge / Brave | Chrome / Chromium / Edge / Brave |
+| **Clipboard** | `clip` | `pbcopy` | `xclip` / `xsel` / `wl-copy` |
+| **Port management (CLI)** | `netstat` + `taskkill` | `lsof` | `lsof` / `fuser` |
 
-SamarthyaBot supports **9 AI providers** — including free and fully offline options:
+> ⚙️ **How it works:** A single source of truth — `backend/services/system/platform.js` — resolves OS-specific behaviour. The LLM is also told the exact host OS in its system prompt, so it only emits commands valid for your platform.
 
-| Provider | Models | Cost | Best For |
-| :--- | :--- | :--- | :--- |
-| **Google Gemini** | gemini-2.5-flash, gemini-2.5-pro | 🟢 Free tier | Default, great balance |
-| **Ollama** | Llama 3, Mistral, Dolphin | 🟢 Free (local) | 100% offline, zero data leakage |
-| **Groq** | Llama 3.3 70B, Qwen3 32B | 🟢 Free tier | Fastest inference |
-| **Anthropic** | Claude 3.5 Sonnet, Claude 3 Opus | 🟡 Paid | Smartest reasoning |
-| **OpenAI** | GPT-5.2, GPT-5-mini, o3-mini | 🟡 Paid | Coding & agentic tasks |
-| **DeepSeek** | DeepSeek Chat, DeepSeek Coder | 🟢 Budget | Affordable coding |
-| **Qwen** | Qwen Max, Qwen Turbo | 🟢 Budget | Alibaba's best |
-| **OpenRouter** | 100+ models | 🟡 Varies | Access any model |
-| **Mistral** | Mistral Large 3, Devstral 2 | 🟡 Paid | EU privacy, code agents |
+> 🔁 **Zero-binary fallback:** The optional ultra-fast Go micro-worker streams long commands. If its binary isn't built for your platform, SamarthyaBot **transparently falls back to a native Node executor** — so heavy DevOps tasks work everywhere, out of the box.
 
 ---
 
-## 🚀 Quick Start — Install in 60 Seconds
+## 🚀 Quick Start (60 Seconds)
 
 > **Prerequisites:** [Node.js 20 LTS](https://nodejs.org/) · [MongoDB](https://www.mongodb.com/try/download/community) (local)
->
-> Get API keys: [Gemini](https://aistudio.google.com/api-keys) (Free) · [Ollama](https://ollama.com) (Free, Local)
->
-> Optional: [Telegram Bot Token](https://t.me/BotFather) · [Groq](https://console.groq.com) (Voice) · [OpenRouter](https://openrouter.ai/keys) (100+ models)
+> Free API keys: [Gemini](https://aistudio.google.com/api-keys) · [Ollama](https://ollama.com) (offline)
 
-### 📦 Install from NPM (Recommended)
+### 📦 Install from NPM (recommended)
 
 ```bash
-# Install globally
+# 1. Install globally (works on Windows, macOS, Linux)
 npm install -g samarthya-bot
 
-# Interactive setup wizard — configures AI keys, channels, everything
+# 2. Interactive setup wizard — picks provider, keys, channels
 samarthya onboard
 
-# Launch the engine + dashboard (Terminal 1)
+# 3. Launch engine + dashboard
 samarthya gateway
 
-# Expose to internet & link Telegram (Terminal 2)
+# 4. (Optional) Expose to internet & link Telegram
 samarthya tunnel
 ```
 
-That's it! 🎉 Open **http://localhost:5000** for the Dashboard.
+🎉 Open **http://localhost:5000** for the dashboard.
 
-### 🛠️ Install from Source (Development)
+### 🛠️ From source (development)
 
 ```bash
 git clone https://github.com/mebishnusahu0595/SamarthyaBot.git
 cd SamarthyaBot
-
-# Install all dependencies
 npm install
-
-# Setup API keys interactively
 samarthya onboard
-
-# Start development server
 npm run start
 ```
 
 ---
 
-## 💬 Chat Channels & Integrations
+## ✨ Core Features
+
+| Feature | Description | Status |
+| :--- | :--- | :---: |
+| 🖥️ **True Cross-Platform** | OS auto-detected; commands adapt to Windows/macOS/Linux | ✅ Live |
+| 🤖 **Full RPA Engine** | Writes code, commits to GitHub, deploys to VPS | ✅ Live |
+| ⚡ **Live Terminal** | Go micro-worker streaming + automatic Node fallback | ✅ Live |
+| 🌍 **SSH Deployments** | Remote deploy via password or PEM key from a chat prompt | ✅ Live |
+| 🕸️ **Browser Controller** | Puppeteer real DOM — scrape, click, navigate, fill forms | ✅ Live |
+| 🛡️ **Hardened Sandbox** | Workspace path enforcement + chained-command blacklist | ✅ Live |
+| 🧠 **Autonomous Planner** | 20-step ReAct loop with failure recovery & retries | ✅ Live |
+| 💬 **Slash Commands** | `/status`, `/tools`, `/pack`, `/model` on every channel | ✅ Live |
+| 🔐 **Encrypted Memory** | AES-256-CBC encrypted local memory in MongoDB | ✅ Live |
+| 🇮🇳 **Indian Localization** | GST, UPI, QR codes, IRCTC, Hindi/Hinglish | ✅ Live |
+| 🛠️ **34 Built-in Skills** | Files, web, crypto, translate, QR, currency & more | ✅ Live |
+| 📱 **Telegram + Discord** | Two-way bots with webhooks, mentions & voice | ✅ Live |
+| 🌐 **React Dashboard** | Dark glassmorphism UI with realtime updates | ✅ Live |
+| 🔌 **Plugin System** | Drop a `.js` file → new AI skill, zero restart | ✅ Live |
+| 🎙️ **Voice (Whisper)** | Groq/Whisper transcription for voice notes | ✅ Live |
+| 💓 **Heartbeat Tasks** | Periodic autonomous tasks from `HEARTBEAT.md` | ✅ Live |
+
+---
+
+## 🧰 Skills Catalog (34 Built-in Tools)
+
+<table>
+<tr><th>📁 Files & System</th><th>🌐 Web & Network</th></tr>
+<tr><td valign="top">
+
+- `file_read` · `file_write` · `file_list`
+- `run_command` *(OS-aware)*
+- `devops_execute_stream` *(live)*
+- `ssh_deploy`
+- `open_path` *(start/open/xdg-open)*
+- `clipboard_copy` *(cross-platform)*
+- `capture_desktop_screenshot`
+- `system_info`
+- `schedule_background_task`
+
+</td><td valign="top">
+
+- `web_search` *(DuckDuckGo)*
+- `weather_info` *(live)*
+- `http_request` *(any REST API)*
+- `url_shorten`
+- `ip_geolocate`
+- `crypto_price`
+- `currency_convert`
+- `browser_action` *(Puppeteer)*
+- `send_email` *(SMTP)*
+
+</td></tr>
+<tr><th>🇮🇳 India & Productivity</th><th>🔐 Utilities & Security</th></tr>
+<tr><td valign="top">
+
+- `upi_generate` *(UPI deep link)*
+- `qr_generate` *(QR for UPI/links)*
+- `gst_reminder`
+- `translate_text` *(Hindi & more)*
+- `calculate` · `summarize_text`
+- `note_take` · `reminder_set`
+- `calendar_schedule`
+
+</td><td valign="top">
+
+- `password_generate` *(crypto-secure)*
+- `hash_text` *(md5/sha1/256/512)*
+- `base64_tool` *(encode/decode)*
+- `timezone_now` *(world clock)*
+- `simulate_task` *(dry-run)*
+- 🔌 *+ unlimited custom plugins*
+
+</td></tr>
+</table>
 
-Talk to SamarthyaBot on your favorite platform:
+---
+
+## 💬 Chat Slash-Commands
+
+Control the agent directly from **any channel** (Web, Telegram, Discord) — instant, no LLM call:
+
+| Command | Action |
+| :--- | :--- |
+| `/help` | List all commands |
+| `/status` | Provider, model, active pack & host OS |
+| `/tools` `/skills` | List skills in your current pack |
+| `/pack [name]` | Show or switch pack (student/business/developer/personal) |
+| `/model` | Show active AI provider + model |
+| `/memory` | Count of stored memories |
+| `/whoami` | Your profile & permissions |
+| `/new` `/clear` `/reset` | Start a fresh conversation |
+| `/version` | SamarthyaBot version |
+
+---
+
+## 🧠 Supported AI Providers
+
+| Provider | Models | Cost | Best For |
+| :--- | :--- | :--- | :--- |
+| **Google Gemini** | gemini-2.5-flash / pro | 🟢 Free tier | Default, great balance |
+| **Ollama** | Llama 3, Mistral, Dolphin | 🟢 Free (local) | 100% offline, zero data leakage |
+| **Groq** | Llama 3.3 70B, Qwen3 32B | 🟢 Free tier | Fastest inference |
+| **Anthropic** | Claude 3.5 Sonnet / Opus | 🟡 Paid | Smartest reasoning |
+| **OpenAI** | GPT-5.2, GPT-5-mini, o3-mini | 🟡 Paid | Coding & agentic tasks |
+| **DeepSeek** | DeepSeek Chat / Coder | 🟢 Budget | Affordable coding |
+| **Qwen** | Qwen Max / Turbo | 🟢 Budget | Alibaba's best |
+| **OpenRouter** | 100+ models | 🟡 Varies | Access any model |
+| **Mistral** | Mistral Large 3, Devstral 2 | 🟡 Paid | EU privacy, code agents |
+
+---
+
+## 💬 Chat Channels & Integrations
 
 | Channel | Setup | Status |
 | :--- | :--- | :---: |
-| **📱 Telegram** | Easy — just a bot token + `samarthya tunnel` | ✅ Live |
+| **📱 Telegram** | Bot token + `samarthya tunnel` | ✅ Live |
 | **🟣 Discord** | Bot token + intents + invite URL | ✅ Live |
 | **🌐 Web Dashboard** | Built-in at `http://localhost:5000` | ✅ Live |
 | **📱 WhatsApp** | Business API integration | 🔜 Coming |
 | **💼 Slack** | Webhook + App | 📋 Planned |
 
 <details>
-<summary><b>📱 Telegram Setup</b> (Recommended)</summary>
-
-**1. Create a bot**
-* Open Telegram → search `@BotFather`
-* Send `/newbot`, follow prompts
-* Copy the token
-
-**2. Configure** — Add to your `.env`:
-```bash
-TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN
-```
-
-**3. Run**
-```bash
-# Terminal 1
-samarthya gateway
-
-# Terminal 2 (new terminal!)
-samarthya tunnel
-```
+<summary><b>📱 Telegram Setup</b></summary>
 
-The tunnel automatically sets the webhook URL. You're live! 🚀
+1. Open Telegram → `@BotFather` → `/newbot` → copy token
+2. Add to `.env`: `TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN`
+3. Run `samarthya gateway` then `samarthya tunnel` (new terminal). The tunnel auto-sets the webhook. 🚀
 
 </details>
 
 <details>
 <summary><b>🟣 Discord Setup</b></summary>
 
-**1. Create a bot**
-* Go to https://discord.com/developers/applications
-* Create Application → Bot → Copy Token
-
-**2. Enable Intents** — In Bot settings:
-* ✅ MESSAGE CONTENT INTENT
-* ✅ SERVER MEMBERS INTENT (optional)
-
-**3. Configure** — Add to your `.env`:
-```bash
-DISCORD_BOT_TOKEN=YOUR_BOT_TOKEN
-DISCORD_ALLOW_FROM=YOUR_USER_ID
-```
-
-**4. Invite the bot**
-* OAuth2 → URL Generator → Scope: `bot`
-* Permissions: `Send Messages`, `Read Message History`
-* Open the generated URL → add to your server
-
-**5. Run**
-```bash
-samarthya gateway
-```
+1. https://discord.com/developers/applications → Application → Bot → copy token
+2. Enable **MESSAGE CONTENT INTENT**
+3. Add to `.env`:
+   ```bash
+   DISCORD_BOT_TOKEN=YOUR_BOT_TOKEN
+   DISCORD_ALLOW_FROM=YOUR_USER_ID
+   ```
+4. OAuth2 → URL Generator → scope `bot` → invite → `samarthya gateway`
 
 </details>
 
 ---
 
-## 🏆 Comparison with Alternative AI Agents
-
-How does SamarthyaBot compare to other open-source AI agents?
-
-|                        | OpenClaw       | PicoClaw             | **SamarthyaBot** 🇮🇳               |
-| ---------------------- | -------------- | -------------------- | ----------------------------------- |
-| **Language**           | TypeScript     | Go                   | **Node.js + Go + React**            |
-| **Browser Control**    | ❌ None        | ❌ Search APIs only  | **✅ Real Puppeteer DOM**           |
-| **Web Dashboard**      | ✅ Yes         | ❌ CLI only          | **✅ Beautiful React UI**           |
-| **Live Terminal**      | ❌ No          | ❌ Spawn (async)     | **✅ Go Worker Streaming**          |
-| **Indian Workflows**   | ❌ No          | ❌ No                | **✅ GST/UPI/IRCTC/Hindi**          |
-| **Encrypted Memory**   | ❌ Plain text  | ❌ Markdown files    | **✅ AES-256-CBC + MongoDB**        |
-| **Voice Transcription**| ❌ No          | ✅ Groq Whisper      | **✅ Groq Whisper**                 |
-| **Chat Channels**      | 2              | 7                    | **Telegram + Discord + Web**        |
-| **SSH Deploy**         | ❌ No          | ❌ No                | **✅ Password + PEM Key**           |
-| **Plugin System**      | ❌ No          | Skills folder        | **✅ Drop-in JS plugins**           |
-| **Startup RAM**        | >1GB           | <10MB                | ~100MB (Full-stack + DB)            |
-| **Install Complexity** | High           | Single binary        | `npm i -g samarthya-bot` ✨         |
-| **AI Providers**       | 1-2            | 3-4                  | **9 Providers, 20+ Models**         |
-
----
+## 🔒 Security & Privacy
 
-## ⚙️ Configuration
+SamarthyaBot is **defense-in-depth** by default:
 
-All configuration is in `backend/.env`:
+| Layer | What it does |
+| :--- | :--- |
+| 🏠 **Local control plane** | Runs entirely on your machine — zero cloud dependency |
+| 🔐 **AES-256-CBC** | All memories & secrets encrypted at rest |
+| 🛡️ **Workspace sandbox** | File reads/writes confined to the workspace (`RESTRICT_TO_WORKSPACE`) — **enforced in every file tool** |
+| 🚫 **Command blacklist** | Blocks `rm -rf`, `mkfs`, `dd`, fork bombs, `format`, `del /f`, remote-shell downloads — **per-segment**, so `echo x && rm -rf /` is also blocked |
+| 🌐 **SSRF guard** | `http_request` rejects non-`http(s)` schemes; `file://` is blocked |
+| 🔑 **Secret-safe** | Generated passwords are never logged or stored |
+| 🔌 **Offline mode** | Ollama = 100% offline, zero data leakage |
+| 🚨 **Kill switch** | `samarthya stop` — instant shutdown |
 
-```bash
-# ═══════════════ REQUIRED ═══════════════
-GEMINI_API_KEY=your_gemini_api_key
-MEMORY_ENCRYPTION_KEY=your_32_char_secret_key
-
-# ═══════════════ AI PROVIDERS ═══════════════
-ACTIVE_PROVIDER=gemini          # gemini | ollama | anthropic | openai | deepseek | openrouter | qwen | groq | mistral
-ACTIVE_MODEL=gemini-2.5-flash
-
-# Provider API Keys (set the one you use)
-ANTHROPIC_API_KEY=
-DEEPSEEK_API_KEY=
-OPENROUTER_API_KEY=
-OPENAI_API_KEY=
-GROQ_API_KEY=
-MISTRAL_API_KEY=
-
-# Ollama (local, free, offline)
-USE_OLLAMA=false
-
-# ═══════════════ CHANNELS ═══════════════
-TELEGRAM_BOT_TOKEN=your_telegram_token
-DISCORD_BOT_TOKEN=your_discord_token
-
-# ═══════════════ VOICE ═══════════════
-GROQ_API_KEY=your_groq_key      # For Whisper voice transcription
-
-# ═══════════════ SECURITY ═══════════════
-RESTRICT_TO_WORKSPACE=true       # Sandbox all file/exec operations
-HEARTBEAT_INTERVAL=30            # Minutes between periodic tasks
-
-# ═══════════════ DATABASE ═══════════════
-MONGO_URI=mongodb://localhost:27017/samarthya
-PORT=5000
-```
+> 🧪 Hardened in v2.3.0: the workspace sandbox is now wired into `file_read` / `file_write` / `file_list`, and the command guard validates **every** segment of chained commands. See [SECURITY.md](SECURITY.md) to report issues.
 
 ---
 
-## 🛠️ CLI Commands
+## 🏗️ Architecture
 
-| Command | Action |
-| :--- | :--- |
-| `samarthya onboard` | Interactive setup wizard — API keys, permissions, everything |
-| `samarthya gateway` | Start the backend engine + serve the Dashboard |
-| `samarthya tunnel` | Expose to internet & auto-link Telegram webhook |
-| `samarthya model` | Swap LLM provider (gemini, ollama, claude, deepseek...) |
-| `samarthya telegram` | Configure Telegram bot token |
-| `samarthya discord` | Configure Discord bot token |
-| `samarthya config` | View current configuration |
-| `samarthya status` | Show status of the engine |
-| `samarthya stop` | Gracefully stop the gateway |
-| `samarthya restart` | Restart the gateway |
+```
+   Telegram / Discord / WebUI / CLI
+                 │
+                 ▼
+  ┌────────────────────────────────────────────┐
+  │          SamarthyaBot Gateway              │
+  │           (Control Plane :5000)            │
+  ├────────────────────────────────────────────┤
+  │  ┌────────────┐ ┌──────────┐ ┌──────────┐  │
+  │  │ Slash-Cmds │ │ Planner  │ │ LLM Hub  │  │
+  │  │ (instant)  │ │ (ReAct)  │ │ (9 prov) │  │
+  │  └────────────┘ └────┬─────┘ └────┬─────┘  │
+  │                      │            │         │
+  │  ┌───────────────────┴────────────┴──────┐ │
+  │  │  Tools Engine (34 skills + plugins)   │ │
+  │  └───────────────────┬───────────────────┘ │
+  │                      │                      │
+  │  ┌───────────┐ ┌─────┴──────┐ ┌──────────┐ │
+  │  │ platform  │ │ Go Worker  │ │ Sandbox /│ │
+  │  │  helper   │ │  + Node    │ │ Security │ │
+  │  │ (OS-aware)│ │  fallback  │ │  guard   │ │
+  │  └───────────┘ └────────────┘ └──────────┘ │
+  │  ┌───────────┐ ┌────────────┐ ┌──────────┐ │
+  │  │ Memory    │ │ Browser    │ │ Heartbeat│ │
+  │  │ (AES-256) │ │(Puppeteer) │ │  / Cron  │ │
+  │  └───────────┘ └────────────┘ └──────────┘ │
+  └────────────────────────────────────────────┘
+                 │
+                 ▼
+        MongoDB (Local, Encrypted)
+```
 
 ---
 
 ## 🔌 Developing Plugins
 
-Give your AI new superpowers — just drop a `.js` file:
+Give your AI new superpowers — drop a `.js` file in `~/SamarthyaBot_Files/plugins/`:
 
 ```javascript
-// ~/SamarthyaBot_Files/plugins/weather.js
+// weather.js
 module.exports = {
-    name: 'get_weather',
-    description: 'Gets current weather for a city',
-    parameters: {
-        city: { type: 'string', required: true }
-    },
-    execute: async (args) => {
-        const res = await fetch(`https://wttr.in/${args.city}?format=j1`);
-        const data = await res.json();
-        return {
-            success: true,
-            result: `${args.city}: ${data.current_condition[0].temp_C}°C, ${data.current_condition[0].weatherDesc[0].value}`
-        };
-    }
+  name: 'get_weather',
+  description: 'Gets current weather for a city',
+  parameters: { city: { type: 'string', required: true } },
+  execute: async (args) => {
+    const res = await fetch(`https://wttr.in/${args.city}?format=j1`);
+    const data = await res.json();
+    return {
+      success: true,
+      result: `${args.city}: ${data.current_condition[0].temp_C}°C`
+    };
+  }
 };
 ```
 
@@ -338,151 +343,133 @@ Restart the gateway — the agent can now check weather autonomously! 🌦️
 
 ---
 
-## 💓 Heartbeat (Periodic Autonomous Tasks)
-
-Create `~/SamarthyaBot_Files/HEARTBEAT.md` to schedule autonomous tasks:
+## 🛠️ CLI Commands
 
-```markdown
-# Periodic Tasks
+| Command | Action |
+| :--- | :--- |
+| `samarthya onboard` | Interactive setup wizard |
+| `samarthya gateway` | Start backend engine + dashboard |
+| `samarthya tunnel` | Expose to internet & link Telegram |
+| `samarthya model` | Swap LLM provider/model |
+| `samarthya telegram` / `discord` | Configure a channel |
+| `samarthya config` | View current configuration |
+| `samarthya status` | Show engine status |
+| `samarthya stop` / `restart` | Stop / restart the gateway |
 
-- Check my email for important messages
-- Search web for latest AI news and summarize
-- Remind me about today's calendar events
-```
+---
 
-SamarthyaBot reads this file every 30 minutes (configurable) and executes each task using available tools. Results are sent via your active channel (Telegram/Discord/Dashboard).
+## 🏆 Comparison
+
+|                        | OpenClaw       | PicoClaw          | **SamarthyaBot** 🇮🇳        |
+| ---------------------- | -------------- | ----------------- | --------------------------- |
+| **Cross-Platform**     | ✅             | ✅                | **✅ OS auto-adapts**       |
+| **Browser Control**    | ❌ / search    | ❌ search only    | **✅ Real Puppeteer DOM**   |
+| **Web Dashboard**      | ✅             | ❌ CLI only       | **✅ React glassmorphism**  |
+| **Live Terminal**      | ❌             | ❌ async spawn    | **✅ Go + Node fallback**   |
+| **Slash Commands**     | ✅             | partial           | **✅ Every channel**        |
+| **Indian Workflows**   | ❌             | ❌                | **✅ GST/UPI/QR/IRCTC**     |
+| **Encrypted Memory**   | ❌ plaintext   | ❌ markdown       | **✅ AES-256-CBC + Mongo**  |
+| **Built-in Skills**    | 100+ external  | skills folder     | **34 built-in + plugins**   |
+| **SSH Deploy**         | ❌             | ❌                | **✅ Password + PEM**       |
+| **Install**            | moderate       | single binary     | **`npm i -g samarthya-bot`**|
+| **AI Providers**       | many           | 3-4               | **9 providers, 20+ models** |
 
 ---
 
-## 🔒 Security & Privacy
+## 📊 Real-World Use Cases
 
-| Feature | Description |
-| :--- | :--- |
-| **🏠 Local Control Plane** | Gateway runs on YOUR machine — zero cloud dependency |
-| **🔐 AES-256-CBC Encryption** | All memories and API keys encrypted at rest |
-| **🛡️ Command Blacklists** | `rm -rf`, `mkfs`, `format`, `dd if=` — all blocked |
-| **📁 Workspace Sandbox** | File/exec operations restricted to workspace folder |
-| **🔌 Ollama Offline Mode** | 100% offline AI — zero data leakage |
-| **🚨 Emergency Kill Switch** | `samarthya stop` — instant shutdown from CLI or Dashboard |
+- **🧑‍💻 Developers:** *"Create an Express REST API, push to GitHub, deploy to my VPS."*
+- **📊 Business:** *"Calculate 18% GST on ₹50,000, make a UPI QR, email the invoice."*
+- **🎓 Students:** *"Summarize the top 5 transformer papers and save notes."*
+- **🏢 DevOps:** *"SSH into my server, check disk space, restart nginx if down."*
+- **🇮🇳 Professionals:** *"Generate a UPI link for ₹2,500, translate this to Hindi."*
 
 ---
 
-## 🏗️ Architecture
+## 🗺️ Roadmap
 
-```
-  Telegram / Discord / WebUI / CLI
-                │
-                ▼
-  ┌──────────────────────────────────────────┐
-  │         SamarthyaBot Gateway             │
-  │        (The Control Plane)               │
-  │        http://localhost:5000             │
-  ├──────────────────────────────────────────┤
-  │                                          │
-  │  ┌─────────┐  ┌──────────┐  ┌────────┐  │
-  │  │ Planner │  │ LLM Hub  │  │ Tools  │  │
-  │  │ (ReAct) │  │ (Multi)  │  │ Engine │  │
-  │  └────┬────┘  └────┬─────┘  └───┬────┘  │
-  │       │            │             │       │
-  │  ┌────┴────────────┴─────────────┴────┐  │
-  │  │        Go Micro-Worker             │  │
-  │  │   (Live Terminal Streaming)        │  │
-  │  └───────────────────────────────────┘  │
-  │                                          │
-  │  ┌─────────┐  ┌──────────┐  ┌────────┐  │
-  │  │ Memory  │  │ Browser  │  │ Cron / │  │
-  │  │ (AES)   │  │(Puppeteer│  │Hearbeat│  │
-  │  └─────────┘  └──────────┘  └────────┘  │
-  │                                          │
-  └──────────────────────────────────────────┘
-                │
-                ▼
-        MongoDB (Local, Encrypted)
-```
+- [x] **True cross-platform** (Windows / macOS / Linux auto-detect)
+- [x] **Go micro-worker + Node fallback**
+- [x] **34 built-in skills** (QR, currency, crypto, translate, hash…)
+- [x] **Slash-commands** on every channel
+- [x] **Hardened sandbox + command guard**
+- [x] Full RPA · SSH deploy · Puppeteer browser
+- [x] Telegram + Discord + Voice (Whisper)
+- [ ] WhatsApp Business API
+- [ ] Slack integration
+- [ ] Docker Compose deployment
+- [ ] RAG over local documents
+- [ ] Multi-user role-based access
 
 ---
 
-## 📊 Use Cases & Real-World Examples
+## 🤝 Contributing
 
-SamarthyaBot is designed for real-world automation:
+PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).
 
-- **🧑‍💻 Developers**: "Samarthya, create a REST API with Express, push to GitHub, and deploy to my VPS"
-- **📊 Business Owners**: "Calculate GST for ₹50,000 at 18% and send invoice to client@email.com"
-- **🎓 Students**: "Research the latest papers on transformer architecture and summarize the top 5"
-- **🏢 DevOps Engineers**: "SSH into my server, check disk space, restart nginx if it's down"
-- **📱 Content Creators**: "Scrape trending topics from Twitter, summarize them, and post to my Discord"
-- **🇮🇳 Indian Professionals**: "Generate UPI payment link for ₹2,500, book Rajdhani ticket status, translate to Hindi"
+```bash
+git clone https://github.com/mebishnusahu0595/SamarthyaBot.git
+cd SamarthyaBot && npm install
+```
 
----
+<a href="https://github.com/mebishnusahu0595/SamarthyaBot/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=mebishnusahu0595/SamarthyaBot" alt="Contributors"/>
+</a>
 
-## ❓ Frequently Asked Questions (FAQ)
+### ⭐ Star History
 
-### What is SamarthyaBot?
-SamarthyaBot is a **privacy-first, self-hosted AI operating system** that runs locally on your machine. It combines chatbot capabilities with full RPA (Robotic Process Automation) — meaning it can write code, deploy servers, control browsers, send emails, and automate Indian workflows like GST and UPI, all from a single Telegram message or web dashboard.
+<a href="https://star-history.com/#mebishnusahu0595/SamarthyaBot&Date">
+  <img src="https://api.star-history.com/svg?repos=mebishnusahu0595/SamarthyaBot&type=Date" width="600" alt="Star History Chart">
+</a>
 
-### How do I install SamarthyaBot?
-Install SamarthyaBot with a single NPM command: `npm install -g samarthya-bot`. Then run `samarthya onboard` for guided setup. Requires Node.js 20+ and MongoDB.
+---
 
-### Is SamarthyaBot free?
-Yes, SamarthyaBot is **100% free and open-source** under the MIT license. It supports free AI providers like Google Gemini and Ollama (fully offline).
+## ❓ Frequently Asked Questions
 
-### Does SamarthyaBot work offline?
-Yes! Using **Ollama** as the AI provider, SamarthyaBot runs **100% offline** with zero data leakage. No internet connection required after initial setup.
+<details>
+<summary><b>Does it really work on Windows, macOS and Linux?</b></summary>
 
-### What AI models does SamarthyaBot support?
-SamarthyaBot supports **9 AI providers** with 20+ models: Google Gemini, Ollama (local), Anthropic Claude, OpenAI GPT, DeepSeek, Qwen, OpenRouter (100+ models), Groq, and Mistral.
+Yes. SamarthyaBot detects your OS at runtime and adapts every shell command, file path, browser launch and "open" action. The LLM is told your exact OS so it only emits valid commands, and the live-terminal worker falls back to native Node if the Go binary isn't built for your platform.
+</details>
 
-### Does SamarthyaBot support Hindi?
-Yes! SamarthyaBot has first-class support for **Hindi, Hinglish, and English**. It's built specifically for Indian developers with Indian workflow support (GST, UPI, IRCTC).
+<details>
+<summary><b>Is SamarthyaBot free?</b></summary>
 
-### Is my data safe with SamarthyaBot?
-Absolutely. SamarthyaBot runs **entirely on your local machine**. All memories are encrypted with **AES-256-CBC**. Dangerous commands are blocked by regex blacklists. Your data never leaves your device.
+Yes — 100% free and open-source under MIT. It supports free providers like Gemini and Ollama (fully offline).
+</details>
 
-### How is SamarthyaBot different from ChatGPT?
-Unlike ChatGPT, SamarthyaBot: (1) runs locally on your machine, (2) can execute real actions (deploy code, send emails, control browsers), (3) supports Indian workflows, (4) works offline via Ollama, and (5) your data never leaves your device.
+<details>
+<summary><b>Does it work offline?</b></summary>
 
-### Can SamarthyaBot deploy code to my server?
-Yes! SamarthyaBot can SSH into remote servers using password or PEM key authentication, run commands, deploy code, and manage infrastructure — all from a simple chat message.
+Yes. With **Ollama**, SamarthyaBot runs 100% offline with zero data leakage.
+</details>
 
-### How do I create a plugin for SamarthyaBot?
-Drop a `.js` file in `~/SamarthyaBot_Files/plugins/` with a name, description, parameters, and execute function. SamarthyaBot auto-discovers and loads it. See the [Plugin Documentation](#-developing-plugins) above.
+<details>
+<summary><b>Is my data safe?</b></summary>
 
----
+Everything runs on your machine. Memories are AES-256-CBC encrypted, file tools are sandboxed to your workspace, and dangerous commands are blocked per-segment.
+</details>
 
-## 🗺️ Roadmap
+<details>
+<summary><b>How do I add a new skill?</b></summary>
 
-- [x] Full RPA Engine (Code → Commit → Deploy)
-- [x] Go Micro-Worker (Live Terminal Streaming)
-- [x] Puppeteer Browser DOM Controller
-- [x] Telegram Integration + Auto Tunnel
-- [x] Multi-Provider LLM (Gemini, Claude, GPT, DeepSeek, Qwen, OpenRouter, Ollama, Groq, Mistral)
-- [x] Discord Bot Integration
-- [x] Groq/Whisper Voice Transcription
-- [x] Workspace Security Sandbox
-- [x] Heartbeat Periodic Tasks
-- [x] Sub-Agent Spawn (Background Workers)
-- [x] Premium CLI with ASCII Banner and Setup Wizard
-- [ ] WhatsApp Business API
-- [ ] Slack Integration
-- [ ] Docker Compose deployment
-- [ ] Mobile companion app
-- [ ] RAG (Retrieval-Augmented Generation) with local documents
-- [ ] Multi-user role-based access
+Drop a `.js` file in `~/SamarthyaBot_Files/plugins/` with `name`, `description`, `parameters`, and an `execute` function. See [Developing Plugins](#-developing-plugins).
+</details>
 
 ---
 
 ## 📄 License
 
-**MIT License** — Free to use, modify, and distribute.
+**MIT License** — free to use, modify, and distribute.
 
 Built with ❤️ in India 🇮🇳 by **[Bishnu Prasad Sahu](https://github.com/mebishnusahu0595)**
 
----
-
 <div align="center">
 
-  **[📦 NPM](https://www.npmjs.com/package/samarthya-bot)** · **[🐙 GitHub](https://github.com/mebishnusahu0595/SamarthyaBot)** · **[🐛 Report Bug](https://github.com/mebishnusahu0595/SamarthyaBot/issues)** · **[✨ Request Feature](https://github.com/mebishnusahu0595/SamarthyaBot/issues)**
+**[📦 NPM](https://www.npmjs.com/package/samarthya-bot)** · **[🐙 GitHub](https://github.com/mebishnusahu0595/SamarthyaBot)** · **[🐛 Report Bug](https://github.com/mebishnusahu0595/SamarthyaBot/issues)** · **[✨ Request Feature](https://github.com/mebishnusahu0595/SamarthyaBot/issues)**
+
+<sub>If SamarthyaBot helps you, please give it a ⭐ — it really helps!</sub>
 
-  <sub>If SamarthyaBot helps you, consider giving it a ⭐ on GitHub!</sub>
+<img src="https://capsule-render.vercel.app/api?type=waving&color=0:138808,50:FFFFFF,100:FF9933&height=100&section=footer" width="100%" alt=""/>
 
 </div>