From 484255aa73e0fd299e82785a318e46e6f791953f Mon Sep 17 00:00:00 2001
From: daymade <daymadev89@gmail.com>
Date: Sun, 11 Jan 2026 17:50:50 +0800
Subject: [PATCH] Release v1.21.1: Update macos-cleaner to v1.1.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Major improvements based on real-world usage experience:

- Add "Value Over Vanity" principle - prioritize identifying truly useless
  items over maximizing cleanup numbers
- Add "Network Environment Awareness" - consider slow internet when
  recommending cache deletion
- Add "Impact Analysis Required" - every recommendation must explain
  consequences
- Add comprehensive "Anti-Patterns" section documenting what NOT to delete
- Add "Multi-Layer Deep Exploration" guide with complete tmux + Mole TUI
  navigation workflow
- Add "High-Quality Report Template" with proven 3-tier classification
  (🟢/🟡/🔴)
- Add "Report Quality Checklist" for verification before presenting findings
- Add explicit prohibition of `docker volume prune -f`
- Update safety principles to emphasize cache value over cleanup metrics

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude-plugin/marketplace.json              | 406 ++++++++++--
 CHANGELOG.md                                 |  14 +
 macos-cleaner/.security-scan-passed          |   4 +-
 macos-cleaner/SKILL.md                       | 633 +++++++++++++++++--
 macos-cleaner/references/mole_integration.md | 578 ++++++++++-------
 5 files changed, 1298 insertions(+), 337 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index b90d78a..901ed96 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Professional Claude Code skills for GitHub operations, document conversion, diagram generation, statusline customization, Teams communication, repomix utilities, skill creation, CLI demo generation, LLM icon access, Cloudflare troubleshooting, UI design system extraction, professional presentation creation, YouTube video downloading, secure repomix packaging, ASR transcription correction, video comparison quality analysis, comprehensive QA testing infrastructure, prompt optimization with EARS methodology, session history recovery, documentation cleanup, PDF generation with Chinese font support, CLAUDE.md progressive disclosure optimization, CCPM skill registry search and management, Promptfoo LLM evaluation framework, iOS app development with XcodeGen and SwiftUI, fact-checking with automated corrections, Twitter/X content fetching, and intelligent macOS disk space recovery",
