@pheem49/mint 1.4.2 → 1.5.0

package/GUIDE_TH.md

@@ -0,0 +1,113 @@
+# 🌿 Mint: คู่มือการใช้งานฉบับสมบูรณ์ (Official Guide)
+
+ยินดีต้อนรับสู่ **Mint** ผู้ช่วย AI อัจฉริยะที่รวมพลังของ Desktop UI และ CLI Agent เข้าด้วยกัน เพื่อช่วยให้การทำงานและเขียนโค้ดของคุณง่ายขึ้น รวดเร็วขึ้น และสนุกยิ่งขึ้น!
+
+---
+
+## 📥 1. การติดตั้ง (Installation)
+
+คุณสามารถติดตั้ง Mint ได้สองวิธีหลักๆ ดังนี้:
+
+### วิธีที่ 1: ติดตั้งผ่าน NPM (แนะนำสำหรับผู้ใช้ทั่วไป)
+หากคุณต้องการใช้งานคำสั่ง `mint` ได้จากทุกที่ในเครื่อง:
+```bash
+npm install -g @pheem49/mint@latest
+```
+
+### วิธีที่ 2: ติดตั้งจาก Source Code (สำหรับนักพัฒนา)
+หากคุณต้องการแก้ไขโค้ดหรือลองฟีเจอร์ใหม่ๆ:
+1. Clone repository: `git clone https://github.com/Pheem49/Mint.git`
+2. เข้าไปที่โฟลเดอร์: `cd Mint`
+3. ติดตั้ง dependencies: `npm install`
+4. เรียกใช้งานผ่าน: `node mint-cli.js` หรือ `npm start` (สำหรับ GUI)
+
+---
+
+## ⚙️ 2. การตั้งค่าเริ่มต้น (Initial Setup)
+
+หลังจากติดตั้งเสร็จ สิ่งแรกที่ควรทำคือการตั้งค่า API Key และบริการต่างๆ ผ่านระบบ Onboarding:
+
+```bash
+mint onboard
+```
+
+### ขั้นตอนการ Onboard:
+1. **Gemini API Key**: กรอกคีย์จาก [Google AI Studio](https://aistudio.google.com/) (จำเป็นสำหรับการทำงานหลัก)
+2. **Select Model**: เลือกโมเดลที่ต้องการ (แนะนำ `gemini-1.5-flash` เพื่อความเร็ว หรือ `gemini-1.5-pro` เพื่อความฉลาด)
+3. **QuickStart Selection**: เลือกบริการที่ต้องการเปิดใช้งาน (ใช้ปุ่ม **Space** เพื่อเลือก/ยกเลิก และ **Enter** เพื่อยืนยัน)
+   - **Chat Bridges**: Telegram, Discord, WhatsApp, LINE, Slack
+   - **AI Providers**: Anthropic (Claude), OpenAI (GPT-4), Hugging Face, Local AI (Ollama/LM Studio)
+   - **Search APIs**: Google Search, Brave Search
+4. **กรอกรายละเอียด**: ระบบจะถามคีย์หรือ URL ตามบริการที่คุณเลือกไว้
+
+---
+
+## ⌨️ 3. การใช้งานผ่าน CLI (Terminal)
+
+Mint CLI เป็นมากกว่าแค่แชท แต่มันคือ **Agent** ที่สามารถคิดและทำงานแทนคุณได้
+
+### การเริ่มแชทปกติ
+```bash
+mint
+```
+*หรือใช้คำสั่งเต็ม:* `mint chat`
+
+### คำสั่งพิเศษ (Slash Commands)
+ขณะอยู่ในหน้าแชท คุณสามารถพิมพ์ `/` เพื่อเรียกใช้งานเมนูคำสั่งด่วน:
+- `/help`: ดูรายการคำสั่งทั้งหมด
+- `/code <งาน>`: บังคับเข้าโหมดเขียนโค้ด (Workspace Aware)
+- `/cd <เส้นทาง>`: เปลี่ยนโฟลเดอร์ทำงานปัจจุบัน
+- `/models`: ดูหรือสลับโมเดล AI
+- `/config`: ดูการตั้งค่าปัจจุบัน
+- `/clear` / `/reset`: ล้างประวัติการสนทนา
+- `/agent <ชื่อ>`: สลับบุคลิกของ AI (เช่น `code`, `reviewer`)
+- `/stats`: ดูสถานะทรัพยากรเครื่อง
+- `/exit`: ออกจากโปรแกรม
+
+### การเขียนโค้ด (Agentic Coding)
+คุณสามารถสั่งงานที่ซับซ้อนในโปรเจกต์ของคุณได้ เช่น:
+```bash
+mint code "ช่วยเขียน Unit Test สำหรับไฟล์ src/System/config_manager.js ให้หน่อย"
+```
+มิ้นท์จะทำการ:
+1. **คิด (Thinking)**: วางแผนการทำงาน
+2. **ใช้เครื่องมือ (Tools)**: อ่านไฟล์, ค้นหาโค้ด, เขียนไฟล์, รันคำสั่ง Shell
+3. **ขออนุมัติ (Approval)**: ถามคุณก่อนรันคำสั่งที่อาจเป็นอันตรายหรือแก้ไขไฟล์
+
+---
+
+## 🔌 4. การจัดการ MCP (Model Context Protocol)
+
+MCP คือระบบที่ช่วยให้มิ้นท์สามารถ "ขยายร่าง" ไปใช้เครื่องมือภายนอกได้
+
+### เพิ่ม Server ใหม่
+```bash
+# รูปแบบ: mint mcp add <ชื่อ> <คำสั่ง> --args <อาร์กิวเมนต์> --env <ตัวแปรสภาพแวดล้อม>
+
+# ตัวอย่าง: เพิ่มความสามารถในการค้นหา Google Search
+mint mcp add google-search npx --args -y @modelcontextprotocol/server-google-search --env GOOGLE_API_KEY=คีย์ของคุณ GOOGLE_SEARCH_ENGINE_ID=ไอดีของคุณ
+```
+
+### คำสั่งอื่นๆ ของ MCP:
+- `mint mcp list`: ดูรายชื่อ Server ที่เชื่อมต่ออยู่
+- `mint mcp remove <ชื่อ>`: ลบ Server ออก
+- `mint mcp clear`: ล้าง Server ทั้งหมด
+
+---
+
+## 🖥️ 5. การใช้งาน Desktop UI (GUI)
+
+หากคุณติดตั้งแบบ Source Code หรือเปิดแอป Mint ขึ้นมา:
+- **Floating Widget**: หน้าต่างจิ๋วที่ลอยอยู่บนหน้าจอ กดเรียกแชทได้ทันที
+- **Screen Vision**: คลิกที่ไอคอนกล้องเพื่อให้มิ้นท์ "มองเห็น" หน้าจอของคุณ และถามคำถามเกี่ยวกับสิ่งที่คุณเห็นได้
+- **Proactive Engine**: มิ้นท์จะคอยสังเกตการณ์และแจ้งเตือนสิ่งที่เป็นประโยชน์ (ตั้งค่าเปิด/ปิดได้ใน Settings)
+- **Settings**: ปรับแต่งสีธีม, ความเร็วเสียงอ่าน (TTS), และความถี่ในการตรวจจับหน้าจอ
+
+---
+
+## 🛡️ ความปลอดภัยและทางเลือก
+- **Approval System**: มิ้นท์จะไม่รันคำสั่ง Shell หรือเขียนไฟล์โดยที่คุณไม่กด `y` ยืนยัน
+- **Local First**: หากคุณต้องการความเป็นส่วนตัวสูงสุด สามารถเลือกใช้ **Ollama** หรือ **LM Studio** ร่วมกับ Mint ได้ 100%
+
+---
+*จัดทำโดย มิ้นท์ (ผู้ช่วยส่วนตัวของคุณ) และ Pheem49* 💚✨

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <strong>The Unified AI Desktop Assistant & Agentic Coding CLI. Built for speed, power, and local control.</strong>
+  <strong>Unified AI Desktop Assistant, Agentic CLI, and local-first automation workspace.</strong>
 </p>
 
 <p align="center">
@@ -13,40 +13,122 @@
   <img src="https://img.shields.io/badge/Node.js-LTS-green?style=for-the-badge&logo=node.js" alt="Node.js">
   <img src="https://img.shields.io/badge/Electron-40.x-47848F?style=for-the-badge&logo=electron" alt="Electron">
   <img src="https://img.shields.io/badge/CLI-Unified_Agent-orange?style=for-the-badge" alt="CLI Agentic">
+  <a href="https://pheem49.github.io/Mint/guide.html"><img src="https://img.shields.io/badge/Documentation-View_Guide-00ffa3?style=for-the-badge" alt="Documentation"></a>
 </p>
 
-Mint is an advanced AI assistant designed to live in your workspace. It features a rich Electron desktop interface for day-to-day assistance and a powerful, unified CLI agent that seamlessly merges conversational chat with complex coding tasks.
+Mint is an AI assistant built to live in your desktop and terminal. It combines a transparent Electron desktop assistant, a unified agentic CLI, project-aware coding tools, local memory, automation, multi-provider AI routing, MCP extensions, and safety controls.
+
+## What's New
+
+- **Unified CLI Agent:** `mint` now routes every normal message through the same agent loop. It can think, answer conversationally, inspect projects, edit files, run tools, and finish directly for simple chat.
+- **Provider Fallback:** The agent can fall back across supported providers, for example from local OpenAI-compatible backends to Gemini.
+- **Provider Visibility:** Desktop and CLI responses show the provider/model that actually answered, including fallback results.
+- **Google Workspace + Notion Integrations:** Gmail, Google Calendar, and Notion plugins can be configured from onboarding.
+- **Safety Manager:** Central safety policy for shell commands and actions, including deterministic command blocking, permission tiers, path guards, and action logs.
+- **Refactored Main Process:** Electron startup is split into focused modules for windows, IPC, proactive loop, screen capture, and action execution.
+- **CI & Audit Baseline:** GitHub Actions runs install, tests, and security audit. Current local test baseline is `120` passing tests and `0` high vulnerabilities.
+- **Dependency Hardening:** Removed vulnerable `google-tts-api` and `xlsx`; replaced with internal Google TTS URL generation and `read-excel-file`.
+
+## Key Features
+
+### Unified CLI Agent
+
+Mint CLI is not just a chat wrapper. It is a workspace-aware agent loop.
+
+- **Think Before Acting:** Every request goes through an agent decision step.
+- **Conversational + Coding in One Flow:** Casual messages can finish directly; coding tasks can inspect, plan, edit, and verify.
+- **Workspace Context:** Reads current path, git status, diff summary, package scripts, and previous workspace session memory.
+- **Tool Use:** Supports web search, file listing, file reading, code search, path finding, shell commands, patch edits, file writes, opening folders, and asking the user.
+- **Approval Flow:** Shell commands, patches, and full-file writes require user approval.
+- **Provider Support:** Gemini, OpenAI, Anthropic, and local OpenAI-compatible endpoints for agent tasks.
+- **Agent Collaboration Option:** Optional reviewer pass can be enabled for longer tasks.
+
+### Desktop Assistant
+
+- **Electron Desktop UI:** Transparent desktop assistant window with tray support.
+- **Floating Widget:** Always-on-top quick access widget.
+- **Spotlight Launcher:** `Alt+Space` quick prompt window.
+- **Screen Vision:** Capture the screen and send selected regions to the AI.
+- **Live Translation:** Continuously translate a selected screen area.
+- **Proactive Suggestions:** Periodic screen/context analysis with behavior memory.
+- **System Notifications:** Low battery, connection changes, and proactive notices.
+- **Settings UI:** Configure provider, model, theme, keys, bridge options, MCP, and assistant behavior.
+
+### Automation
+
+- **Apps and Websites:** Open local apps, URLs, search queries, files, and folders.
+- **Browser Automation:** Use Puppeteer-driven browser workflows.
+- **File Operations:** Create folders, find paths, open files/folders, and move files to trash.
+- **System Automation:** Volume, mute, brightness, suspend, restart, shutdown, and window minimization helpers.
+- **Granular Automation:** Mouse move, mouse click, typing, and key tap actions.
+- **Custom Workflows:** Process-monitoring rules loaded from local config.
+- **Headless Agent:** Queue background tasks with `mint task`.
+
+### Knowledge and Memory
+
+- **Chat History:** Persistent local chat transcript.
+- **Behavior Memory:** Stores recurring user context for proactive suggestions.
+- **Long-Term Memory Store:** SQLite-backed user context, session memories, usage patterns, and response cache.
+- **Knowledge Base / RAG:** Index and search local `.txt`, `.md`, `.pdf`, `.docx`, and `.xlsx` files.
+- **Workspace Session Memory:** Remembers previous task summary and verification for each workspace.
+
+### Multi-Provider AI
+
+- **Gemini:** Main default provider with model selection.
+- **OpenAI:** GPT-compatible cloud provider.
+- **Anthropic:** Claude-compatible provider.
+- **Local OpenAI Compatible:** LM Studio or other local `/v1/chat/completions` servers.
+- **Ollama / Hugging Face:** Available in general provider configuration where supported.
+- **Fallback Routing:** Agent provider selection can fall back when local providers are offline.
+- **Response Badges:** Chat surfaces show the provider/model that produced the final response, such as `gemini • gemini-3.1-flash-lite-preview`.
+
+### Messaging Bridges and Plugins
+
+- **Discord Bridge**
+- **Telegram Bridge**
+- **Slack Bridge**
+- **LINE Bridge**
+- **WhatsApp Bridge**
+- **Google Search and Brave Search Bridges**
+- **Spotify Plugin**
+- **Docker Plugin**
+- **Obsidian Plugin**
+- **System Monitor and Metrics Plugins**
+- **Google Calendar Plugin:** List events and create calendar events via Google Calendar API, with browser fallback.
+- **Gmail Plugin:** Search/read Gmail and create drafts safely. It does not send email automatically.
+- **Notion Plugin:** Create notes/pages, read databases, and append page blocks through the Notion API.
+- **MCP Manager**
+
+### MCP Extensions
+
+Mint supports the **Model Context Protocol (MCP)** so external tools can be added without hardcoding them into Mint.
 
-## 🌟 What's New in v1.4.1
+```bash
+mint mcp add <name> <command> --args <args...> --env <KEY=VALUE>
+mint mcp list
+mint mcp remove <name>
+mint mcp clear
+```
 
-- **Unified Agent Loop:** No more switching modes. Every interaction in the CLI is now handled by a sophisticated agent that can think, plan, and execute tools autonomously.
-- **Agentic Web Search:** Mint can now search the internet in real-time to answer questions with the latest information using integrated web tools.
-- **Upgraded TUI:** A redesigned terminal interface featuring a Braille spinner, thinking timer, and a cleaner "✓ ActionName" logging style.
-- **Interactive "Ask User":** The agent can now pause and ask you for clarification or preferences during complex multi-step tasks.
-- **Enhanced System Control:** Reliable multi-fallback support for opening files, folders, and applications on Linux (Pop!_OS/Ubuntu), macOS, and Windows.
+Example:
 
-## 🚀 Key Features
+```bash
+mint mcp add google-search npx --args -y @modelcontextprotocol/server-google-search --env GOOGLE_API_KEY=your_key GOOGLE_SEARCH_ENGINE_ID=your_id
+```
 
-### 💻 Unified CLI Agent
-Mint CLI is not just a chat wrapper; it's a full agentic workflow.
-- **Think & Plan:** Every response starts with a reasoning phase where Mint plans its next move.
-- **Autonomous Tools:** `web_search`, `list_files`, `read_file`, `search_code`, `run_shell`, `apply_patch`, `write_file`, `open_folder`, and more.
-- **User-in-the-Loop:** Safety first. Mint asks for your approval before running shell commands or making file edits.
-- **Workspace Aware:** Automatically understands your project structure, git status, and testing framework.
+## Safety System
 
-### 🖥️ Desktop Assistant
-- **Screen Vision:** Capture and analyze your screen for instant help with what you're looking at.
-- **Real-time Translation:** Instantly translate text from your screen into Thai or English.
-- **Proactive Engine:** Mint monitors your system events to provide helpful suggestions before you even ask.
-- **System Tray & Floating Widgets:** Quick access to Mint from anywhere on your desktop.
+Mint includes a central safety layer in `src/System/safety_manager.js`.
 
-### 🛠️ Multi-Provider Support
-Mint supports the latest LLMs and local backends:
-- **Cloud:** Gemini 1.5/2.0 Pro & Flash, Anthropic Claude 3.5, OpenAI GPT-4o.
-- **Local:** Ollama, LM Studio, Hugging Face Inference API.
-- **MCP:** Full support for Model Context Protocol to extend Mint's capabilities with external tools.
+- **Permission Tiers:** `safe`, `approval`, `dangerous`, and `blocked`.
+- **Deterministic Command Blocking:** Blocks known dangerous shell commands regardless of what the AI requests.
+- **Blocked Examples:** `rm -rf`, `git reset --hard`, `git clean -f`, `mkfs`, raw disk writes, `shutdown`, `reboot`, `sudo`, `chmod -R 777`, `curl | sh`, and `wget | bash`.
+- **Dangerous Actions:** `delete_file` and destructive `system_automation` actions require explicit permission.
+- **Path Guard:** Prevents path traversal outside an allowed root.
+- **Action Logs:** Writes JSONL records to `~/.config/mint/action-log.jsonl`.
+- **Test Coverage:** Safety tests verify destructive command blocking, dangerous action classification, path traversal protection, and action executor enforcement.
 
-## 📸 Screenshots
+## Screenshots
 
 <p align="center">
   <img src="assets/Agent_Mint.png" alt="Mint Desktop UI" width="48%">
@@ -57,97 +139,178 @@ Mint supports the latest LLMs and local backends:
   <img src="assets/CLI_Screen.png" alt="Mint CLI" width="100%">
 </p>
 
-## 📦 Installation
+## Installation
 
 ### Global Install
+
 ```bash
 npm install -g @pheem49/mint@latest
 ```
 
 ### Local Development
+
 ```bash
 git clone https://github.com/Pheem49/Mint.git
 cd Mint
 npm install
 ```
 
-## ⚡ Quick Start
+## Quick Start
+
+```bash
+mint onboard
+mint
+npm start
+```
 
-1. **Setup Mint:**
-   ```bash
-   mint onboard
-   ```
-2. **Start Chatting:**
-   ```bash
-   mint
-   ```
-3. **Run the Desktop App:**
-   ```bash
-   npm start
-   ```
+## CLI Commands
 
-## ⌨️ CLI Commands
+- `mint` / `mint chat` - Start the unified interactive agent UI.
+- `mint chat "<message>"` - Start with an initial message.
+- `mint code "<task>"` - Run a specific coding task in the current workspace.
+- `mint gmail auth` - Open Google OAuth and save a Gmail refresh token.
+- `mint gmail auth --no-open` - Print the Gmail OAuth link without opening a browser.
+- `mint task "<task>"` - Queue a background task for the headless agent.
+- `mint agent [task]` - Run the background/headless agent.
+- `mint mcp` - Manage MCP servers.
+- `mint update` - Check npm and install the latest Mint CLI version.
+- `mint update --check` - Check for a newer version without installing it.
+- `mint list` - Display available features and commands.
+- `mint onboard` - Configure Mint for first use.
 
-- `mint` / `mint chat` : Start the unified interactive agent UI.
-- `mint code "<task>"` : Run a specific coding task in the current workspace.
-- `mint task "<task>"` : Queue a background task for the headless agent.
-- `mint mcp` : Manage Model Context Protocol (MCP) servers.
-- `mint list` : Display all available features and commands.
+## CLI Updates
 
-## 🔌 MCP Management (Extensions)
+Mint CLI checks for updates automatically on startup. The auto-check is enabled by default, uses a 24-hour cooldown, and updates from npm with `npm install -g @pheem49/mint@latest` when a newer package version is available.
 
-Mint supports the **Model Context Protocol (MCP)**, allowing you to extend its capabilities via the CLI without manual config editing.
+Use manual update commands when you want direct control:
 
-### Add a New Server
 ```bash
-# Template
-mint mcp add <name> <command> --args <args...> --env <KEY=VALUE>
+mint update
+mint update --check
+mint update --dry-run
+```
 
-# Example: Google Search
-mint mcp add google-search npx --args -y @modelcontextprotocol/server-google-search --env GOOGLE_API_KEY=your_key GOOGLE_SEARCH_ENGINE_ID=your_id
+You can skip the startup auto-check for one command:
 
-# Example: Filesystem Access
-mint mcp add my-files npx --args -y @modelcontextprotocol/server-filesystem /path/to/folder
+```bash
+MINT_SKIP_AUTO_UPDATE=1 mint
 ```
 
-### List Configured Servers
+To disable automatic update checks, set `enableAutoUpdate` to `false` in your Mint config file.
+
+## Integration Setup
+
+Most integrations can be configured from:
+
 ```bash
-mint mcp list
+mint onboard
 ```
 
-### Remove a Server
+### Gmail
+
+Gmail uses Google OAuth, not a plain Gmail address/password. Configure the OAuth Client ID and Client Secret in onboarding, leave the refresh token empty if you do not have one yet, and keep `Gmail User ID` as `me` for the signed-in account.
+
+After onboarding, run one of:
+
 ```bash
-mint mcp remove google-search
+mint gmail auth
+mint gmail auth --no-open
 ```
 
-### Clear All Servers
+`mint gmail auth` opens the browser automatically. `mint gmail auth --no-open` prints the auth link for you to open manually. Both flows save `gmailRefreshToken` locally after Google redirects back to Mint. Recommended scopes are `gmail.readonly` and `gmail.compose`; Mint creates drafts only and does not send email automatically.
+
+### Google Calendar
+
+Google Calendar uses OAuth credentials and a refresh token. Onboarding stores:
+
+- `googleCalendarClientId`
+- `googleCalendarClientSecret`
+- `googleCalendarRefreshToken`
+- `googleCalendarId`, usually `primary`
+
+The plugin can list events and create events through the Calendar API. If OAuth is not configured, it falls back to opening Google Calendar in the browser.
+
+### Notion
+
+Notion uses an internal integration secret. After creating an integration in Notion, share the target page or database with that integration, then configure:
+
+- `notionApiKey`
+- `notionDatabaseId`, optional default database
+- `notionPageId`, optional default page
+- `notionTitleProperty`, default `Name`
+
+The plugin can create pages, query database pages, and append text blocks.
+
+## Interactive Slash Commands
+
+Inside `mint`:
+
+- `/help` - Show commands.
+- `/code <task>` - Force Code Mode.
+- `/cd <path>` - Change active workspace directory.
+- `/models [name]` - Show or switch model/provider.
+- `/config` - Show current configuration.
+- `/copy` - Copy last response.
+- `/clear` / `/reset` - Clear conversation history.
+- `/agent <type>` - Switch specialized persona.
+- `/workspace` - Manage registered workspaces.
+- `/stats` - Show system statistics.
+- `/review` - Ask reviewer persona to critique the last answer.
+- `/exit` - Exit.
+
+## Development
+
 ```bash
-mint mcp clear
+npm test
+npm test -- --runInBand
+npm audit --audit-level=high
+npm start
+npm run build:linux
 ```
 
-## 🏗️ Project Structure
+## Project Structure
 
 ```text
 Mint/
+├── main.js                         # Electron bootstrap and wiring
+├── mint-cli.js                     # CLI entry point
+├── mint-cli-logic.js               # CLI action executor bridge
 ├── src/
-│   ├── AI_Brain/          # Gemini API, Unified Agent Client, Memory Store
-│   ├── Automation_Layer/  # File Ops, Browser Automation, System Control
-│   ├── CLI/               # TUI logic, Chat Router, Code Agent
-│   ├── Plugins/           # MCP Manager, System Monitor, Third-party integrations
-│   ├── System/            # Config, Notifications, Daemons
-│   └── UI/                # Electron Renderer, Settings, Widgets
-├── mint-cli.js            # Main CLI entry point
+│   ├── AI_Brain/                   # Providers, memory, RAG, autonomous/headless agents
+│   ├── Automation_Layer/           # File, app, website, and browser automation
+│   ├── Channels/                   # Messaging and search bridges
+│   ├── CLI/                        # Unified CLI UI, router, code agent, workspaces
+│   ├── Command_Parser/             # Structured AI response parser
+│   ├── Plugins/                    # Plugin manager and integrations
+│   ├── System/                     # Config, IPC, safety, windows, screen capture, notifications
+│   └── UI/                         # Electron renderer, settings, widgets, spotlight
+├── tests/                          # Jest tests
+├── docs/                           # Documentation site
 └── package.json
 ```
 
-## 🛡️ Security & Privacy
-- **Local Control:** Mint prioritizes local execution and user privacy.
-- **Approval System:** No destructive command or file change happens without your explicit `y/n` confirmation.
-- **Secure Config:** API keys are stored locally on your machine and never transmitted outside of the chosen AI provider.
+## Runtime Notes
+
+- Mint is currently a **Node.js + CommonJS** project, not TypeScript.
+- API keys are stored locally in Mint config or environment variables.
+- Google OAuth refresh tokens for Gmail and Calendar are stored locally in Mint config.
+- Local OpenAI-compatible providers require a running local server such as LM Studio.
+- Some desktop features depend on Linux tools such as `xdg-open`, `gio`, `xdotool`, `amixer`, `pactl`, `brightnessctl`, or `xbacklight`.
+- Electron GUI behavior should be smoke-tested manually after large UI or main-process changes.
+
+## Security & Privacy
+
+- **Local Control:** Mint prioritizes local execution and local configuration.
+- **User Approval:** Shell commands, patches, and file writes require explicit approval in the CLI agent.
+- **Safety Manager:** Dangerous commands and actions are blocked or gated by deterministic policy.
+- **Action Audit Trail:** Tool actions are logged locally for debugging and accountability.
+- **Secure Config Practice:** Keys stay on the user's machine and are only sent to the selected AI/search provider.
+
+## License
 
-## 📜 License
 Mint is licensed under the **GNU Affero General Public License v3.0**.
-See the [LICENSE](LICENSE) file for more details.
+See the [LICENSE](LICENSE) file for details.
 
 ---
-<p align="center">Made with 💚 by <a href="https://github.com/Pheem49">Pheem49</a></p>
+
+<p align="center">Made with love by <a href="https://github.com/Pheem49">Pheem49</a></p>