appclean 1.8.0 → 2.0.0

package/README.md

@@ -1,548 +1,618 @@
 <div align="center">
-  <img src="./logo.svg" alt="AppClean Logo" width="120" height="120">
+  <img src="https://raw.githubusercontent.com/praveenkay/AppClean/main/assets/logo.svg" alt="AppClean - Intelligent Application Uninstaller" width="150" height="150">
 
-  # AppClean
+  # AppClean 🧹
 
-  > **Intelligently find and safely uninstall applications with all their artifacts**
+  **Intelligently find and safely uninstall applications with all their artifacts**
 
-  [![version](https://img.shields.io/badge/version-1.8.0-blue?style=flat-square)](https://github.com/praveenkay/AppClean/releases)
+  [![version](https://img.shields.io/badge/version-2.0.0-blue?style=flat-square)](https://github.com/praveenkay/AppClean/releases/tag/v2.0.0)
   [![license](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
-  [![platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square)](README.md)
+  [![platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=flat-square)](#platform-support)
   [![npm](https://img.shields.io/npm/dm/appclean?style=flat-square)](https://npmjs.com/package/appclean)
 
-  **A powerful, cross-platform CLI tool for developers and system administrators**
+  **A powerful, cross-platform tool for developers, system administrators, and everyone**
 
 </div>
 
-## ✨ Features
+---
 
-### Core Features
-- **🔍 Smart Detection** — Finds apps installed via npm, yarn, pnpm, Homebrew, apt, yum, dnf, and custom installers
-- **📊 Deep Analysis** — Shows installation method, version, and locates all related artifacts
-- **🛡️ Safe Removal** — Dry-run preview, double confirmation, and optional backups
-- **💾 Backup & Restore** — Create backups before deletion and restore if needed
-- **⚡ Fast & Efficient** — Scans and analyzes systems in seconds
-- **🖥️ Cross-Platform** — macOS (Intel & Apple Silicon), Linux, and Windows
-- **🎨 Beautiful CLI** — Interactive menu-driven interface with colors and animations
+## What is AppClean?
 
-### Advanced Features (v1.1.0+)
-- **🔐 Elevated Permissions** — Automatic sudo/admin detection and prompts
-- **🔧 Service File Detection** — Finds LaunchAgent/LaunchDaemon and systemd services
-- **📋 Operation Recording** — Complete removal history tracking and reporting
-- **✓ Verification** — Post-removal verification to ensure complete uninstall
-- **📄 Professional Reports** — HTML and text reports with legal disclaimers
+AppClean is an intelligent application uninstaller that completely removes apps from your system along with all their hidden files, configurations, caches, and leftover data. It supports apps installed via npm, Homebrew, apt, yum, and custom installers across macOS, Linux, and Windows.
 
-### Latest Features (v1.2.0 - v1.8.0)
-- **🎨 GUI Application** — Modern web-based interface (v1.2.0)
-- **🔍 Duplicate File Finder** — Find and remove duplicate files (v1.3.0)
-- **📦 Orphaned Dependency Detector** — Identify unused npm packages (v1.4.0)
-- **🔌 Plugin System** — Extensible architecture for custom detectors (v1.5.0)
-- **⏰ Scheduled Cleanup** — Automate regular cleanup tasks (v1.6.0)
-- **📈 App Update Checker** — Check for available updates (v1.7.0)
-- **🚀 Performance Optimizer** — Multi-threaded scanning & caching (v1.8.0)
+### Why AppClean?
+- 🎯 **Complete Removal** - Finds and removes all app-related files, not just the executable
+- 🛡️ **Safe & Smart** - Preview what will be deleted before confirming
+- 💾 **Backup Option** - Create backups before removal for peace of mind
+- 🎨 **Beautiful Interface** - Modern GUI makes app management easy for everyone
+- ⚡ **Fast & Efficient** - ~50KB bundle, <100ms API responses
+- 🔌 **Programmable** - Full REST API for automation and integration
 
-## 🚀 Installation
+---
 
-### Quick Install (npm)
+## ✨ What's New in v2.0.0
 
-```bash
-npm install -g appclean
-```
+🎉 **Complete GUI Overhaul** - A brand new modern single-page application (SPA) interface for intelligent app management!
 
-### From Source
+### New Features
+- 🎨 **Beautiful SPA Interface** - Clean, minimal design with dark mode support
+- 📊 **Dashboard** - System statistics, disk usage gauge, recent activity log
+- 🔍 **Smart App Search** - Fuzzy search, filter by installation method, sort by name/size/date
+- 📂 **Detailed Analysis** - Visual artifacts list, size breakdown pie chart, category breakdown
+- 👁️ **Preview Mode** - See exactly what will be deleted before confirming
+- 🛡️ **Safe Removal** - Dual confirmation dialogs, optional backup creation
+- 🌙 **Dark Mode** - Beautiful theme with persistent preference
+- 🔌 **REST API** - Full API endpoints for integration
+- ⚡ **High Performance** - ~50KB gzipped, <100ms API response time
 
-```bash
-git clone https://github.com/praveenkay/AppClean.git
-cd AppClean
-npm install
-npm run build
-npm install -g .
-```
+---
 
-**Requirements:** Node.js 16+ and npm 7+
+## Quick Start
 
-## 💻 Usage
+### 1. Install AppClean
 
-### Interactive Mode
+```bash
+npm install -g appclean@2.0.0
+```
 
-Simply run:
+### 2. Launch the GUI (Recommended)
 
 ```bash
-appclean
+appclean gui
 ```
 
-Then use arrow keys to navigate and select actions:
-- 🔍 Search for applications
-- 📋 List all installed apps
-- 📊 View app details and artifacts
-- 🗑️ Remove applications safely
+Then open **http://localhost:3000** in your browser.
 
-### Command Mode
+### 3. Or Use the CLI
 
 ```bash
-# Search for an app
-appclean search webpack
-
-# List all applications
+# List all apps
 appclean list
 
-# Analyze app artifacts before removal
-appclean analyze webpack
-
-# Preview removal (no files deleted)
-appclean remove webpack --dry-run
+# Search for an app
+appclean search <app-name>
 
-# Remove with backup
-appclean remove webpack --backup
+# Analyze app and artifacts
+appclean analyze <app-name>
 
-# Remove without confirmations
-appclean remove webpack --force
+# Remove app (with confirmation)
+appclean remove <app-name>
 ```
 
-## Supported Package Managers
+---
 
-| Manager | Platform | Support |
-|---------|----------|---------|
-| npm | All | ✅ |
-| yarn | All | ✅ |
-| pnpm | All | ✅ |
-| Homebrew | macOS, Linux | ✅ |
-| apt | Linux | ✅ |
-| yum | Linux | ✅ |
-| dnf | Linux | ✅ |
-| Custom Scripts | All | ✅ |
+## Features
+
+### 🎨 Modern GUI Interface
+
+**Dashboard View**
+- 📊 Total apps, total space used, session metrics
+- 💾 Real-time disk usage gauge with health indicators
+- 📜 Recent activity log showing removed apps
+- 🚀 Quick action buttons
+
+**App Discovery (`#/apps`)**
+- 🔍 Real-time search with fuzzy matching
+- 🏷️ Filter by installation method (npm, Homebrew, apt, yum, custom)
+- 📊 Sort by name, size, or date installed
+- 📦 Visual app cards with version and size
+- 📄 Infinite scroll pagination
+
+**App Analysis (`#/apps/:appName`)**
+- 📂 Complete artifact listing with file paths
+- 📈 Visual pie chart showing size breakdown
+- 📋 Category breakdown (binaries, configs, caches, data, logs)
+- 👁️ Preview mode showing what will be deleted
+- 🗑️ Safe removal with dual confirmation
+- 💾 Optional backup creation before removal
+
+**Settings**
+- 🔄 Version checking and update notifications
+- 🚀 One-click upgrade to latest version
+- 🎨 Theme toggle (light/dark mode)
+- ℹ️ About section with documentation
+- ⚠️ Danger zone for uninstalling AppClean
+
+### 💻 Powerful CLI
+
+**Find Apps**
+- Detect apps from npm, yarn, pnpm, Homebrew, apt, yum, dnf
+- Search by name with instant results
+- Show app version and installation method
+
+**Analyze**
+- Find all related files (binaries, configs, caches, logs)
+- See how much space each app uses
+- Preview what will be deleted before removing
+
+**Remove Safely**
+- Dry-run mode to preview first
+- Backup option before deletion
+- Confirmation prompts to prevent accidents
+- Error reporting for failed deletions
+
+**Manage**
+- Check for updates: `appclean check-update`
+- Upgrade automatically: `appclean upgrade`
+- Uninstall AppClean: `appclean uninstall`
 
-## How It Works
+---
 
-AppClean intelligently detects and removes applications by:
+## GUI vs CLI
 
-1. **Scanning Installation Locations**
-   - Checks npm/yarn/pnpm global directories
-   - Queries Homebrew installation database
-   - Searches Linux package manager databases
-   - Scans custom binary locations
+| Feature | GUI | CLI |
+|---------|-----|-----|
+| **User-Friendly** | ✅ Great for everyone | ✅ Great for power users |
+| **Visuals** | ✅ Charts, cards, animations | ❌ Text-based |
+| **Speed** | ✅ Fast with API | ✅ Very fast |
+| **Automation** | ❌ Interactive | ✅ Scriptable |
+| **Remote Access** | ✅ Via network | ❌ Local only |
+| **Learning Curve** | ✅ Minimal | ⚠️ Moderate |
 
-2. **Locating Related Files**
-   - Configuration files (`~/.config`, `~/.bashrc`, etc.)
-   - Cache directories
-   - Data files and logs
-   - Service files (systemd, LaunchAgents, etc.)
+**Recommendation**: Use the GUI for discovery and management, CLI for scripting and automation.
 
-3. **Safe Removal**
-   - Preview all files to be removed with `--dry-run`
-   - Create optional backups before deletion
-   - Double confirmation before final removal
-   - Detailed error reporting
+---
 
-## 📚 Examples
+## Common Tasks
 
-### Interactive Search and Remove
+### Using the GUI
 
 ```bash
-$ appclean search webpack
-ℹ Found 1 app(s)
-
-? Select an app to remove: (Use arrow keys)
-❯ webpack (npm) - v5.89.0
-
-? What would you like to do? (Use arrow keys)
-❯ 📊 View details and artifacts
-  🗑️  Remove this app
-  ⬅️  Back to search
+# Start the GUI
+appclean gui
+
+# Open http://localhost:3000
+# Then:
+# 1. Click "Apps" to browse installed applications
+# 2. Search for an app by name
+# 3. Click app card to see details
+# 4. Click "Preview Removal" to see what will be deleted
+# 5. Click "Remove App" to uninstall (with confirmation)
 ```
 
-### Preview Before Removal
+### Using the CLI
 
 ```bash
-$ appclean remove webpack --dry-run
+# Find and remove an app
+appclean search firefox
+appclean analyze firefox
+appclean remove firefox --dry-run  # Preview first
+appclean remove firefox             # Actually remove
 
-ℹ Files to be removed:
-  binary   512 B    /usr/local/bin/webpack
-  config   1.2 KB   ~/.config/webpack
-  cache    15 MB    ~/.cache/webpack
-  data     2.3 MB   ~/.local/share/webpack
-  log      512 B    ~/.local/share/log/webpack
+# Remove multiple apps
+appclean list
+appclean remove <app1>
+appclean remove <app2>
 
-ℹ Total space to be freed: 17.5 MB
+# Backup before removing
+appclean remove <app-name> --backup
 
-✓ This is a preview only. No files were removed.
+# Use without confirmation
+appclean remove <app-name> --force
 ```
 
-### Safe Removal with Backup
+---
 
-```bash
-$ appclean remove webpack --backup
+## All Commands
 
-ℹ App: webpack
-ℹ Method: npm
-ℹ Version: 5.89.0
+### GUI Server
+```bash
+appclean gui                 # Start GUI on port 3000
+appclean gui --port 8080    # Use custom port
+```
 
-? This action cannot be undone. Remove webpack and all its files? (y/N) y
+### Search & List
+```bash
+appclean search <query>     # Find apps by name
+appclean list               # Show all installed apps
+appclean analyze <app>      # View app details and files
+```
 
-✓ Backup created: ~/.appclean-backups/webpack-2024-01-20T15-30-45.tar.gz
-✓ Successfully removed webpack (freed 17.5 MB)
+### Remove Apps
+```bash
+appclean remove <app>                # Remove app (with confirmation)
+appclean remove <app> --dry-run      # Preview only
+appclean remove <app> --backup       # Create backup first
+appclean remove <app> --force        # Skip confirmation
 ```
 
-### Check for Duplicate Files
+### Update AppClean
+```bash
+appclean upgrade            # Update to latest version
+appclean check-update       # Check for updates
+appclean --version          # Show current version
+```
 
+### Uninstall
 ```bash
-$ appclean find-duplicates ~/Documents ~/Downloads
+appclean uninstall          # Remove AppClean (with confirmation)
+appclean uninstall --force  # Remove without confirmation
+```
 
-ℹ Scanning for duplicate files...
-✓ Found 3 duplicate groups
-  Group 1: report.pdf (2.5 MB)
-    - ~/Documents/reports/report.pdf
-    - ~/Downloads/report.pdf
+---
 
-  Group 2: image.png (1.2 MB)
-    - ~/Documents/images/image.png
-    - ~/Pictures/image.png
+## API Documentation
 
-💾 Potential space savings: 3.7 MB
+The GUI server provides a REST API for integration with other tools.
+
+### Base URL
+```
+http://localhost:3000
 ```
 
-### Check for Updates
+### Endpoints
 
+**Get Dashboard Statistics**
 ```bash
-$ appclean check-updates
-
-📦 webpack: 5.89.0 → Latest: 5.90.0
-   npm install -g webpack@latest
-
-📦 typescript: 5.3.3 → Latest: 5.4.0
-   npm install -g typescript@latest
-
-✓ Found 2 updates available
+curl http://localhost:3000/api/dashboard/stats
 ```
 
-### List All Installed Apps
+Response:
+```json
+{
+  "success": true,
+  "data": {
+    "totalApps": 99,
+    "totalSpaceUsed": 4236604496,
+    "sessionAppsRemoved": 0,
+    "sessionSpaceFreed": 0,
+    "diskUsagePercent": 12,
+    "recentlyRemoved": []
+  }
+}
+```
 
+**List Applications**
 ```bash
-$ appclean list
-ℹ Found 42 app(s)
-
-┌──────────────┬──────────┬──────────┐
-│     Name     │ Version  │ Method   │
-├──────────────┼──────────┼──────────┤
-│ webpack      │ 5.89.0   │ npm      │
-│ typescript   │ 5.3.3    │ npm      │
-│ lodash       │ 4.17.21  │ npm      │
-│ node         │ 20.10.0  │ custom   │
-│ git          │ 2.43.0   │ brew     │
-│ python       │ 3.11.7   │ system   │
-└──────────────┴──────────┴──────────┘
+curl 'http://localhost:3000/api/apps/list?limit=20&offset=0'
 ```
 
-## Commands & Options
+Response:
+```json
+{
+  "success": true,
+  "data": {
+    "apps": [...],
+    "total": 99,
+    "page": 1,
+    "pageSize": 20
+  }
+}
+```
 
-### Core Commands
+**Search Applications**
 ```bash
-appclean search <query>           # Search for installed applications
-appclean list                     # List all installed applications
-appclean analyze <appName>        # Analyze an application and show its artifacts
-appclean remove <appName>         # Remove an application
-appclean gui                      # Launch GUI application (v1.2.0+)
+curl 'http://localhost:3000/api/apps/search?q=node&method=npm&sort=name'
 ```
 
-### Advanced Commands (v1.2.0 - v1.8.0)
+**Analyze Application**
 ```bash
-# Duplicate file operations
-appclean find-duplicates [paths]  # Find duplicate files (v1.3.0)
-
-# Dependency management
-appclean find-orphaned-packages   # Find unused npm packages (v1.4.0)
-
-# Plugin management
-appclean plugin register <path>   # Register custom plugin (v1.5.0)
-appclean plugin list              # List installed plugins (v1.5.0)
-appclean plugin enable <name>     # Enable plugin (v1.5.0)
-
-# Schedule management
-appclean schedule create <app>    # Create cleanup schedule (v1.6.0)
-appclean schedule list            # List all schedules (v1.6.0)
-appclean schedule delete <id>     # Delete schedule (v1.6.0)
-
-# Update checking
-appclean check-updates            # Check for available updates (v1.7.0)
-appclean update <appName>         # Update an application (v1.7.0)
+curl 'http://localhost:3000/api/apps/node/analysis'
+```
 
-# Performance
-appclean scan --optimize          # Optimize scan performance (v1.8.0)
-appclean clear-cache              # Clear scan cache (v1.8.0)
+Response:
+```json
+{
+  "success": true,
+  "data": {
+    "app": {...},
+    "artifacts": [...],
+    "totalSize": 52428800,
+    "breakdown": {
+      "binaries": 5000000,
+      "configs": 2000000,
+      "caches": 45000000,
+      "data": 100000,
+      "logs": 328800
+    }
+  }
+}
 ```
 
-### Common Options
+**Remove Application**
 ```bash
---dry-run                         # Preview without removing files
---backup                          # Create backup before removal
---force                           # Skip confirmation prompts
---help                            # Show help information
---version                         # Show version information
+curl -X POST 'http://localhost:3000/api/apps/node/remove' \
+  -H 'Content-Type: application/json' \
+  -d '{"dryRun": false, "createBackup": true}'
 ```
 
-## Safety Features
-
-⚠️ **AppClean prioritizes safety**:
-
-- **Dry-run by default**: Use `--dry-run` to preview what will be deleted
-- **Double confirmation**: You'll be asked to confirm twice before actual removal
-- **Backups**: Create optional backups before removing apps
-- **Detailed logging**: See exactly what's being removed
-- **Error reporting**: Clear error messages if something goes wrong
-
-## Latest Features Guide (v1.1.0 - v1.8.0)
-
-### v1.1.0 - Advanced Features
-- **Elevated Permissions**: Automatically detects and requests sudo/admin access
-- **Service File Detection**: Identifies LaunchAgent/LaunchDaemon (macOS) and systemd (Linux) files
-- **User Consent Recording**: Tracks all removal operations with timestamps
-- **Post-Removal Verification**: Confirms complete app removal via filesystem and commands
-- **Professional Reports**: Generate HTML and text reports with legal disclaimers
-
-**Usage:**
+**Check Version**
 ```bash
-appclean remove app-name      # Automatic elevation detection
-appclean remove app-name --backup  # Creates backup before removal
+curl 'http://localhost:3000/api/version'
 ```
 
-### v1.2.0 - GUI Application
-Modern web-based interface for visual app management.
-
-**Usage:**
+**Upgrade AppClean**
 ```bash
-appclean gui                   # Opens GUI at http://localhost:3000
+curl -X POST 'http://localhost:3000/api/upgrade'
 ```
 
-### v1.3.0 - Duplicate File Finder
-Find and manage duplicate files by SHA256 hash.
-
-**Usage:**
+**Uninstall AppClean**
 ```bash
-appclean find-duplicates ~/Documents ~/Downloads
-appclean find-duplicates --recursive /          # Search entire filesystem
+curl -X POST 'http://localhost:3000/api/uninstall'
 ```
 
-### v1.4.0 - Orphaned Dependency Detector
-Identify npm packages with no project dependencies.
+---
+
+## Examples
 
-**Usage:**
+### Remove Node.js package globally
 ```bash
-appclean find-orphaned-packages    # Find all unused packages
-appclean find-orphaned-packages --dry-run  # Preview without removal
+# Using GUI: Click on app → Preview → Remove
+# Using CLI:
+appclean remove express
 ```
 
-### v1.5.0 - Plugin System
-Extend AppClean with custom application detectors.
-
-**Usage:**
+### Remove Homebrew app
 ```bash
-appclean plugin register ./my-plugin.js
-appclean plugin list
-appclean plugin enable my-plugin
-appclean plugin config my-plugin --setting value
+# Using GUI: Search "spotify" → Click → Remove
+# Using CLI:
+appclean remove spotify
 ```
 
-### v1.6.0 - Scheduled Cleanup Automation
-Automate cleanup with recurring schedules.
+### Remove system package
+```bash
+# Using GUI: Search "vim" → Filter by apt → Click → Remove
+# Using CLI:
+sudo appclean remove vim
+```
 
-**Usage:**
+### Preview before removing
 ```bash
-appclean schedule create webpack --frequency daily
-appclean schedule create node --frequency weekly --backup
-appclean schedule list
-appclean schedule update schedule-id --frequency monthly
-appclean schedule delete schedule-id
+# Using GUI: Click "Preview Removal" button
+# Using CLI:
+appclean remove chrome --dry-run
+# Review output, then:
+appclean remove chrome
 ```
 
-### v1.7.0 - App Update Checker
-Check for available updates across all package managers.
+### Create backup before removing
+```bash
+# Using GUI: Automatic backup option is shown
+# Using CLI:
+appclean remove myapp --backup
+```
 
-**Usage:**
+### Use custom GUI port
 ```bash
-appclean check-updates              # Check all apps
-appclean check-updates webpack      # Check specific app
-appclean update webpack             # Update app
+appclean gui --port 8080
+# Open http://localhost:8080
 ```
 
-### v1.8.0 - Performance Optimizer
-Optimize scanning performance for large systems.
+---
 
-**Features:**
-- Multi-threaded scanning (configurable threads)
-- Intelligent result caching
-- Performance metrics and reporting
-- Automatic optimization recommendations
+## What Gets Removed?
 
-**Usage:**
-```bash
-appclean scan --optimize            # Use optimization settings
-appclean scan --threads 8           # Set thread count
-appclean clear-cache                # Clear cached scan results
-```
+AppClean intelligently finds and removes:
 
-## Platform-Specific Notes
+- ✓ Application binaries and executables
+- ✓ Configuration files (`.config`, `.local`, etc)
+- ✓ Cache directories and files
+- ✓ Log files and directories
+- ✓ Data files and user data
+- ✓ Launch agents/daemons (macOS)
+- ✓ Systemd services (Linux)
+- ✓ Man pages and documentation
+- ✓ Package manager metadata
 
-### macOS
-- Detects both Intel and Apple Silicon installations
-- Removes LaunchAgents and LaunchDaemons
-- Cleans Application Support directories
-- Handles .plist preference files
+---
 
-### Linux
-- Supports apt, yum, and dnf package managers
-- Removes systemd service files
-- Cleans .config and .local directories
-- Handles /var/log files
+## Platform Support
 
-### Windows
-- Scans Program Files directories
-- Removes APPDATA and LOCALAPPDATA entries
-- Handles .exe files and shortcuts
+| Feature | macOS | Linux | Windows |
+|---------|-------|-------|---------|
+| **npm/yarn/pnpm** | ✓ | ✓ | ✓ |
+| **Homebrew** | ✓ | ✓ | - |
+| **apt/yum/dnf** | - | ✓ | - |
+| **GUI** | ✓ | ✓ | ✓ |
+| **CLI** | ✓ | ✓ | ✓ |
+| **Custom apps** | ✓ | ✓ | ✓ |
 
-## Troubleshooting
+---
 
-### App not found
+## Architecture
 
-```bash
-appclean search partial-name
-```
+### Technology Stack
 
-Try searching with a partial name. AppClean searches by substring.
+**GUI (Client)**
+- ES2020 JavaScript modules
+- Hash-based SPA routing
+- Event-driven state management
+- CSS with design tokens and animations
+- Responsive layout (Flexbox, Grid)
 
-### Permission denied
+**Server**
+- Native Node.js HTTP module (no Express)
+- TypeScript with strict mode
+- RESTful API design
+- CORS enabled
 
-Some system files may require elevated permissions:
+**Core**
+- Intelligent app detection
+- Multi-package-manager support
+- Artifact discovery and categorization
+- Safe removal with validation
 
-```bash
-sudo appclean remove app-name
+### Directory Structure
+
+```
+src/
+├── ui/
+│   ├── client/              # SPA application
+│   │   ├── pages/           # Dashboard, Apps, Settings
+│   │   ├── state/           # Reactive stores
+│   │   ├── styles/          # CSS design system
+│   │   ├── utils/           # Router, formatting
+│   │   └── app.ts           # SPA entry point
+│   ├── server/              # API backend
+│   │   ├── routes/          # API endpoints
+│   │   ├── services/        # Business logic
+│   │   └── middleware/      # Request handling
+│   └── guiServer.ts         # HTTP server
+├── core/                    # App detection & removal
+├── managers/                # Package manager integrations
+└── utils/                   # Utilities
 ```
 
-### Can't restore backup
+---
+
+## Performance
 
-Backups are stored in `~/.appclean-backups/`:
+- **Bundle Size**: ~50KB gzipped (no frameworks)
+- **API Response**: <100ms per request
+- **Page Load**: <2 seconds
+- **Startup Time**: <1 second
+- **Memory Usage**: Minimal footprint
 
+---
+
+## Tips & Best Practices
+
+💡 **Always preview first**
 ```bash
-ls ~/.appclean-backups/
-tar -xzf ~/.appclean-backups/app-backup.tar.gz
+# GUI: Click "Preview Removal"
+# CLI: Use --dry-run flag
+appclean remove myapp --dry-run
 ```
 
-## Data & Storage Locations
+💡 **Create backups for important apps**
+```bash
+# GUI: Backup option is shown before removal
+# CLI: Use --backup flag
+appclean remove myapp --backup
+```
 
-AppClean stores all data in user home directory:
+💡 **Use the GUI for visual browsing**
+```bash
+appclean gui
+# Open http://localhost:3000
+# Visual cards and charts make it easy
+```
 
-| Data | Location | Purpose |
-|------|----------|---------|
-| Backups | `~/.appclean-backups/` | App removal backups |
-| Records | `~/.appclean-records/` | Removal operation history |
-| Reports | `~/.appclean-reports/` | Generated HTML/text reports |
-| Schedules | `~/.appclean-schedules.json` | Cleanup automation schedules |
-| Cache | `~/.appclean-cache/` | Scan result cache |
-| Results | `~/.appclean-cleanup-results/` | Scheduled cleanup results |
+💡 **Use CLI for scripting and automation**
+```bash
+# In shell scripts or CI/CD pipelines
+appclean remove myapp --force
+```
 
-All data is stored locally on your machine. No cloud upload or external connections.
+💡 **Check updates regularly**
+```bash
+appclean check-update
+# Or use GUI: Settings → Check for Updates
+```
 
-## Performance Tips
+---
 
-### For Large Systems (100k+ files)
-1. Use v1.8.0 Performance Optimizer
-2. Enable result caching: `appclean scan --cache`
-3. Increase thread count: `appclean scan --threads 8`
-4. Exclude system directories: `--exclude /usr --exclude /var`
+## Permissions
 
-### For Faster Scans
-1. Use caching: Results are automatically cached
-2. Skip deep directory scans: Set `--max-depth 5`
-3. Exclude symlinks: Enabled by default
-4. Pre-filter patterns: Use exclude patterns
+- **macOS/Linux**: May need `sudo` for system packages
+  ```bash
+  sudo appclean remove system-package
+  ```
+- **Windows**: May need to run as Administrator
 
-## Development
+---
 
-### Setup
+## Troubleshooting
 
+**"Permission denied" error**
 ```bash
-git clone https://github.com/YOUR_USERNAME/appclean.git
-cd appclean
-npm install
+# Try with sudo
+sudo appclean remove <app>
 ```
 
-### Build
-
+**App not found**
 ```bash
-npm run build
+# Search for partial name
+appclean search <partial-name>
+# Or use GUI search with fuzzy matching
 ```
 
-### Development Server
-
+**GUI won't start**
 ```bash
-npm run dev
+# Check if port 3000 is in use
+# Use custom port:
+appclean gui --port 8080
 ```
 
-### Run Tests
+**Want to preview without removing**
+```bash
+# Using GUI: Click "Preview Removal"
+# Using CLI: Use --dry-run flag
+appclean remove <app> --dry-run
+```
 
+**Want to restore from backup**
 ```bash
-npm test
+# Backups are saved in ~/.appclean-backups/
+ls ~/.appclean-backups/
+# Manually restore from tar.gz if needed
 ```
 
-## Contributing
+---
+
+## Safety Guarantees
+
+✅ **All actions require confirmation** (unless `--force` is used)
+✅ **Preview mode available** - see what will be deleted first
+✅ **Backup option available** - protect important data
+✅ **No data loss** - only removes application files
+✅ **Easy to reinstall** - use npm/brew/apt to reinstall apps
+✅ **Dry-run mode** - test before actual removal
 
-Contributions are welcome! Please:
+---
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+## Getting Help
 
-## Version History & Roadmap
+```bash
+# Show all commands
+appclean --help
 
-### Completed Features ✅
-- [x] **v1.0.0** - Initial release with core functionality
-- [x] **v1.1.0** - Advanced features (permissions, service detection, reporting)
-- [x] **v1.2.0** - GUI application for all platforms
-- [x] **v1.3.0** - Duplicate file finder
-- [x] **v1.4.0** - Orphaned dependency detection
-- [x] **v1.5.0** - Plugin system for custom detectors
-- [x] **v1.6.0** - Scheduled cleanup automation
-- [x] **v1.7.0** - App update checker
-- [x] **v1.8.0** - Performance optimization for large scans
+# Get help for specific command
+appclean remove --help
 
-### Future Roadmap 🚀
-- [ ] Mobile app (iOS/Android)
-- [ ] Advanced caching system
-- [ ] Batch operations
-- [ ] Custom rule builder
-- [ ] System notifications
-- [ ] Cloud sync for schedules
-- [ ] Advanced analytics dashboard
+# Check your version
+appclean --version
 
-## Known Limitations
+# Check if update available
+appclean check-update
+```
 
-- System packages may require elevated permissions to remove
-- Some service files may need manual cleanup
-- Snap packages (Linux) are currently not supported
+---
 
 ## License
 
-MIT License © 2026
+MIT License - Free to use and modify. See [LICENSE](LICENSE) file for details.
+
+---
 
-## Disclaimer
+## Support & Community
 
-⚠️ **Use with caution**: This tool permanently deletes files. Always use `--dry-run` first to preview changes.
+📝 **Report Issues**: https://github.com/praveenkay/AppClean/issues
+💬 **Discussions**: https://github.com/praveenkay/AppClean/discussions
+🌟 **Star** if you find it useful!
+📖 **Documentation**: https://github.com/praveenkay/AppClean#readme
 
-## 🤝 Support & Community
+---
 
-- **🐛 [Report Issues](https://github.com/praveenkay/AppClean/issues)** — Found a bug? Let us know
-- **💬 [Discussions](https://github.com/praveenkay/AppClean/discussions)** — Share ideas and feedback
-- **⭐ [Star on GitHub](https://github.com/praveenkay/AppClean)** — Show your support
+## Changelog
 
-## 📄 License
+### v2.0.0 (Current)
+- 🎉 Complete GUI overhaul with modern SPA interface
+- 📊 Dashboard with statistics and activity log
+- 🔍 Advanced search with filtering and sorting
+- 📂 Detailed artifact analysis with charts
+- 🛡️ Safe removal with preview and backup
+- 🌙 Dark mode support
+- 🔌 REST API endpoints
+- 📱 Responsive design (mobile, tablet, desktop)
 
-MIT License © 2026 [Praveen Kothapally](https://github.com/praveenkay)
+### v1.9.0
+- Version management and upgrade system
+- Basic web interface
+- Enhanced CLI functionality
 
 ---
 
-**Built with care for developers and system administrators who value clean systems**
+**Made with ❤️ by Praveen Kothapally**
 
-<div align="center">
-  Made with ❤️ by <a href="https://github.com/praveenkay">Praveen Kothapally</a>
-</div>
+*AppClean - Making app removal intelligent, safe, and beautiful.* ✨