-    "version": "1.21.0",
+    "version": "1.21.1",
     "homepage": "https://github.com/daymade/claude-code-skills"
   },
   "plugins": [
@@ -17,8 +17,18 @@
       "strict": false,
       "version": "1.2.2",
       "category": "developer-tools",
-      "keywords": ["skill-creation", "claude-code", "development", "tooling", "workflow", "meta-skill", "essential"],
-      "skills": ["./skill-creator"]
+      "keywords": [
+        "skill-creation",
+        "claude-code",
+        "development",
+        "tooling",
+        "workflow",
+        "meta-skill",
+        "essential"
+      ],
+      "skills": [
+        "./skill-creator"
+      ]
     },
     {
       "name": "github-ops",
@@ -27,8 +37,17 @@
       "strict": false,
       "version": "1.0.0",
       "category": "developer-tools",
-      "keywords": ["github", "gh-cli", "pull-request", "issues", "workflows", "api"],
-      "skills": ["./github-ops"]
+      "keywords": [
+        "github",
+        "gh-cli",
+        "pull-request",
+        "issues",
+        "workflows",
+        "api"
+      ],
+      "skills": [
+        "./github-ops"
+      ]
     },
     {
       "name": "markdown-tools",
@@ -37,8 +56,17 @@
       "strict": false,
       "version": "1.1.0",
       "category": "document-conversion",
-      "keywords": ["markdown", "pdf", "docx", "confluence", "markitdown", "wsl"],
-      "skills": ["./markdown-tools"]
+      "keywords": [
+        "markdown",
+        "pdf",
+        "docx",
+        "confluence",
+        "markitdown",
+        "wsl"
+      ],
+      "skills": [
+        "./markdown-tools"
+      ]
     },
     {
       "name": "mermaid-tools",
@@ -47,8 +75,16 @@
       "strict": false,
       "version": "1.0.0",
       "category": "documentation",
-      "keywords": ["mermaid", "diagrams", "visualization", "flowchart", "sequence"],
-      "skills": ["./mermaid-tools"]
+      "keywords": [
+        "mermaid",
+        "diagrams",
+        "visualization",
+        "flowchart",
+        "sequence"
+      ],
+      "skills": [
+        "./mermaid-tools"
+      ]
     },
     {
       "name": "statusline-generator",
@@ -57,8 +93,16 @@
       "strict": false,
       "version": "1.0.0",
       "category": "customization",
-      "keywords": ["statusline", "ccusage", "git-status", "customization", "prompt"],
-      "skills": ["./statusline-generator"]
+      "keywords": [
+        "statusline",
+        "ccusage",
+        "git-status",
+        "customization",
+        "prompt"
+      ],
+      "skills": [
+        "./statusline-generator"
+      ]
     },
     {
       "name": "teams-channel-post-writer",
@@ -67,8 +111,16 @@
       "strict": false,
       "version": "1.0.0",
       "category": "communication",
-      "keywords": ["teams", "microsoft", "adaptive-cards", "communication", "announcements"],
-      "skills": ["./teams-channel-post-writer"]
+      "keywords": [
+        "teams",
+        "microsoft",
+        "adaptive-cards",
+        "communication",
+        "announcements"
+      ],
+      "skills": [
+        "./teams-channel-post-writer"
+      ]
     },
     {
       "name": "repomix-unmixer",
@@ -77,8 +129,16 @@
       "strict": false,
       "version": "1.0.0",
       "category": "utilities",
-      "keywords": ["repomix", "unmix", "extract", "xml", "conversion"],
-      "skills": ["./repomix-unmixer"]
+      "keywords": [
+        "repomix",
+        "unmix",
+        "extract",
+        "xml",
+        "conversion"
+      ],
+      "skills": [
+        "./repomix-unmixer"
+      ]
     },
     {
       "name": "llm-icon-finder",
@@ -87,8 +147,16 @@
       "strict": false,
       "version": "1.0.0",
       "category": "assets",
-      "keywords": ["icons", "ai-models", "llm", "branding", "lobe-icons"],
-      "skills": ["./llm-icon-finder"]
+      "keywords": [
+        "icons",
+        "ai-models",
+        "llm",
+        "branding",
+        "lobe-icons"
+      ],
+      "skills": [
+        "./llm-icon-finder"
+      ]
     },
     {
       "name": "cli-demo-generator",
@@ -97,8 +165,19 @@
       "strict": false,
       "version": "1.0.0",
       "category": "developer-tools",
-      "keywords": ["cli", "demo", "terminal", "vhs", "gif", "recording", "animation", "documentation"],
-      "skills": ["./cli-demo-generator"]
+      "keywords": [
+        "cli",
+        "demo",
+        "terminal",
+        "vhs",
+        "gif",
+        "recording",
+        "animation",
+        "documentation"
+      ],
+      "skills": [
+        "./cli-demo-generator"
+      ]
     },
     {
       "name": "cloudflare-troubleshooting",
@@ -107,8 +186,18 @@
       "strict": false,
       "version": "1.0.0",
       "category": "developer-tools",
-      "keywords": ["cloudflare", "troubleshooting", "ssl", "dns", "api", "debugging", "devops"],
-      "skills": ["./cloudflare-troubleshooting"]
+      "keywords": [
+        "cloudflare",
+        "troubleshooting",
+        "ssl",
+        "dns",
+        "api",
+        "debugging",
+        "devops"
+      ],
+      "skills": [
+        "./cloudflare-troubleshooting"
+      ]
     },
     {
       "name": "ui-designer",
@@ -117,8 +206,17 @@
       "strict": false,
       "version": "1.0.0",
       "category": "design",
-      "keywords": ["ui", "design-system", "mockup", "screenshot", "design-extraction", "mvp"],
-      "skills": ["./ui-designer"]
+      "keywords": [
+        "ui",
+        "design-system",
+        "mockup",
+        "screenshot",
+        "design-extraction",
+        "mvp"
+      ],
+      "skills": [
+        "./ui-designer"
+      ]
     },
     {
       "name": "ppt-creator",
@@ -127,8 +225,19 @@
       "strict": false,
       "version": "1.0.0",
       "category": "productivity",
-      "keywords": ["presentation", "powerpoint", "pptx", "slides", "marp", "charts", "data-visualization", "pyramid-principle"],
-      "skills": ["./ppt-creator"]
+      "keywords": [
+        "presentation",
+        "powerpoint",
+        "pptx",
+        "slides",
+        "marp",
+        "charts",
+        "data-visualization",
+        "pyramid-principle"
+      ],
+      "skills": [
+        "./ppt-creator"
+      ]
     },
     {
       "name": "youtube-downloader",
@@ -137,8 +246,23 @@
       "strict": false,
       "version": "1.1.0",
       "category": "utilities",
-      "keywords": ["youtube", "yt-dlp", "video-download", "audio-extraction", "mp3", "download", "hls", "m3u8", "ffmpeg", "streaming", "mux", "vimeo"],
-      "skills": ["./youtube-downloader"]
+      "keywords": [
+        "youtube",
+        "yt-dlp",
+        "video-download",
+        "audio-extraction",
+        "mp3",
+        "download",
+        "hls",
+        "m3u8",
+        "ffmpeg",
+        "streaming",
+        "mux",
+        "vimeo"
+      ],
+      "skills": [
+        "./youtube-downloader"
+      ]
     },
     {
       "name": "repomix-safe-mixer",
@@ -147,8 +271,18 @@
       "strict": false,
       "version": "1.0.0",
       "category": "security",
-      "keywords": ["repomix", "security", "credentials", "secrets-scanning", "safe-packaging", "secret-detection", "code-security"],
-      "skills": ["./repomix-safe-mixer"]
+      "keywords": [
+        "repomix",
+        "security",
+        "credentials",
+        "secrets-scanning",
+        "safe-packaging",
+        "secret-detection",
+        "code-security"
+      ],
+      "skills": [
+        "./repomix-safe-mixer"
+      ]
     },
     {
       "name": "transcript-fixer",
@@ -157,8 +291,19 @@
       "strict": false,
       "version": "1.1.0",
       "category": "productivity",
-      "keywords": ["transcription", "asr", "stt", "speech-to-text", "correction", "ai", "meeting-notes", "nlp"],
-      "skills": ["./transcript-fixer"]
+      "keywords": [
+        "transcription",
+        "asr",
+        "stt",
+        "speech-to-text",
+        "correction",
+        "ai",
+        "meeting-notes",
+        "nlp"
+      ],
+      "skills": [
+        "./transcript-fixer"
+      ]
     },
     {
       "name": "video-comparer",
@@ -167,8 +312,19 @@
       "strict": false,
       "version": "1.0.0",
       "category": "media",
-      "keywords": ["video", "comparison", "quality-analysis", "psnr", "ssim", "compression", "ffmpeg", "codec"],
-      "skills": ["./video-comparer"]
+      "keywords": [
+        "video",
+        "comparison",
+        "quality-analysis",
+        "psnr",
+        "ssim",
+        "compression",
+        "ffmpeg",
+        "codec"
+      ],
+      "skills": [
+        "./video-comparer"
+      ]
     },
     {
       "name": "qa-expert",
@@ -177,8 +333,21 @@
       "strict": false,
       "version": "1.0.0",
       "category": "developer-tools",
-      "keywords": ["qa", "testing", "test-cases", "bug-tracking", "google-standards", "owasp", "security", "automation", "quality-gates", "metrics"],
-      "skills": ["./qa-expert"]
+      "keywords": [
+        "qa",
+        "testing",
+        "test-cases",
+        "bug-tracking",
+        "google-standards",
+        "owasp",
+        "security",
+        "automation",
+        "quality-gates",
+        "metrics"
+      ],
+      "skills": [
+        "./qa-expert"
+      ]
     },
     {
       "name": "prompt-optimizer",
@@ -187,8 +356,19 @@
       "strict": false,
       "version": "1.1.0",
       "category": "productivity",
-      "keywords": ["prompt-engineering", "ears", "requirements", "specifications", "optimization", "domain-theory", "prompt-enhancement", "ai-prompting"],
-      "skills": ["./prompt-optimizer"]
+      "keywords": [
+        "prompt-engineering",
+        "ears",
+        "requirements",
+        "specifications",
+        "optimization",
+        "domain-theory",
+        "prompt-enhancement",
+        "ai-prompting"
+      ],
+      "skills": [
+        "./prompt-optimizer"
+      ]
     },
     {
       "name": "claude-code-history-files-finder",
@@ -197,8 +377,18 @@
       "strict": false,
       "version": "1.0.0",
       "category": "developer-tools",
-      "keywords": ["session-history", "recovery", "deleted-files", "conversation-history", "file-tracking", "claude-code", "history-analysis"],
-      "skills": ["./claude-code-history-files-finder"]
+      "keywords": [
+        "session-history",
+        "recovery",
+        "deleted-files",
+        "conversation-history",
+        "file-tracking",
+        "claude-code",
+        "history-analysis"
+      ],
+      "skills": [
+        "./claude-code-history-files-finder"
+      ]
     },
     {
       "name": "docs-cleaner",
@@ -207,8 +397,17 @@
       "strict": false,
       "version": "1.0.0",
       "category": "productivity",
-      "keywords": ["documentation", "cleanup", "consolidation", "redundancy", "merge", "docs"],
-      "skills": ["./docs-cleaner"]
+      "keywords": [
+        "documentation",
+        "cleanup",
+        "consolidation",
+        "redundancy",
+        "merge",
+        "docs"
+      ],
+      "skills": [
+        "./docs-cleaner"
+      ]
     },
     {
       "name": "pdf-creator",
@@ -217,8 +416,19 @@
       "strict": false,
       "version": "1.0.0",
       "category": "document-conversion",
-      "keywords": ["pdf", "markdown", "weasyprint", "chinese-fonts", "document-generation", "legal", "reports", "typography"],
-      "skills": ["./pdf-creator"]
+      "keywords": [
+        "pdf",
+        "markdown",
+        "weasyprint",
+        "chinese-fonts",
+        "document-generation",
+        "legal",
+        "reports",
+        "typography"
+      ],
+      "skills": [
+        "./pdf-creator"
+      ]
     },
     {
       "name": "claude-md-progressive-disclosurer",
@@ -227,8 +437,17 @@
       "strict": false,
       "version": "1.0.1",
       "category": "productivity",
-      "keywords": ["claude-md", "progressive-disclosure", "optimization", "context-efficiency", "configuration", "token-savings"],
-      "skills": ["./claude-md-progressive-disclosurer"]
+      "keywords": [
+        "claude-md",
+        "progressive-disclosure",
+        "optimization",
+        "context-efficiency",
+        "configuration",
+        "token-savings"
+      ],
+      "skills": [
+        "./claude-md-progressive-disclosurer"
+      ]
     },
     {
       "name": "skills-search",
@@ -237,8 +456,20 @@
       "strict": false,
       "version": "1.0.0",
       "category": "developer-tools",
-      "keywords": ["ccpm", "skills", "search", "install", "registry", "plugin", "marketplace", "discovery", "skill-management"],
-      "skills": ["./skills-search"]
+      "keywords": [
+        "ccpm",
+        "skills",
+        "search",
+        "install",
+        "registry",
+        "plugin",
+        "marketplace",
+        "discovery",
+        "skill-management"
+      ],
+      "skills": [
+        "./skills-search"
+      ]
     },
     {
       "name": "promptfoo-evaluation",
@@ -247,8 +478,19 @@
       "strict": false,
       "version": "1.0.0",
       "category": "developer-tools",
-      "keywords": ["promptfoo", "evaluation", "llm-testing", "prompt-testing", "assertions", "llm-rubric", "few-shot", "model-comparison"],
-      "skills": ["./promptfoo-evaluation"]
+      "keywords": [
+        "promptfoo",
+        "evaluation",
+        "llm-testing",
+        "prompt-testing",
+        "assertions",
+        "llm-rubric",
+        "few-shot",
+        "model-comparison"
+      ],
+      "skills": [
+        "./promptfoo-evaluation"
+      ]
     },
     {
       "name": "iOS-APP-developer",
@@ -257,8 +499,22 @@
       "strict": false,
       "version": "1.1.0",
       "category": "developer-tools",
-      "keywords": ["ios", "xcodegen", "swiftui", "spm", "avfoundation", "camera", "code-signing", "device-deployment", "swift", "xcode", "testing"],
-      "skills": ["./iOS-APP-developer"]
+      "keywords": [
+        "ios",
+        "xcodegen",
+        "swiftui",
+        "spm",
+        "avfoundation",
+        "camera",
+        "code-signing",
+        "device-deployment",
+        "swift",
+        "xcode",
+        "testing"
+      ],
+      "skills": [
+        "./iOS-APP-developer"
+      ]
     },
     {
       "name": "fact-checker",
@@ -267,8 +523,18 @@
       "strict": false,
       "version": "1.0.0",
       "category": "productivity",
-      "keywords": ["fact-checking", "verification", "accuracy", "sources", "validation", "corrections", "web-search"],
-      "skills": ["./fact-checker"]
+      "keywords": [
+        "fact-checking",
+        "verification",
+        "accuracy",
+        "sources",
+        "validation",
+        "corrections",
+        "web-search"
+      ],
+      "skills": [
+        "./fact-checker"
+      ]
     },
     {
       "name": "twitter-reader",
@@ -277,18 +543,42 @@
       "strict": false,
       "version": "1.0.0",
       "category": "utilities",
-      "keywords": ["twitter", "x", "social-media", "jina", "content-fetching", "api", "scraping", "threads"],
-      "skills": ["./twitter-reader"]
+      "keywords": [
+        "twitter",
+        "x",
+        "social-media",
+        "jina",
+        "content-fetching",
+        "api",
+        "scraping",
+        "threads"
+      ],
+      "skills": [
+        "./twitter-reader"
+      ]
     },
     {
       "name": "macos-cleaner",
       "description": "Intelligent macOS disk space analysis and cleanup with safety-first philosophy. Use when users report disk space issues, need to clean their Mac, or want to understand storage consumption. Analyzes system caches, application remnants, large files, and development environments (Docker, Homebrew, npm, pip) with risk categorization (Safe/Caution/Keep) and requires explicit user confirmation before any deletions. Includes Mole visual tool integration for hybrid workflow",
       "source": "./",
       "strict": false,
-      "version": "1.0.0",
+      "version": "1.1.0",
       "category": "utilities",
-      "keywords": ["macos", "disk-space", "cleanup", "cache", "storage", "developer-tools", "docker", "homebrew", "system-maintenance", "safety"],
-      "skills": ["./macos-cleaner"]
+      "keywords": [
+        "macos",
+        "disk-space",
+        "cleanup",
+        "cache",
+        "storage",
+        "developer-tools",
+        "docker",
+        "homebrew",
+        "system-maintenance",
+        "safety"
+      ],
+      "skills": [
+        "./macos-cleaner"
+      ]
     }
   ]
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7d0d9b2..b400b41 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Security
 - None
 
