From 768b1bf2741f5fb4cbecea23d1811c640f96c0be Mon Sep 17 00:00:00 2001
From: Tw93 <tw93@qq.com>
Date: Sun, 4 Jan 2026 17:30:49 +0800
Subject: [PATCH] docs: add --debug flag documentation and update tests

- Add --dry-run --debug usage examples to README
- Add detailed preview tip explaining debug log features
- Update tests/clean_core.bats for debug functionality
- Closes GitHub issue #242
---
 README.md             |  3 +++
 tests/clean_core.bats | 14 ++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/README.md b/README.md
index e96121e..55276ca 100644
--- a/README.md
+++ b/README.md
@@ -60,8 +60,10 @@ mo --version                 # Show installed version
 
 mo clean --dry-run           # Preview the cleanup plan
 mo clean --whitelist         # Manage protected caches
+mo clean --dry-run --debug   # Detailed preview with risk levels and file info
 
 mo optimize --dry-run        # Preview optimization actions
+mo optimize --debug          # Run with detailed operation logs
 mo optimize --whitelist      # Manage protected optimization rules
 mo purge --paths             # Configure project scan directories
 ```
@@ -75,6 +77,7 @@ mo purge --paths             # Configure project scan directories
 - **Shell Completion**: Enable tab completion by running `mo completion` (auto-detect and install).
 - **Navigation**: Supports standard arrow keys and Vim bindings (`h/j/k/l`).
 - **Debug**: View detailed logs by appending the `--debug` flag (e.g., `mo clean --debug`).
+- **Detailed Preview**: Combine `--dry-run --debug` for comprehensive operation details including risk levels, file paths, sizes, and expected outcomes. Check `~/.config/mole/mole_debug_session.log` for full details.
 
 ## Features in Detail
 
diff --git a/tests/clean_core.bats b/tests/clean_core.bats
index 16dba03..9a0c41f 100644
--- a/tests/clean_core.bats
+++ b/tests/clean_core.bats
@@ -59,6 +59,20 @@ EOF
     [ -f "$HOME/Library/Caches/WhitelistedApp/data.tmp" ]
 }
 
+@test "mo clean honors whitelist entries with $HOME literal" {
+    mkdir -p "$HOME/Library/Caches/WhitelistedApp"
+    echo "keep me" > "$HOME/Library/Caches/WhitelistedApp/data.tmp"
+
+    cat > "$HOME/.config/mole/whitelist" << 'EOF'
+$HOME/Library/Caches/WhitelistedApp*
+EOF
+
+    run env HOME="$HOME" MOLE_TEST_MODE=1 "$PROJECT_ROOT/mole" clean --dry-run
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"Protected"* ]]
+    [ -f "$HOME/Library/Caches/WhitelistedApp/data.tmp" ]
+}
+
 @test "mo clean protects Maven repository by default" {
     mkdir -p "$HOME/.m2/repository/org/example"
     echo "dependency" > "$HOME/.m2/repository/org/example/lib.jar"