Add CLI --help examples and scheduling documentation

README.md

@@ -121,6 +121,7 @@ Each app has detailed documentation in its own directory:
 - [`mac-cache-cleaner/README.md`](mac-cache-cleaner/README.md) - Full mac-cache-cleaner docs
 - [`dev-cache/README.md`](dev-cache/README.md) - Full dev-cache docs
 - [`git-cleaner/README.md`](git-cleaner/README.md) - Full git-cleaner docs
+- [`docs/scheduling.md`](docs/scheduling.md) - cron and launchd scheduling examples
 
 ## Development
 

dev-cache/main.go

@@ -37,6 +37,19 @@ var (
 	flagLangs  = flag.String("languages", "", "Comma-separated list of languages to scan")
 )
 
+func init() {
+	flag.Usage = func() {
+		out := flag.CommandLine.Output()
+		fmt.Fprintf(out, "Usage: dev-cache [flags]\n\nFlags:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(out, "\nExamples:\n")
+		fmt.Fprintf(out, "  dev-cache                        # Scan default path from config\n")
+		fmt.Fprintf(out, "  dev-cache --scan ~/projects      # Scan specific directory\n")
+		fmt.Fprintf(out, "  dev-cache --clean --yes          # Clean without confirmation\n")
+		fmt.Fprintf(out, "  dev-cache --languages node,rust  # Only node and rust caches\n")
+	}
+}
+
 // ----- Config types -----
 
 type Config struct {

docs/scheduling.md

@@ -0,0 +1,70 @@
+# Scheduled Runs
+
+Use scheduled jobs to run cache cleanup during low-usage hours.
+
+## cron (Linux/macOS)
+
+Weekly at 3:00 AM every Sunday:
+
+```cron
+0 3 * * 0 /usr/local/bin/dev-cache --scan ~/src --clean --yes >> ~/cache-cleaner.log 2>&1
+0 3 * * 0 /usr/local/bin/git-cleaner --scan ~/src --clean >> ~/cache-cleaner.log 2>&1
+0 3 * * 0 /usr/local/bin/mac-cache-cleaner --clean >> ~/cache-cleaner.log 2>&1
+```
+
+Notes:
+- Update binary paths based on your install location (`which dev-cache`, `which git-cleaner`, `which mac-cache-cleaner`).
+- Keep log redirection enabled for troubleshooting.
+
+## launchd (macOS)
+
+Create `~/Library/LaunchAgents/com.cache-cleaner.weekly.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.cache-cleaner.weekly</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/mac-cache-cleaner</string>
+    <string>--clean</string>
+  </array>
+
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Weekday</key>
+    <integer>1</integer>
+    <key>Hour</key>
+    <integer>3</integer>
+    <key>Minute</key>
+    <integer>0</integer>
+  </dict>
+
+  <key>StandardOutPath</key>
+  <string>/Users/YOUR_USER/cache-cleaner.log</string>
+  <key>StandardErrorPath</key>
+  <string>/Users/YOUR_USER/cache-cleaner.log</string>
+</dict>
+</plist>
+```
+
+Load and start:
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.cache-cleaner.weekly.plist
+launchctl start com.cache-cleaner.weekly
+```
+
+Unload:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.cache-cleaner.weekly.plist
+```
+
+## Homebrew services
+
+`brew services` is best for long-running daemons, not periodic CLI jobs. For periodic cleanup, prefer `cron` or `launchd`.

git-cleaner/main.go

@@ -27,6 +27,17 @@ var (
 	flagClean = flag.Bool("clean", false, "Run git gc in each repository and show disk savings")
 )
 
+func init() {
+	flag.Usage = func() {
+		out := flag.CommandLine.Output()
+		fmt.Fprintf(out, "Usage: git-cleaner --scan <directory> [flags]\n\nFlags:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(out, "\nExamples:\n")
+		fmt.Fprintf(out, "  git-cleaner --scan ~/src         # Scan for .git directories\n")
+		fmt.Fprintf(out, "  git-cleaner --scan ~/src --clean # Optimize with git gc\n")
+	}
+}
+
 // ----- Finding types -----
 
 type Finding struct {

mac-cache-cleaner/main.go

@@ -65,6 +65,18 @@ var (
 	flagDetails     = flag.Bool("details", false, "Show detailed per-directory information")
 )
 
+func init() {
+	flag.Usage = func() {
+		out := flag.CommandLine.Output()
+		fmt.Fprintf(out, "Usage: mac-cache-cleaner [flags]\n\nFlags:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(out, "\nExamples:\n")
+		fmt.Fprintf(out, "  mac-cache-cleaner                         # Scan all targets (dry-run)\n")
+		fmt.Fprintf(out, "  mac-cache-cleaner --clean                 # Run cleanup commands\n")
+		fmt.Fprintf(out, "  mac-cache-cleaner --targets docker,npm    # Specific targets only\n")
+	}
+}
+
 // ----- Config types -----
 
 type Config struct {