+## [1.21.1] - 2026-01-11
+
+### Changed
+- **Updated Skill**: macos-cleaner v1.0.0 → v1.1.0 - Major improvements based on real-world usage
+  - Added "Value Over Vanity" principle: Goal is identifying truly useless items, not maximizing cleanup numbers
+  - Added "Network Environment Awareness": Consider slow internet (especially in China) when recommending cache deletion
+  - Added "Impact Analysis Required": Every cleanup recommendation must explain consequences
+  - Added comprehensive "Anti-Patterns" section: What NOT to delete (Xcode DerivedData, npm _cacache, uv cache, Playwright, iOS DeviceSupport, etc.)
+  - Added "Multi-Layer Deep Exploration" guide: Complete tmux + Mole TUI navigation workflow
+  - Added "High-Quality Report Template": Proven 3-tier classification report format (🟢/🟡/🔴)
+  - Added "Report Quality Checklist": 8-point verification before presenting findings
+  - Added explicit prohibition of `docker volume prune -f` - must confirm per-project
+  - Updated safety principles to emphasize cache value over cleanup metrics
+
 ## [1.21.0] - 2026-01-11
 
 ### Added
diff --git a/macos-cleaner/.security-scan-passed b/macos-cleaner/.security-scan-passed
index 3d5abb8..3e21731 100644
--- a/macos-cleaner/.security-scan-passed
+++ b/macos-cleaner/.security-scan-passed
@@ -1,4 +1,4 @@
 Security scan passed
-Scanned at: 2026-01-11T15:33:50.497864
+Scanned at: 2026-01-11T17:48:10.512079
 Tool: gitleaks + pattern-based validation
-Content hash: 837b8b7dfa3a728295649b608acaba00d7eb2b1fbbe02a35f5c8e0ffc8c2e361
+Content hash: de94268166b88b2b704930f641a401a1eddcf2ea957ca6185533203b9e13fb04
diff --git a/macos-cleaner/SKILL.md b/macos-cleaner/SKILL.md
index bc0fd73..1b42226 100644
--- a/macos-cleaner/SKILL.md
+++ b/macos-cleaner/SKILL.md
@@ -13,11 +13,21 @@ Intelligently analyze macOS disk usage and provide actionable cleanup recommenda
 
 ## Core Principles
 
-1. **Analyze First, Act Second**: Never delete files without explicit user confirmation
-2. **Transparency**: Explain what each file/directory is and why it's safe (or unsafe) to delete
-3. **Interactive Decision Making**: Present findings in human-readable format, let users decide
-4. **Conservative Defaults**: When in doubt, don't delete
-5. **Backup Suggestions**: Recommend Time Machine backup before major cleanups
+1. **Safety First, Never Bypass**: NEVER execute dangerous commands (`rm -rf`, `mo clean`, etc.) without explicit user confirmation. No shortcuts, no workarounds.
+2. **Value Over Vanity**: Your goal is NOT to maximize cleaned space. Your goal is to identify what is **truly useless** vs **valuable cache**. Clearing 50GB of useful cache just to show a big number is harmful.
+3. **Network Environment Awareness**: Many users (especially in China) have slow/unreliable internet. Re-downloading caches can take hours. A cache that saves 30 minutes of download time is worth keeping.
+4. **Impact Analysis Required**: Every cleanup recommendation MUST include "what happens if deleted" column. Never just list items without explaining consequences.
+5. **Patience Over Speed**: Disk scans can take 5-10 minutes. NEVER interrupt or skip slow operations. Report progress to user regularly.
+6. **User Executes Cleanup**: After analysis, provide the cleanup command for the user to run themselves. Do NOT auto-execute cleanup.
+7. **Conservative Defaults**: When in doubt, don't delete. Err on the side of caution.
+
+**ABSOLUTE PROHIBITIONS:**
+- ❌ NEVER run `rm -rf` on user directories automatically
+- ❌ NEVER run `mo clean` without dry-run preview first
+- ❌ NEVER use `docker volume prune -f` or `docker system prune -a --volumes`
+- ❌ NEVER skip analysis steps to save time
+- ❌ NEVER append `--help` to Mole commands (except `mo --help`)
+- ❌ NEVER recommend deleting useful caches just to inflate cleanup numbers
 
 ## Workflow Decision Tree
 
@@ -42,41 +52,124 @@ Immediate    Deep Analysis
   Verify Results
 ```
 
-## Step 1: Quick Diagnosis
+## Step 1: Quick Diagnosis with Mole
 
-Start with a rapid assessment to understand the scope:
+**Primary tool**: Use Mole for disk analysis. It provides comprehensive, categorized results.
+
+### 1.1 Pre-flight Checks
 
 ```bash
-# Check available disk space
-df -h /
+# Check Mole installation and version
+which mo && mo --version
 
-# Find top 10 largest directories in home folder
-du -h -d 1 ~ | sort -hr | head -n 10
+# If not installed
+brew install tw93/tap/mole
 
-# Quick check for common space hogs
-du -sh ~/Library/Caches ~/Library/Logs ~/Downloads ~/.Trash 2>/dev/null
+# Check for updates (Mole updates frequently)
+brew info tw93/tap/mole | head -5
+
+# Upgrade if outdated
+brew upgrade tw93/tap/mole
 ```
 
-**Present findings in this format:**
+### 1.2 Choose Analysis Method
+
+**IMPORTANT**: Use `mo analyze` as the primary analysis tool, NOT `mo clean --dry-run`.
+
+| Command | Purpose | Use When |
+|---------|---------|----------|
+| `mo analyze` | Interactive disk usage explorer (TUI tree view) | **PRIMARY**: Understanding what's consuming space |
+| `mo clean --dry-run` | Preview cleanup categories | **SECONDARY**: Only after `mo analyze` to see cleanup preview |
+
+**Why prefer `mo analyze`:**
+- Dedicated disk analysis tool with interactive tree navigation
+- Allows drilling down into specific directories
+- Shows actual disk usage breakdown, not just cleanup categories
+- More informative for understanding storage consumption
+
+### 1.3 Run Analysis via tmux
+
+**IMPORTANT**: Mole requires TTY. Always use tmux from Claude Code.
+
+**CRITICAL TIMING NOTE**: Home directory scans are SLOW (5-10 minutes or longer for large directories). Inform user upfront and wait patiently.
+
+```bash
+# Create tmux session
+tmux new-session -d -s mole -x 120 -y 40
+
+# Run disk analysis (PRIMARY tool - interactive TUI)
+tmux send-keys -t mole 'mo analyze' Enter
+
+# Wait for scan - BE PATIENT!
+# Home directory scanning typically takes 5-10 minutes
+# Report progress to user regularly
+sleep 60 && tmux capture-pane -t mole -p
+
+# Navigate the TUI with arrow keys
+tmux send-keys -t mole Down    # Move to next item
+tmux send-keys -t mole Enter   # Expand/select item
+tmux send-keys -t mole 'q'     # Quit when done
+```
+
+**Alternative: Cleanup preview (use AFTER mo analyze)**
+```bash
+# Run dry-run preview (SAFE - no deletion)
+tmux send-keys -t mole 'mo clean --dry-run' Enter
+
+# Wait for scan (report progress to user every 30 seconds)
+# Be patient! Large directories take 5-10 minutes
+sleep 30 && tmux capture-pane -t mole -p
+```
+
+### 1.4 Progress Reporting
+
+Report scan progress to user regularly:
 
 ```
