docs: update documentation for custom path support

- Add PATH argument to command-line options tables
- Add Custom Path Organization section with examples
- Update basic usage examples to include path usage
- Add combined options examples with custom paths
- Add Custom Path Support section to README
- Document path validation, normalization, and use cases

Documentation now fully covers the new custom path functionality
with clear examples and explanations.

README.md

@@ -60,9 +60,18 @@ On first run, NoEntropy will guide you through an interactive setup to configure
 # Organize your downloads folder
 ./noentropy
 
+# Organize a specific directory (current directory)
+./noentropy .
+
+# Organize a specific directory (absolute path)
+./noentropy /path/to/folder
+
 # Preview changes without moving files
 ./noentropy --dry-run
 
+# Preview organization of current directory
+./noentropy . --dry-run
+
 # Undo the last organization
 ./noentropy --undo
 ```
@@ -109,6 +118,48 @@ Files moved: 47, Errors: 0
 Done!
 ```
 
+## Custom Path Support
+
+NoEntropy now supports organizing any directory, not just your configured Downloads folder!
+
+### Organize Any Directory
+
+```bash
+# Organize current directory
+./noentropy .
+
+# Organize specific folder
+./noentropy /path/to/folder
+
+# Organize with relative path
+./noentropy ./subfolder
+```
+
+### Features
+
+- **Path Validation**: Ensures the directory exists and is accessible
+- **Path Normalization**: Resolves `.`, `..`, and symlinks for consistency
+- **Full Compatibility**: Works with all existing options (`--dry-run`, `--recursive`, etc.)
+- **Security**: Prevents path traversal attacks and invalid paths
+
+### Use Cases
+
+- Quickly organize project directories
+- Clean up specific folders without changing configuration
+- Test organization on different directories
+- Organize documents, downloads, or any file collection
+
+```bash
+# Preview organization of current directory
+./noentropy . --dry-run
+
+# Organize project folder recursively
+./noentropy ./my-project --recursive
+
+# Undo organization in specific directory
+./noentropy /path/to/folder --undo
+```
+
 ## Use Cases
 
 - 📂 Organize a messy Downloads folder
@@ -153,6 +204,7 @@ All file moves are tracked for 30 days with full conflict detection and safety f
 
 | Option | Short | Description |
 |--------|-------|-------------|
+| `[PATH]` | - | Path to organize (defaults to configured download folder) |
 | `--dry-run` | `-d` | Preview changes without moving files |
 | `--max-concurrent` | `-m` | Maximum concurrent API requests (default: 5) |
 | `--recursive` | - | Recursively search files in subdirectories |

docs/USAGE.md

@@ -23,6 +23,7 @@ NoEntropy supports several command-line flags to customize its behavior:
 
 | Option | Short | Default | Description |
 |--------|-------|---------|-------------|
+| `[PATH]` | - | - | Path to organize (defaults to configured download folder) |
 | `--dry-run` | `-d` | `false` | Preview changes without moving files |
 | `--max-concurrent` | `-m` | `5` | Maximum concurrent API requests |
 | `--recursive` | - | `false` | Recursively search files in subdirectories |
@@ -32,6 +33,35 @@ NoEntropy supports several command-line flags to customize its behavior:
 
 ## Usage Examples
 
+### Custom Path Organization
+
+Organize any directory instead of the configured download folder:
+
+```bash
+./noentropy /path/to/folder
+```
+
+**Usage with current directory:**
+```bash
+./noentropy .
+```
+
+**Usage with relative path:**
+```bash
+./noentropy ./subfolder
+```
+
+**When to use:**
+- Organize directories other than your Downloads folder
+- Quickly organize the current working directory
+- Test organization on specific folders before applying to Downloads
+- Organize project directories, documents, or other file collections
+
+**Features:**
+- Path validation ensures the directory exists and is accessible
+- Path normalization resolves `.`, `..`, and symlinks for consistency
+- Works with all other options (`--dry-run`, `--recursive`, etc.)
+
 ### Dry-Run Mode
 
 Preview what NoEntropy would do without actually moving any files:
@@ -102,6 +132,28 @@ You can combine multiple options:
 ./noentropy --recursive --max-concurrent 10
 ```
 
+**Custom path combinations:**
+
+```bash
+# Preview organization of current directory
+./noentropy . --dry-run
+```
+
+```bash
+# Organize specific folder recursively
+./noentropy /path/to/folder --recursive
+```
+
+```bash
+# Organize current directory with custom concurrency
+./noentropy . --max-concurrent 10
+```
+
+```bash
+# Undo organization in specific directory
+./noentropy /path/to/folder --undo
+```
+
 ## Undo Operations
 
 NoEntropy tracks all file moves and allows you to undo them.