feat: add --llm flag and update README with directory support

- Add --llm flag for comprehensive LLM-friendly usage guide
- Update README with directory processing examples
- Add recursive flag documentation
- Update version to 0.1.2
- Comprehensive LLM guide covers all usage patterns, supported languages, and best practices

.claude/settings.local.json

@@ -21,7 +21,8 @@
       "Bash(git reset:*)",
       "Bash(ls:*)",
       "Bash(cp:*)",
-      "Bash(cat:*)"
+      "Bash(cat:*)",
+      "Bash(bt:*)"
     ],
     "deny": []
   }

README.md

@@ -20,6 +20,12 @@ Download the binary for your platform from the [releases page](https://github.co
 # Remove all comments from a file
 shush file.py
 
+# Remove all comments from a directory
+shush src/
+
+# Process directories recursively
+shush src/ --recursive
+
 # Remove only line comments (// or #)
 shush file.js --inline
 
@@ -34,6 +40,9 @@ shush config.lua --backup
 
 # Verbose output
 shush app.go --verbose
+
+# Combine flags for complex operations
+shush src/ --recursive --inline --dry-run --verbose
 ```
 
 ## Supported Languages
@@ -54,13 +63,15 @@ shush app.go --verbose
 ## Options
 
 ```
---inline     Remove only line comments
+--inline       Remove only line comments
---block      Remove only block comments
+--block        Remove only block comments
---dry-run    Show what would be removed without making changes
+-r, --recursive Process directories recursively
---backup     Create backup file before modification
+--dry-run      Show what would be removed without making changes
---verbose    Show detailed output
+--backup       Create backup files before modification
---version    Show version information
+--verbose      Show detailed output
---help       Show help message
+--version      Show version information
+--llm          Show LLM-friendly usage guide
+--help         Show help message
 ```
 
 ## Examples
@@ -86,6 +97,18 @@ shush app.js --inline
 shush app.js --block
 ```
 
+### Directory Processing
+```bash
+# Process all supported files in a directory
+shush src/ --verbose
+
+# Process directories recursively
+shush . --recursive --dry-run
+
+# Process only specific comment types in entire project
+shush . --recursive --inline --backup
+```
+
 ### Backup and Preview
 ```bash
 # Always create backup before modifying

cmd/shush/main.go

@@ -9,7 +9,7 @@ import (
 	"github.com/carlosarraes/shush/internal/types"
 )
 
-var version = "0.1.1"
+var version = "0.1.2"
 
 func main() {
 	var cli types.CLI
@@ -17,6 +17,11 @@ func main() {
 		kong.Description("Remove comments from source code files"),
 		kong.Vars{"version": version})
 
+	if cli.LLM {
+		showLLMGuide()
+		return
+	}
+
 	if cli.Path == "" {
 		fmt.Fprintf(os.Stderr, "Error: path argument is required\n")
 		os.Exit(1)
@@ -33,3 +38,139 @@ func main() {
 		os.Exit(1)
 	}
 }
+
+func showLLMGuide() {
+	fmt.Print(`# Shush CLI - LLM Guide
+
+## Overview
+Shush is a fast comment removal tool for source code files using sed under the hood.
+- **Purpose**: Remove comments from source code while preserving file structure
+- **Key Strength**: Processes individual files or entire directories with recursive support
+- **LLM-Friendly**: Supports dry-run mode with colored preview for safe operation
+
+## Core Commands
+
+### Basic File Processing
+` + "```bash" + `
+shush file.py                    # Remove all comments from single file
+shush file.js --inline          # Remove only line comments (// in JS)
+shush file.c --block            # Remove only block comments (/* */ in C)
+shush script.sh --dry-run       # Preview changes without modification
+shush config.lua --backup       # Create backup before processing
+` + "```" + `
+
+### Directory Processing  
+` + "```bash" + `
+shush src/                       # Process all supported files in directory
+shush . --recursive              # Process current directory recursively
+shush project/ -r --verbose     # Recursive with detailed output
+shush src/ --dry-run --verbose  # Preview recursive changes
+` + "```" + `
+
+### Advanced Usage
+` + "```bash" + `
+# Safe exploration workflow
+shush project/ -r --dry-run --verbose  # 1. Preview all changes
+shush project/ -r --backup             # 2. Process with backups
+
+# Selective comment removal
+shush src/ -r --inline --backup        # Remove only line comments
+shush src/ -r --block --dry-run        # Preview block comment removal
+
+# Combined operations
+shush . --recursive --inline --dry-run --verbose
+` + "```" + `
+
+## Supported Languages & Comment Types
+
+### Line Comments Only
+- **Python**: ` + "`#`" + ` comments
+- **Shell/Bash**: ` + "`#`" + ` comments  
+- **Ruby**: ` + "`#`" + ` comments
+- **Perl**: ` + "`#`" + ` comments
+- **YAML**: ` + "`#`" + ` comments
+- **Lua**: ` + "`--`" + ` comments
+
+### Line + Block Comments
+- **JavaScript/TypeScript**: ` + "`//`" + ` and ` + "`/* */`" + `
+- **Go**: ` + "`//`" + ` and ` + "`/* */`" + `
+- **C/C++**: ` + "`//`" + ` and ` + "`/* */`" + `
+- **Java**: ` + "`//`" + ` and ` + "`/* */`" + `
+
+## Processing Behavior
+
+### Comment Removal Logic
+- **Comment-only lines**: Deleted entirely (preserves line structure)
+- **Inline comments**: Stripped but line kept (e.g., ` + "`code(); // comment`" + ` → ` + "`code();`" + `)
+- **Block comments**: Removed (single-line or multi-line)
+- **Blank lines**: Original empty lines preserved (file structure maintained)
+
+### File Selection
+- **Auto-detection**: Language determined by file extension
+- **Recursive mode**: Scans subdirectories when ` + "`-r/--recursive`" + ` used
+- **Supported only**: Ignores unsupported file types automatically
+- **Error handling**: Continues processing other files if one fails
+
+## Flag Combinations
+
+### Mutually Exclusive
+` + "```bash" + `
+shush file.js --inline --block   # ❌ ERROR: Cannot use both
+` + "```" + `
+
+### Recommended Workflows
+` + "```bash" + `
+# Safe exploration
+shush project/ -r --dry-run --verbose
+
+# Production processing  
+shush project/ -r --backup --verbose
+
+# Selective processing
+shush src/ -r --inline --dry-run    # Preview line comment removal
+shush src/ -r --inline --backup     # Apply line comment removal
+` + "```" + `
+
+## Output Modes
+
+### Dry-Run Preview (--dry-run)
+- **Color-coded display**: Red strikethrough for deleted lines, green for kept
+- **Line numbers**: Easy reference for changes
+- **Summary stats**: Count of lines to be removed/kept
+- **Zero risk**: No files modified
+
+### Verbose Mode (--verbose)  
+- **File discovery**: Shows which files found and processed
+- **Language detection**: Displays detected language per file
+- **Command execution**: Shows sed commands being run
+- **Progress tracking**: File-by-file processing status
+
+### Backup Mode (--backup)
+- **Safety net**: Creates ` + "`.bak`" + ` files before modification
+- **Original preservation**: Backup contains exact original content
+- **Per-file basis**: Each processed file gets individual backup
+
+## Best Practices for LLM Integration
+
+1. **Always start with dry-run** for unknown codebases
+2. **Use recursive + verbose** for comprehensive analysis
+3. **Create backups** before processing important code
+4. **Test on small directories** before full project processing
+5. **Combine flags strategically** (e.g., --recursive --dry-run --verbose)
+
+## Error Scenarios
+- **File not found**: Clear error message, continues with other files
+- **Permission denied**: Skips file, continues processing
+- **Unsupported extension**: Ignores file, shows in verbose mode
+- **Directory not found**: Error message, exits
+- **No supported files**: Error message for directories
+
+## Command Categories by Priority
+1. **Essential**: Basic file processing (` + "`shush file.py`" + `)
+2. **Important**: Directory processing (` + "`shush src/ -r`" + `)
+3. **Safety**: Dry-run and backup modes (` + "`--dry-run`" + `, ` + "`--backup`" + `)
+4. **Selective**: Comment type filtering (` + "`--inline`" + `, ` + "`--block`" + `)
+
+Shush excels at safe, fast comment removal with excellent preview capabilities for confident code processing.
+`)
+}

internal/types/types.go

@@ -10,6 +10,7 @@ type CLI struct {
 	DryRun    bool   `help:"Show what would be removed without making changes"`
 	Backup    bool   `help:"Create backup files before modification"`
 	Verbose   bool   `help:"Show detailed output"`
+	LLM       bool   `help:"Show LLM-friendly usage guide"`
 	Version   kong.VersionFlag `help:"Show version information"`
 }