-📊 Disk Space Analysis
-━━━━━━━━━━━━━━━━━━━━━━━━
-Total:     500 GB
-Used:      450 GB (90%)
-Available:  50 GB (10%)
+📊 Disk Analysis in Progress...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⏱️ Elapsed: 2 minutes
 
-🔍 Top Space Consumers:
-1. ~/Library/Caches          45 GB
-2. ~/Downloads                38 GB
-3. ~/Library/Application Support  25 GB
-4. ~/.Trash                   12 GB
-5. ~/Library/Logs              8 GB
+Current status:
+✅ Applications: 49.5 GB (complete)
+✅ System Library: 10.3 GB (complete)
+⏳ Home: scanning... (this may take 5-10 minutes)
+⏳ App Library: pending
 
-⚡ Quick Win Opportunities:
-- Empty Trash: ~12 GB
-- Clear Downloads: ~38 GB (requires user review)
-- System Caches: ~45 GB (mostly safe to clear)
+I'm waiting patiently for the scan to complete.
+Will report again in 30 seconds...
+```
+
+### 1.5 Present Final Findings
+
+After scan completes, present structured results:
+
+```
+📊 Disk Space Analysis (via Mole)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Free space: 27 GB
+
+🧹 Recoverable Space (dry-run preview):
+
+➤ User Essentials
+  • User app cache:     16.67 GB
+  • User app logs:      102.3 MB
+  • Trash:              642.9 MB
+
+➤ Browser Caches
+  • Chrome cache:       1.90 GB
+  • Safari cache:       4 KB
+
+➤ Developer Tools
+  • uv cache:           9.96 GB
+  • npm cache:          (detected)
+  • Docker cache:       (detected)
+  • Homebrew cache:     (detected)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Total recoverable: ~30 GB
+
+⚠️ This was a dry-run preview. No files were deleted.
 ```
 
 ## Step 2: Deep Analysis Categories
@@ -192,48 +285,474 @@ Total potential:       9 GB
 
 **Cleanup commands (require confirmation):**
 ```bash
-# Docker cleanup
-docker system prune -a --volumes
-
-# Homebrew cleanup
+# Homebrew cleanup (safe)
 brew cleanup -s
 
-# npm cache
-npm cache clean --force
+# npm _npx only (safe - temporary packages)
+rm -rf ~/.npm/_npx
 
-# pip cache
+# pip cache (use with caution)
 pip cache purge
 ```
 
-**Safety level**: 🟢 Safe for development caches, 🟡 Caution for Docker volumes
+**Docker cleanup - SPECIAL HANDLING REQUIRED:**
+
+⚠️ **NEVER use these commands:**
+```bash
+# ❌ DANGEROUS - deletes ALL volumes without confirmation
+docker volume prune -f
+docker system prune -a --volumes
+```
+
+✅ **Correct approach - per-volume confirmation:**
+```bash
+# 1. List all volumes
+docker volume ls
+
+# 2. Identify which projects each volume belongs to
+docker volume inspect <volume_name>
+
+# 3. Ask user to confirm EACH project they want to delete
+# Example: "Do you want to delete all volumes for 'ragflow' project?"
+
+# 4. Delete specific volumes only after confirmation
+docker volume rm ragflow_mysql_data ragflow_redis_data
+```
+
+**Safety level**: 🟢 Homebrew/npm cleanup, 🔴 Docker volumes require per-project confirmation
 
 ## Step 3: Integration with Mole
 
-**Mole** (https://github.com/tw93/Mole) is a visual macOS cleaner. Recommend it as a complementary tool for users who want GUI-based cleanup.
+**Mole** (https://github.com/tw93/Mole) is a **command-line interface (CLI)** tool for comprehensive macOS cleanup. It provides interactive terminal-based analysis and cleanup for caches, logs, developer tools, and more.
 
-**When to suggest Mole:**
-- User prefers visual interface over command-line
-- User wants one-click cleaning for common targets
-- Script analysis reveals complex cleanup needs
+**CRITICAL REQUIREMENTS:**
 
-**How to integrate:**
+1. **TTY Environment**: Mole requires a TTY for interactive commands. Use `tmux` when running from Claude Code or scripts.
+2. **Version Check**: Always verify Mole is up-to-date before use.
+3. **Safe Help Command**: Only `mo --help` is safe. Do NOT append `--help` to other commands.
 
-1. **Check if Mole is installed:**
-   ```bash
-   if [ -d "/Applications/Mole.app" ]; then
-     echo "✅ Mole is installed"
-   else
-     echo "💡 Consider installing Mole for visual cleanup: https://github.com/tw93/Mole"
-   fi
-   ```
+**Installation check and upgrade:**
 
-2. **Coordinate workflow:**
-   - Use scripts for detailed analysis and reports
-   - Suggest Mole for executing approved cleanups
-   - Use scripts for developer-specific cleanup (Docker, npm, etc.)
+```bash
+# Check if installed and get version
+which mo && mo --version
 
