@pheem49/mint 1.4.1 → 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,48 +5,128 @@
 </p>
 
 <p align="center">
-  <strong>Desktop assistant + CLI coding agent built with Electron, Node.js, and modern LLM providers.</strong>
+  <strong>Unified AI Desktop Assistant, Agentic CLI, and local-first automation workspace.</strong>
 </p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/License-AGPL--3.0-blue?style=for-the-badge" alt="License">
   <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-Agentic-orange?style=for-the-badge" alt="CLI Agentic">
+  <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 AI assistant that runs in two main surfaces:
+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.
 
-- A desktop Electron app for chat, screen-aware help, and system actions
-- A terminal-first CLI with a workspace-aware coding agent
-
-The project is built around practical local workflows: inspect code, edit files, run safe commands with approval, use project context, and fall back across multiple AI providers when needed.
-
-## What Mint Can Do
-
-- Chat in Desktop or CLI mode
-- Route coding requests into Code Mode automatically from the CLI chat UI
-- Inspect a workspace before editing
-- Search code, read file ranges, and patch files
-- Run non-destructive shell commands with user approval
-- Keep lightweight per-workspace session memory
-- Perform a second-pass reviewer step in Code Mode
-- Execute structured actions such as opening apps, URLs, folders, and system tasks
-- Support multiple providers: Gemini, Anthropic, OpenAI, local OpenAI-compatible endpoints, Ollama, and Hugging Face
+```bash
+mint mcp add <name> <command> --args <args...> --env <KEY=VALUE>
+mint mcp list
+mint mcp remove <name>
+mint mcp clear
+```
 
-## Current Agent Capabilities
+Example:
 
-Mint CLI is an agentic coding workflow, not just a chat wrapper.
+```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
+```
 
-In Code Mode it can:
+## Safety System
 
-- Decide on the next step from the current observation
-- Use tools in a loop: `list_files`, `read_file`, `search_code`, `run_shell`, `apply_patch`, `write_file`
-- Observe tool output and continue iterating
-- Stop with a summary and verification result
-- Ask for approval before shell commands and file changes
+Mint includes a central safety layer in `src/System/safety_manager.js`.
 
-That makes Mint a practical CLI coding agent, while still keeping the user in control of risky actions.
+- **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
 
@@ -61,13 +141,13 @@ That makes Mint a practical CLI coding agent, while still keeping the user in co
 
 ## Installation
 
-### Global install
+### Global Install
 
 ```bash
 npm install -g @pheem49/mint@latest
 ```
 
-### Local development
+### Local Development
 
 ```bash
 git clone https://github.com/Pheem49/Mint.git
@@ -77,168 +157,160 @@ npm install
 
 ## Quick Start
 
-### Run the desktop app
-
-```bash
-npm start
-```
-
-### Run the CLI
-
-```bash
-mint
-```
-
-### First-time setup
-
 ```bash
 mint onboard
+mint
+npm start
 ```
 
 ## CLI Commands
 
-- `mint` or `mint chat`
-Start the interactive chat UI.
-
-- `mint code "<task>"`
-Run the workspace-aware coding agent in the current directory.
+- `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 task "<task>"`
-Queue a background task for the headless agent.
+## CLI Updates
 
-- `mint agent`
-Run the background headless agent.
+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 list`
-Show major features and commands.
-
-- `mint onboard`
-Configure API keys and local settings.
-
-## CLI Examples
-
-### Interactive chat
+Use manual update commands when you want direct control:
 
 ```bash
-mint
+mint update
+mint update --check
+mint update --dry-run
 ```
 
-Then ask naturally:
+You can skip the startup auto-check for one command:
 
-```text
-สำรวจโปรเจคนี้ให้หน่อย
-แก้บัคใน CLI ตัวนี้และรันเทสต์
-open github
+```bash
+MINT_SKIP_AUTO_UPDATE=1 mint
 ```
 
-### One-shot coding task
+To disable automatic update checks, set `enableAutoUpdate` to `false` in your Mint config file.
 
-```bash
-mint code "fix the failing tests and verify the result"
-```
+## Integration Setup
 
-### Background task
+Most integrations can be configured from:
 
 ```bash
