From 6ed5e80d0acde2f96cddbb5b0779e19a324b4bcc Mon Sep 17 00:00:00 2001
From: glitchySid <siddheshmhatrecodes1808@gmail.com>
Date: Wed, 7 Jan 2026 22:22:18 +0530
Subject: [PATCH] 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     | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/USAGE.md | 52 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 104 insertions(+)

diff --git a/README.md b/README.md
index 816adef..31b5d49 100644
--- a/README.md
+++ b/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 |
diff --git a/docs/USAGE.md b/docs/USAGE.md
index c95c87a..c8cc64c 100644
--- a/docs/USAGE.md
+++ b/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.