-3. **Reference guide:**
-   See `references/mole_integration.md` for detailed usage.
+# If not installed
+brew install tw93/tap/mole
+
+# Check for updates
+brew info tw93/tap/mole | head -5
+
+# Upgrade if needed
+brew upgrade tw93/tap/mole
+```
+
+**Using Mole with tmux (REQUIRED for Claude Code):**
+
+```bash
+# Create tmux session for TTY environment
+tmux new-session -d -s mole -x 120 -y 40
+
+# Run analysis (safe, read-only)
+tmux send-keys -t mole 'mo analyze' Enter
+
+# Wait for scan (be patient - can take 5-10 minutes for large directories)
+sleep 60
+
+# Capture results
+tmux capture-pane -t mole -p
+
+# Cleanup when done
+tmux kill-session -t mole
+```
+
+**Available commands (from `mo --help`):**
+
+| Command | Safety | Description |
+|---------|--------|-------------|
+| `mo --help` | ✅ Safe | View all commands (ONLY safe help) |
+| `mo analyze` | ✅ Safe | Disk usage explorer (read-only) |
+| `mo status` | ✅ Safe | System health monitor |
+| `mo clean --dry-run` | ✅ Safe | Preview cleanup (no deletion) |
+| `mo clean` | ⚠️ DANGEROUS | Actually deletes files |
+| `mo purge` | ⚠️ DANGEROUS | Remove project artifacts |
+| `mo uninstall` | ⚠️ DANGEROUS | Remove applications |
+
+**Reference guide:**
+See `references/mole_integration.md` for detailed tmux workflow and troubleshooting.
+
+## Multi-Layer Deep Exploration with Mole
+
+**CRITICAL**: For comprehensive analysis, you MUST perform multi-layer exploration, not just top-level scans. This section documents the proven workflow for navigating Mole's TUI.
+
+### Navigation Commands
+
+```bash
+# Create session
+tmux new-session -d -s mole -x 120 -y 40
+
+# Start analysis
+tmux send-keys -t mole 'mo analyze' Enter
+
+# Wait for initial scan
+sleep 8 && tmux capture-pane -t mole -p
+
+# Navigation keys (send via tmux)
+tmux send-keys -t mole Enter    # Enter/expand selected directory
+tmux send-keys -t mole Left     # Go back to parent directory
+tmux send-keys -t mole Down     # Move to next item
+tmux send-keys -t mole Up       # Move to previous item
+tmux send-keys -t mole 'q'      # Quit TUI
+
+# Capture current view
+tmux capture-pane -t mole -p
+```
+
+### Multi-Layer Exploration Workflow
+
+**Step 1: Top-level overview**
+```bash
+# Start mo analyze, wait for initial menu
+tmux send-keys -t mole 'mo analyze' Enter
+sleep 8 && tmux capture-pane -t mole -p
+
+# Example output:
+# 1. Home           289.4 GB (58.5%)
+# 2. App Library    145.2 GB (29.4%)
+# 3. Applications    49.5 GB (10.0%)
+# 4. System Library  10.3 GB (2.1%)
+```
+
+**Step 2: Enter largest directory (Home)**
+```bash
+tmux send-keys -t mole Enter
+sleep 10 && tmux capture-pane -t mole -p
+
+# Example output:
+# 1. Library       144.4 GB (49.9%)
+# 2. Workspace      52.0 GB (18.0%)
+# 3. .cache         19.3 GB (6.7%)
+# 4. Applications   17.0 GB (5.9%)
+# ...
+```
+
+**Step 3: Drill into specific directories**
+```bash
+# Go to .cache (3rd item: Down Down Enter)
+tmux send-keys -t mole Down Down Enter
+sleep 5 && tmux capture-pane -t mole -p
+
+# Example output:
+# 1. uv           10.3 GB (55.6%)
+# 2. modelscope    5.5 GB (29.5%)
+# 3. huggingface   887.8 MB (4.7%)
+```
+
+**Step 4: Navigate back and explore another branch**
+```bash
+# Go back to parent
+tmux send-keys -t mole Left
+sleep 2
+
+# Navigate to different directory
+tmux send-keys -t mole Down Down Down Down Enter  # Go to .npm
+sleep 5 && tmux capture-pane -t mole -p
+```
+
+**Step 5: Deep dive into Library**
+```bash
+# Back to Home, then into Library
+tmux send-keys -t mole Left
+tmux send-keys -t mole Up Up Up Up Up Up Enter  # Go to Library
+sleep 10 && tmux capture-pane -t mole -p
+
+# Example output:
+# 1. Application Support  37.1 GB
+# 2. Containers          35.4 GB
+# 3. Developer           17.8 GB  ← Xcode is here
+# 4. Caches               8.2 GB
+```
+
+### Recommended Exploration Path
+
+For comprehensive analysis, follow this exploration tree:
+
+```
+mo analyze
+├── Home (Enter)
+│   ├── Library (Enter)
+│   │   ├── Developer (Enter) → Xcode/DerivedData, iOS DeviceSupport
+│   │   ├── Caches (Enter) → Playwright, JetBrains, etc.
+│   │   └── Application Support (Enter) → App data
+│   ├── .cache (Enter) → uv, modelscope, huggingface
+│   ├── .npm (Enter) → _cacache, _npx
+│   ├── Downloads (Enter) → Large files to review
+│   ├── .Trash (Enter) → Confirm trash contents
+│   └── miniconda3/other dev tools (Enter) → Check last used time
+├── App Library → Usually overlaps with ~/Library
+└── Applications → Installed apps
+```
+
+### Time Expectations
+
+| Directory | Scan Time | Notes |
+|-----------|-----------|-------|
+| Top-level menu | 5-8 seconds | Fast |
+| Home directory | 5-10 minutes | Large, be patient |
+| ~/Library | 3-5 minutes | Many small files |
+| Subdirectories | 2-30 seconds | Varies by size |
+
+### Example Complete Session
+
+```bash
+# 1. Create session
+tmux new-session -d -s mole -x 120 -y 40
+
+# 2. Start analysis and get overview
+tmux send-keys -t mole 'mo analyze' Enter
+sleep 8 && tmux capture-pane -t mole -p
+
+# 3. Enter Home
+tmux send-keys -t mole Enter
+sleep 10 && tmux capture-pane -t mole -p
+
+# 4. Enter .cache to see dev caches
+tmux send-keys -t mole Down Down Enter
+sleep 5 && tmux capture-pane -t mole -p
+
+# 5. Back to Home, then to .npm
+tmux send-keys -t mole Left
+sleep 2
+tmux send-keys -t mole Down Down Down Down Enter
+sleep 5 && tmux capture-pane -t mole -p
+
+# 6. Back to Home, enter Library
+tmux send-keys -t mole Left
+sleep 2
+tmux send-keys -t mole Up Up Up Up Up Up Enter
+sleep 10 && tmux capture-pane -t mole -p
+
+# 7. Enter Developer to see Xcode
+tmux send-keys -t mole Down Down Down Enter
+sleep 5 && tmux capture-pane -t mole -p
+
+# 8. Enter Xcode
+tmux send-keys -t mole Enter
+sleep 5 && tmux capture-pane -t mole -p
+
+# 9. Enter DerivedData to see projects
+tmux send-keys -t mole Enter
+sleep 5 && tmux capture-pane -t mole -p
+
+# 10. Cleanup
+tmux kill-session -t mole
+```
+
+### Key Insights from Exploration
+
+After multi-layer exploration, you will discover:
+
+1. **What projects are using DerivedData** - specific project names
+2. **Which caches are actually large** - uv vs npm vs others
+3. **Age of files** - Mole shows ">3mo", ">7mo", ">1yr" markers
+4. **Specific volumes and their purposes** - Docker project data
+5. **Downloads that can be cleaned** - old dmgs, duplicate files
+
+## Anti-Patterns: What NOT to Delete
+
+**CRITICAL**: The following items are often suggested for cleanup but should NOT be deleted in most cases. They provide significant value that outweighs the space they consume.
+
+### Items to KEEP (Anti-Patterns)
+
+| Item | Size | Why NOT to Delete | Real Impact of Deletion |
+|------|------|-------------------|------------------------|
+| **Xcode DerivedData** | 10+ GB | Build cache saves 10-30 min per full rebuild | Next build takes 10-30 minutes longer |
+| **npm _cacache** | 5+ GB | Downloaded packages cached locally | `npm install` redownloads everything (30min-2hr in China) |
+| **~/.cache/uv** | 10+ GB | Python package cache | Every Python project reinstalls deps from PyPI |
+| **Playwright browsers** | 3-4 GB | Browser binaries for automation testing | Redownload 2GB+ each time (30min-1hr) |
+| **iOS DeviceSupport** | 2-3 GB | Required for device debugging | Redownload from Apple when connecting device |
+| **Docker stopped containers** | <500 MB | May restart anytime with `docker start` | Lose container state, need to recreate |
+| **~/.cache/huggingface** | varies | AI model cache | Redownload large models (hours) |
+| **~/.cache/modelscope** | varies | AI model cache (China) | Same as above |
+| **JetBrains caches** | 1+ GB | IDE indexing and caches | IDE takes 5-10 min to re-index |
+
+### Why This Matters
+
+**The vanity trap**: Showing "Cleaned 50GB!" feels good but:
+- User spends next 2 hours redownloading npm packages
+- Next Xcode build takes 30 minutes instead of 30 seconds
+- AI project fails because models need redownload
+
+**The right mindset**: "I found 50GB of caches. Here's why most of them are actually valuable and should be kept..."
+
+### What IS Actually Safe to Delete
+
+| Item | Why Safe | Impact |
+|------|----------|--------|
+| **Trash** | User already deleted these files | None - user's decision |
+| **Homebrew old versions** | Replaced by newer versions | Rare: can't rollback to old version |
+| **npm _npx** | Temporary npx executions | Minor: npx re-downloads on next use |
+| **Orphaned app remnants** | App already uninstalled | None - app doesn't exist |
+| **Specific unused Docker volumes** | Projects confirmed abandoned | None - if truly abandoned |
+
+## Report Format Requirements
+
+Every cleanup report MUST follow this format with impact analysis:
+
+```markdown
+## Disk Analysis Report
+
+### Classification Legend
+| Symbol | Meaning |
+|--------|---------|
+| 🟢 | **Absolutely Safe** - No negative impact, truly unused |
+| 🟡 | **Trade-off Required** - Useful cache, deletion has cost |
+| 🔴 | **Do Not Delete** - Contains valuable data or actively used |
+
+### Findings
+
+| Item | Size | Classification | What It Is | Impact If Deleted |
+|------|------|----------------|------------|-------------------|
+| Trash | 643 MB | 🟢 | Files you deleted | None |
+| npm _npx | 2.1 GB | 🟢 | Temp npx packages | Minor redownload |
+| npm _cacache | 5 GB | 🟡 | Package cache | 30min-2hr redownload |
+| DerivedData | 10 GB | 🟡 | Xcode build cache | 10-30min rebuild |
+| Docker volumes | 11 GB | 🔴 | Project databases | **DATA LOSS** |
+
+### Recommendation
+Only items marked 🟢 are recommended for cleanup.
+Items marked 🟡 require your judgment based on usage patterns.
+Items marked 🔴 require explicit confirmation per-item.
+```
+
+## High-Quality Report Template
+
+After multi-layer exploration, present findings using this proven template:
+
+```markdown
+## 📊 磁盘空间深度分析报告
+
+**分析日期**: YYYY-MM-DD
+**使用工具**: Mole CLI + 多层目录探索
+**分析原则**: 安全第一，价值优于虚荣
+
+---
+
+### 总览
+
+| 区域 | 总占用 | 关键发现 |
+|------|--------|----------|
+| **Home** | XXX GB | Library占一半(XXX GB) |
+| **App Library** | XXX GB | 与Home/Library重叠统计 |
+| **Applications** | XXX GB | 应用本体 |
+
+---
+
+### 🟢 绝对安全可删除 (约 X.X GB)
+
+| 项目 | 大小 | 位置 | 删除后影响 | 清理命令 |
+|------|------|------|-----------|---------|
+| **废纸篓** | XXX MB | ~/.Trash | 无 - 你已决定删除的文件 | 清空废纸篓 |
+| **npm _npx** | X.X GB | ~/.npm/_npx | 下次 npx 命令重新下载 | `rm -rf ~/.npm/_npx` |
+| **Homebrew 旧版本** | XX MB | /opt/homebrew | 无 - 已被新版本替代 | `brew cleanup --prune=0` |
+
+**废纸篓内容预览**:
+- [列出主要文件]
+
+---
+
+### 🟡 需要你确认的项目
+
+#### 1. [项目名] (X.X GB) - [状态描述]
+
+| 子目录 | 大小 | 最后使用 |
+|--------|------|----------|
+| [子目录1] | X.X GB | >X个月 |
+| [子目录2] | X.X GB | >X个月 |
+
+**问题**: [需要用户回答的问题]
+
+---
+
+#### 2. Downloads 中的旧文件 (X.X GB)
+
+| 文件/目录 | 大小 | 年龄 | 建议 |
+|-----------|------|------|------|
+| [文件1] | X.X GB | - | [建议] |
+| [文件2] | XXX MB | >X个月 | [建议] |
+
+**建议**: 手动检查 Downloads，删除已不需要的文件。
+
+---
+
+#### 3. 停用的 Docker 项目 Volumes
+
+| 项目前缀 | 可能包含的数据 | 需要你确认 |
+|---------|--------------|-----------|
+| `project1_*` | MySQL, Redis | 还在用吗？ |
+| `project2_*` | Postgres | 还在用吗？ |
+
+**注意**: 我不会使用 `docker volume prune -f`，只会在你确认后删除特定项目的 volumes。
+
+---
+
+### 🔴 不建议删除的项目 (有价值的缓存)
+
+| 项目 | 大小 | 为什么要保留 |
+|------|------|-------------|
+| **Xcode DerivedData** | XX GB | [项目名]的编译缓存，删除后下次构建需要X分钟 |
+| **npm _cacache** | X.X GB | 所有下载过的 npm 包，删除后需要重新下载 |
+| **~/.cache/uv** | XX GB | Python 包缓存，重新下载在中国网络下很慢 |
+| [其他有价值的缓存] | X.X GB | [保留原因] |
+
+---
+
+### 📋 其他发现
+
+| 项目 | 大小 | 说明 |
+|------|------|------|
+| **OrbStack/Docker** | XX GB | 正常的 VM/容器占用 |
+| [其他发现] | X.X GB | [说明] |
+
+---
+
+### 推荐操作
+
+**立即可执行** (无需确认):
+```bash
+# 1. 清空废纸篓 (XXX MB)
+# 手动: Finder → 清空废纸篓
+
+# 2. npm _npx (X.X GB)
+rm -rf ~/.npm/_npx
+
+# 3. Homebrew 旧版本 (XX MB)
+brew cleanup --prune=0
+```
+
+**预计释放**: ~X.X GB
+
+---
+
+**需要你确认后执行**:
+
+1. **[项目1]** - [确认问题]
+2. **[项目2]** - [确认问题]
+3. **Docker 项目** - 告诉我哪些项目确定不用了
+```
+
+### Report Quality Checklist
+
+Before presenting the report, verify:
+
+- [ ] Every item has "Impact If Deleted" explanation
+- [ ] 🟢 items are truly safe (Trash, _npx, old versions)
+- [ ] 🟡 items require user decision (age info, usage patterns)
+- [ ] 🔴 items explain WHY they should be kept
+- [ ] Docker volumes listed by project, not blanket prune
+- [ ] Network environment considered (China = slow redownload)
+- [ ] No recommendations to delete useful caches just to inflate numbers
+- [ ] Clear action items with exact commands
 
 ## Step 4: Present Recommendations
 
diff --git a/macos-cleaner/references/mole_integration.md b/macos-cleaner/references/mole_integration.md
index 425f1bd..b1ef25b 100644
--- a/macos-cleaner/references/mole_integration.md
+++ b/macos-cleaner/references/mole_integration.md
@@ -4,69 +4,31 @@ How to integrate [Mole](https://github.com/tw93/Mole) with the macOS Cleaner ski
 
 ## About Mole
 
-**Mole** is a visual macOS disk cleanup tool with a native macOS interface. It provides:
+**Mole** is a command-line interface (CLI) tool for macOS disk cleanup. It provides:
 
-- Visual disk usage analysis
-- One-click cleanup for common targets
-- Safe deletion with preview
-- Native macOS design
+- Interactive terminal-based disk usage analysis
+- Comprehensive cleanup for caches, logs, and application remnants
+- Developer environment cleanup (Docker, npm, pip, Homebrew, etc.)
+- Safe deletion with preview (`--dry-run`)
 
 **Repository**: https://github.com/tw93/Mole
 
-## When to Recommend Mole
+## Critical: TTY Environment Required
 
-Suggest Mole to users in these scenarios:
+**IMPORTANT**: Mole requires a TTY (terminal) environment for interactive commands. When running Mole from automated environments (scripts, Claude Code, CI/CD), use `tmux` to provide a proper TTY.
 
-### 1. User Prefers Visual Interface
+```bash
+# Create tmux session for Mole commands
+tmux new-session -d -s mole -x 120 -y 40
 