-mint task "inspect the repo and summarize the top 3 risks"
+mint onboard
 ```
 
-## Code Mode Workflow
+### Gmail
 
-Mint Code Mode is designed around an inspect -> act -> verify loop.
+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.
 
-What it does well right now:
+After onboarding, run one of:
 
-- Understand the current workspace path
-- Read git status and diff summary
-- Suggest verification commands from `package.json`
-- Apply focused patches instead of blind rewrites
-- Keep a workspace session summary for future tasks
+```bash
+mint gmail auth
+mint gmail auth --no-open
+```
 
-What it deliberately does not do:
+`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.
 
-- Run destructive commands like `rm -rf` or `git reset --hard`
-- Edit files outside the current workspace
-- Execute shell edits without approval
+### Google Calendar
 
-## Desktop Features
+Google Calendar uses OAuth credentials and a refresh token. Onboarding stores:
 
-- Chat window with custom UI
-- Settings window for provider and behavior configuration
-- System tray support
-- Proactive suggestion loop
-- Silent screen capture for analysis
-- Screen translation support
-- Floating widget / overlay UI elements
+- `googleCalendarClientId`
+- `googleCalendarClientSecret`
+- `googleCalendarRefreshToken`
+- `googleCalendarId`, usually `primary`
 
-## AI Providers
+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.
 
-Mint supports multiple providers and local backends.
+### Notion
 
-- `gemini`
-- `anthropic`
-- `openai`
-- `local_openai`
-- `ollama`
-- `huggingface`
+Notion uses an internal integration secret. After creating an integration in Notion, share the target page or database with that integration, then configure:
 
-For CLI Code Mode, Mint currently behaves best with:
+- `notionApiKey`
+- `notionDatabaseId`, optional default database
+- `notionPageId`, optional default page
+- `notionTitleProperty`, default `Name`
 
-- `gemini`
-- `anthropic`
-- `openai`
-- `local_openai`
+The plugin can create pages, query database pages, and append text blocks.
 
-## Project Structure
+## Interactive Slash Commands
 
-```text
-Mint/
-├── src/
-│   ├── AI_Brain/          # Provider integration, prompts, memory, orchestration
-│   ├── Automation_Layer/  # App/file/browser actions
-│   ├── CLI/               # Chat router, code agent, TUI support, onboarding
-│   ├── Plugins/           # Docker, Spotify, calendar, system monitor, MCP
-│   ├── System/            # Config, notifications, daemon, automation, task queue
-│   └── UI/                # Electron renderer files
-├── tests/                 # Jest tests
-├── mint-cli.js            # Main CLI entry
-├── mint-cli-logic.js      # CLI action executor
-├── main.js                # Electron main process
-└── package.json
-```
+Inside `mint`:
 
-## Development
+- `/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.
 
-### Run tests
+## Development
 
 ```bash
+npm test
 npm test -- --runInBand
+npm audit --audit-level=high
+npm start
+npm run build:linux
 ```
 
-### Watch tests
+## Project Structure
 
-```bash
-npm run test:watch
+```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/                   # 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
 ```
 
-### Build Linux packages
+## Runtime Notes
 
-```bash
-npm run build:linux
-```
+- 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.
 
-See [BUILD_AND_RELEASE.md](/home/pheem49/vscode/Project/Mint/BUILD_AND_RELEASE.md) for Linux packaging and release notes workflow.
+## Security & Privacy
 
-## Security Notes
+- **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.
 
-- API keys are stored in local config, not in source files
-- Code Mode asks for approval before shell commands and file edits
-- Workspace path resolution blocks writes outside the active workspace
-- Several shell-based execution paths have been hardened to use argument-based process execution
+## License
 
-This is still an actively evolving project. Review permissions and local configuration before using Mint against sensitive files or production systems.
+Mint is licensed under the **GNU Affero General Public License v3.0**.
+See the [LICENSE](LICENSE) file for details.
 
-## License
+---
 
-Mint is licensed under the GNU Affero General Public License v3.0.
-See [LICENSE](/home/pheem49/vscode/Project/Mint/LICENSE).
+<p align="center">Made with love by <a href="https://github.com/Pheem49">Pheem49</a></p>