-```
-User: "I prefer clicking buttons rather than running commands"
-```
+# Send command to tmux session
+tmux send-keys -t mole 'mo analyze' Enter
 
-**Response**:
-```
-I recommend using Mole alongside these scripts:
+# Capture output
+tmux capture-pane -t mole -p
 
-1. Use the analysis scripts to understand what's using space
-2. Install Mole for visual cleanup: https://github.com/tw93/Mole
-3. Use Mole's GUI to execute cleanup with visual confirmation
-
-Would you like me to guide you through the analysis first?
-```
-
-### 2. Complex Cleanup Needs
-
-```
-User: "I have lots of cache files and don't want to run commands for each"
-```
-
-**Response**:
-```
-Mole can help with batch cleanup. It provides visual categories:
-
-- System caches
-- Application caches
-- Log files
-- Trash
-
-Install Mole and you can review and clean multiple categories at once.
-```
-
-### 3. Ongoing Maintenance
-
-```
-User: "I want to clean my Mac regularly"
-```
-
-**Response**:
-```
-For regular maintenance, I recommend:
-
-1. Keep Mole installed for weekly quick cleanups
-2. Use our analysis scripts monthly for deep analysis
-3. Use safe_delete.py for specific files/folders
-
-This hybrid approach gives you both convenience and precision.
+# Clean up when done
+tmux kill-session -t mole
 ```
 
 ## Installation
@@ -74,231 +36,407 @@ This hybrid approach gives you both convenience and precision.
 ### Check if Mole is Installed
 
 ```bash
-if [ -d "/Applications/Mole.app" ]; then
-  echo "✅ Mole is installed"
-  open -a Mole
-else
-  echo "💡 Mole is not installed"
-  echo "   Install from: https://github.com/tw93/Mole"
-fi
+# Check if mole command exists
+which mo && mo --version
 ```
 
-### Installation Methods
+Expected output:
+```
+/opt/homebrew/bin/mo
+Mole version X.Y.Z
+macOS: XX.X
+Architecture: arm64
+...
+```
 
-**Method 1: Download from GitHub Releases**
+### Installation via Homebrew (Recommended)
 
 ```bash
-# Guide user to:
-# 1. Visit https://github.com/tw93/Mole/releases
-# 2. Download latest .dmg file
-# 3. Open .dmg and drag Mole.app to /Applications
+brew install tw93/tap/mole
 ```
 
-**Method 2: Build from Source** (if user is developer)
+### Version Check and Update
+
+**IMPORTANT**: Always check if Mole is up-to-date before use. The tool updates frequently with bug fixes and new features.
 
 ```bash
-git clone https://github.com/tw93/Mole.git
-cd Mole
-# Follow build instructions in README
+# Check current vs latest version
+brew info tw93/tap/mole | head -5
+
+# If outdated, upgrade
+brew upgrade tw93/tap/mole
 ```
 
-## Workflow Integration
+## Available Commands
 
-### Hybrid Workflow: Scripts + Mole
-
-**Best practice**: Use both tools for their strengths.
-
-#### Step 1: Analysis with Scripts
-
-Run comprehensive analysis:
+**CRITICAL**: Only use `mo --help` to view help. Do NOT append `--help` to other commands as it may cause unexpected behavior.
 
 ```bash
-# System analysis
-python3 scripts/analyze_caches.py
-python3 scripts/analyze_large_files.py --threshold 100
-python3 scripts/find_app_remnants.py
-
-# Developer analysis (if applicable)
-python3 scripts/analyze_dev_env.py
+# View all commands (SAFE - the only help command)
+mo --help
 ```
 
-This gives detailed reports with safety categorization.
+Available commands from `mo --help`:
 
-#### Step 2: Review Findings
+| Command | Description | Safety |
+|---------|-------------|--------|
+| `mo` | Interactive main menu | Requires TTY |
+| `mo clean` | Free up disk space | **DANGEROUS** - deletes files |
+| `mo clean --dry-run` | Preview cleanup (no deletion) | Safe |
+| `mo analyze` | Explore disk usage | Safe (read-only) |
+| `mo status` | Monitor system health | Safe (read-only) |
+| `mo uninstall` | Remove apps completely | **DANGEROUS** |
+| `mo purge` | Remove old project artifacts | **DANGEROUS** |
+| `mo optimize` | Check and maintain system | Caution required |
+| `mo installer` | Find and remove installer files | Caution required |
 
-Present findings to user in readable format (see SKILL.md Step 4).
+## mo analyze vs mo clean --dry-run
 
-#### Step 3: Execute Cleanup
+**CRITICAL**: These are two different tools with different purposes. Use the right tool for the job.
 
-For different types of cleanup:
+### Comparison Table
 
-**Option A: Use Mole** (for batch operations)
-- System caches: Use Mole's "System" category
-- Application caches: Use Mole's "Applications" category
-- Trash: Use Mole's "Trash" feature
+| Aspect | `mo analyze` | `mo clean --dry-run` |
+|--------|--------------|---------------------|
+| **Primary Purpose** | Explore disk usage interactively | Preview cleanup categories |
+| **Use When** | Understanding what consumes space | Ready to see cleanup options |
+| **Interface** | Interactive TUI with tree navigation | Static list output |
+| **Navigation** | Arrow keys to drill into directories | No navigation |
+| **Detail Level** | Full directory breakdown | Only cleanup-eligible items |
+| **Recommended Order** | **Use FIRST** | Use SECOND (after analyze) |
 
-**Option B: Use Scripts** (for precision)
-- Large files: Use `safe_delete.py` with specific paths
-- Application remnants: Use `safe_delete.py` with confirmed orphans
-- Dev environment: Run cleanup commands directly
+### When to Use Each
 
-**Option C: Manual** (for sensitive items)
-- Guide user to review in Finder
-- User deletes manually
+**Use `mo analyze` when:**
+- User asks "What's taking up space?" or "Where is my disk space going?"
+- Need to understand storage consumption patterns
+- Want to explore specific directories interactively
+- Investigating unexpected disk usage
 
-### Example Integrated Session
+**Use `mo clean --dry-run` when:**
+- Already know what's consuming space (after `mo analyze`)
+- User is ready to see cleanup recommendations
+- Need a quick preview of what can be cleaned
+- Preparing to run `mo clean` for actual cleanup
 
-```markdown
-🔍 Analysis Results
+### Workflow Recommendation
 
-I've analyzed your Mac and found:
-- System caches: 45 GB (safe to clean)
-- Large files: 38 GB (need review)
-- App remnants: 8 GB (medium confidence)
-- Docker: 25 GB (requires caution)
-
-Recommended cleanup approach:
-
-1. **Use Mole for safe batch cleanup** (45 GB)
-   - Open Mole
-   - Select "System Caches"
-   - Click "Clean"
-   - This will clear ~/Library/Caches safely
-
-2. **Use scripts for large file review** (38 GB)
-   - I found 20 large files >100MB
-   - Let me show you the list
-   - We'll use safe_delete.py to delete selected files
-
-3. **Manual review for app remnants** (8 GB)
-   - 5 folders for possibly uninstalled apps
-   - Please verify these apps are truly gone:
-     - Adobe Creative Cloud (3 GB)
-     - Old Xcode version (2 GB)
-     - ...
-
-4. **Manual Docker cleanup** (25 GB)
-   - Requires technical review
-   - I'll guide you through checking volumes
-
-Shall we proceed with step 1 using Mole?
+```
+Step 1: mo analyze (understand the problem)
+    ↓
+Step 2: Present findings to user
+    ↓
+Step 3: mo clean --dry-run (show cleanup options)
+    ↓
+Step 4: User confirms cleanup categories
+    ↓
+Step 5: User runs mo clean (actual cleanup)
 ```
 
-## Mole Feature Mapping
+### Common Mistake
 
-Map Mole's features to our script capabilities:
+```bash
+# ❌ WRONG: Jumping straight to cleanup preview
+tmux send-keys -t mole 'mo clean --dry-run' Enter
+# This only shows cleanup-eligible items, not the full picture
 
-| Mole Feature | Script Equivalent | Use Case |
-|--------------|-------------------|----------|
-| System Caches | `analyze_caches.py --user-only` | Quick cache cleanup |
-| Application Caches | `analyze_caches.py` | Per-app cache analysis |
-| Large Files | `analyze_large_files.py` | Find space hogs |
-| Trash | N/A (Finder) | Empty trash |
-| Duplicate Files | Manual `fdupes` | Find duplicates |
+# ✅ CORRECT: Start with disk analysis
+tmux send-keys -t mole 'mo analyze' Enter
+# This shows where ALL disk space is going
+```
 
-**Mole's advantages**:
-- Visual representation
-- One-click cleanup
-- Native macOS integration
+### Interactive TUI Navigation (mo analyze)
 
-**Scripts' advantages**:
-- Developer-specific tools (Docker, npm, pip)
-- Application remnant detection
-- Detailed categorization and safety notes
-- Batch operations with confirmation
+`mo analyze` provides an interactive tree view. Navigate using tmux key sequences:
 
-## Coordinated Cleanup Strategy
+```bash
+# Start analysis
+tmux send-keys -t mole 'mo analyze' Enter
 
-### For Non-Technical Users
+# Wait for scan to complete (5-10 minutes for Home directory!)
+sleep 300  # 5 minutes for large directories
 
-1. **Install Mole** - Primary cleanup tool
-2. **Keep scripts** - For occasional deep analysis
-3. **Workflow**:
-   - Monthly: Run `analyze_caches.py` to see what's using space
-   - Use Mole to execute cleanup
-   - Special cases: Use scripts
+# Capture current view
+tmux capture-pane -t mole -p
 
-### For Technical Users / Developers
+# Navigate down to next item
+tmux send-keys -t mole Down
 
-1. **Keep both** - Mole for quick cleanup, scripts for precision
-2. **Workflow**:
-   - Weekly: Mole for routine cache cleanup
-   - Monthly: Full script analysis for deep cleaning
-   - As needed: Script-based cleanup for dev environment
+# Expand/enter selected directory
+tmux send-keys -t mole Enter
 
-### For Power Users
+# Go back up
+tmux send-keys -t mole Up
 
-1. **Scripts only** - Full control and automation
-2. **Workflow**:
-   - Schedule analysis scripts with cron/launchd
-   - Review reports
-   - Execute cleanup with `safe_delete.py` or direct commands
+# Quit the TUI
+tmux send-keys -t mole 'q'
+```
 
-## Limitations & Complementary Use
+## Safe Analysis Workflow
 
-### What Mole Does Well
+### Step 1: Check Version First
 
-✅ Visual disk usage analysis
-✅ Safe cache cleanup
-✅ User-friendly interface
-✅ Quick routine maintenance
+```bash
+# Always ensure latest version
+brew info tw93/tap/mole | head -3
+```
 
-### What Mole Doesn't Do (Use Scripts For)
+### Step 2: Create TTY Environment
 
-❌ Docker cleanup
-❌ Homebrew cache (command-line only)
-❌ npm/pip cache
-❌ Application remnant detection with confidence levels
-❌ Large .git directory detection
-❌ Development environment analysis
+```bash
+# Start tmux session
+tmux new-session -d -s mole -x 120 -y 40
+```
 
-### Recommended Approach
+### Step 3: Run Analysis (Safe Commands Only)
 
-**Use Mole for**: 80% of routine cleanup needs
-**Use Scripts for**: 20% of specialized/technical cleanup needs
+```bash
+# Disk analysis - SAFE, read-only
+tmux send-keys -t mole 'mo analyze' Enter
+
+# Wait for scan to complete (be patient!)
+sleep 30  # Home directory scanning can take several minutes
+
+# Capture results
+tmux capture-pane -t mole -p
+```
+
+### Step 4: Preview Cleanup (No Actual Deletion)
+
+```bash
+# Preview what would be cleaned - SAFE
+tmux send-keys -t mole 'mo clean --dry-run' Enter
+sleep 10
+tmux capture-pane -t mole -p
+```
+
+### Step 5: User Confirmation Required
+
+**NEVER** execute `mo clean` without explicit user confirmation. Always:
+1. Show the `--dry-run` preview results to user
+2. Wait for user to confirm each category
+3. User runs the actual cleanup command themselves
+
+## Safety Principles
+
+### 0. Value Over Vanity (Most Important)
+
+**Your goal is NOT to maximize cleaned space.** Your goal is to identify truly useless items while preserving valuable caches.
+
+**The vanity trap**: Showing "Cleaned 50GB!" feels impressive but:
+- User spends 2 hours redownloading npm packages
+- Next Xcode build takes 30 minutes instead of 30 seconds
+- AI project fails because models need redownload
+
+**Items that should usually be KEPT:**
+| Item | Why Keep It |
+|------|-------------|
+| Xcode DerivedData | Saves 10-30 min per rebuild |
+| npm _cacache | Avoids re-downloading all packages |
+| ~/.cache/uv | Python package cache |
+| Playwright browsers | Avoids 2GB+ redownload |
+| iOS DeviceSupport | Needed for device debugging |
+| Docker stopped containers | May restart anytime |
+
+**Items that are truly safe to delete:**
+| Item | Why Safe |
+|------|----------|
+| Trash | User already deleted |
+| Homebrew old versions | Replaced by newer |
+| npm _npx | Temporary executions |
+
+### 1. Never Execute Dangerous Commands Automatically
+
+```bash
+# ❌ NEVER do this automatically
+mo clean
+mo uninstall
+mo purge
+docker system prune -a --volumes
+docker volume prune -f
+rm -rf ~/Library/Caches/*
+
+# ✅ ALWAYS use preview/dry-run first
+mo clean --dry-run
+```
+
+### 2. Patience is Critical
+
+- `mo analyze` on large home directories can take 5-10 minutes
+- Do NOT interrupt or skip slow scans
+- Report progress to user regularly
+- Wait for complete results before making decisions
+
+### 3. User Executes Cleanup
+
+After analysis and confirmation:
+```
+Present findings to user, then provide command for them to run:
+
+"Based on the analysis, you can reclaim approximately 30GB.
+To proceed, please run this command in your terminal:
+
+    mo clean
+
+You will be prompted to confirm each category interactively."
+```
+
+## Mole Command Details
+
+### mo analyze
+
+Interactive disk usage explorer. Scans these locations:
+- Home directory (`~`)
+- App Library (`~/Library/Application Support`)
+- Applications (`/Applications`)
+- System Library (`/Library`)
+- Volumes
+
+**Usage in tmux**:
+```bash
+tmux send-keys -t mole 'mo analyze' Enter
+
+# Navigate with arrow keys (send via tmux)
+tmux send-keys -t mole Down  # Move to next item
+tmux send-keys -t mole Enter # Select/expand item
+tmux send-keys -t mole 'q'   # Quit
+```
+
+### mo clean --dry-run
+
+Preview cleanup without deletion. Shows:
+- User essentials (caches, logs, trash)
+- macOS system caches
+- Browser caches
+- Developer tool caches (npm, pip, uv, Homebrew, Docker, etc.)
+
+**Whitelist**: Mole maintains a whitelist of protected patterns. Check with:
+```bash
+mo clean --whitelist
+```
+
+### mo status
+
+System health monitoring (CPU, memory, disk, network). Requires TTY for real-time display.
+
+### mo purge
+
+Cleans old project build artifacts (node_modules, target, venv, etc.) from configured directories.
+
+Check/configure scan paths:
+```bash
+mo purge --paths
+```
+
+## Integration with Claude Code
+
+### Recommended Workflow
+
+1. **Version check**: Ensure Mole is installed and up-to-date
+2. **TTY setup**: Create tmux session for interactive commands
+3. **Analysis**: Run `mo analyze` or `mo clean --dry-run`
+4. **Progress reporting**: Inform user of scan progress
+5. **Present findings**: Show structured results to user
+6. **User confirmation**: Wait for explicit approval
+7. **Provide command**: Give user the command to run themselves
+
+### Example Session
+
+```python
+# 1. Check version
+$ brew info tw93/tap/mole | head -3
+# Output: tw93/tap/mole: stable 1.20.0
+# Installed: 1.13.13 -> needs upgrade
+
+# 2. Upgrade if needed
+$ brew upgrade tw93/tap/mole
+
+# 3. Create tmux session
+$ tmux new-session -d -s mole -x 120 -y 40
+
+# 4. Run dry-run analysis
+$ tmux send-keys -t mole 'mo clean --dry-run' Enter
+
+# 5. Wait and capture output
+$ sleep 15 && tmux capture-pane -t mole -p
+
+# 6. Present to user:
+"""
+📊 Cleanup Preview (dry-run - no files deleted)
+
+User essentials:
+  - User app cache: 16.67 GB
+  - User app logs: 102.3 MB
+  - Trash: 642.9 MB
+
+Developer tools:
+  - uv cache: 9.96 GB
+  - npm cache: (pending)
+  - Docker: (pending)
+
+Total recoverable: ~27 GB
+
+To proceed with cleanup, please run in your terminal:
+    mo clean
+"""
+```
 
 ## Troubleshooting
 
-### Mole Not Opening
+### "device not configured" Error
 
+**Cause**: Command run without TTY environment.
+
+**Solution**: Use tmux:
 ```bash
-# Check if Mole is installed
-ls -l /Applications/Mole.app
-
-# Try opening from command line (see error messages)
-open -a Mole
-
-# If not installed
-echo "Download from: https://github.com/tw93/Mole/releases"
+tmux new-session -d -s mole
+tmux send-keys -t mole 'mo status' Enter
 ```
 
-### Mole Shows Different Numbers than Scripts
+### Scan Stuck on "pending"
 
-**Explanation**:
-- Mole uses different calculation methods
-- Scripts use `du` command (more accurate for directory sizes)
-- Both are valid, differences typically <5%
+**Cause**: Large directories take time to scan.
 
-**Not a problem**: Use Mole's numbers for decisions
+**Solution**: Be patient. Home directory with many files can take 5-10 minutes. Monitor progress:
+```bash
+# Check if still scanning (spinner animation in output)
+tmux capture-pane -t mole -p | tail -10
+```
 
-### Mole Can't Delete Some Caches
+### Non-Interactive Mode Auto-Executes
 
-**Reason**: Permission issues (some caches are protected)
+**WARNING**: Some Mole commands may auto-execute in non-TTY environments without confirmation!
+
+**Solution**: ALWAYS use tmux for ANY Mole command, even help:
+```bash
+# ❌ DANGEROUS - may auto-execute
+mo clean --help  # Might run cleanup instead of showing help!
+
+# ✅ SAFE - use mo --help only
+mo --help  # The ONLY safe help command
+```
+
+### Version Mismatch
+
+**Cause**: Local version outdated.
 
 **Solution**:
-1. Use scripts with sudo for system caches
-2. Or manually delete in Finder with authentication
+```bash
+# Check versions
+brew info tw93/tap/mole
+
+# Upgrade
+brew upgrade tw93/tap/mole
+```
 
 ## Summary
 
-**Best Practice**: Use both tools
-
-- **Mole**: Visual cleanup, routine maintenance, user-friendly
-- **Scripts**: Deep analysis, developer tools, precise control
-
-**Workflow**:
-1. Analyze with scripts (comprehensive report)
-2. Execute with Mole (safe and visual) OR scripts (precise and technical)
-3. Maintain with Mole (weekly/monthly routine)
-
-This combination provides the best user experience for macOS cleanup.
+**Key Points**:
+1. Mole is a **CLI tool**, not a GUI application
+2. Install via `brew install tw93/tap/mole`
+3. **Always check version** before use
+4. **Use tmux** for all interactive commands
+5. `mo --help` is the **ONLY safe help command**
+6. **Never auto-execute** cleanup commands
+7. **Be patient** - scans take time
+8. **User runs cleanup** - provide command, don't execute