docs: restructure documentation into organized files

Split the 630-line README.md into focused, well-organized documentation: - README.md: Concise overview with quick start and links - docs/INSTALLATION.md: Installation instructions and setup - docs/CONFIGURATION.md: Configuration options and custom categories - docs/USAGE.md: Command-line options and usage examples - docs/HOW_IT_WORKS.md: Architecture and internal processes - docs/TROUBLESHOOTING.md: Common issues and solutions - docs/DEVELOPMENT.md: Project structure and development guide - docs/CONTRIBUTING.md: Contribution guidelines and standards Benefits: - Main README is now clean and welcoming (~150 lines vs 630) - Each doc has a clear, focused purpose - Better navigation with cross-linking between docs - Follows GitHub best practices with docs/ directory - Easier to maintain and update specific sections
2026-01-02 00:55:29 +05:30
parent 0eedb61455
commit d4e8dbc6b3
8 changed files with 2621 additions and 518 deletions
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -0,0 +1,202 @@
+# Configuration Guide
+
+NoEntropy uses a simple TOML configuration file to store your API key, download folder path, and custom categories.
+
+## Configuration File Location
+
+NoEntropy stores configuration in `~/.config/noentropy/config.toml` following XDG Base Directory specifications.
+
+**Platform-specific paths:**
+- **Linux/macOS**: `~/.config/noentropy/config.toml`
+- **Windows**: `C:\Users\<username>\AppData\Roaming\noentropy\config.toml`
+
+## Basic Configuration
+
+### Minimal Configuration
+
+The minimum required configuration includes just your API key and download folder:
+
+```toml
+api_key = "AIzaSyDTEhAq414SHY094A5oy5lxNA0vhbY1O3k"
+download_folder = "/home/user/Downloads"
+```
+
+### Full Configuration with Custom Categories
+
+```toml
+api_key = "AIzaSyDTEhAq414SHY094A5oy5lxNA0vhbY1O3k"
+download_folder = "/home/user/Downloads"
+
+# Optional: Custom categories for file organization
+categories = ["Work", "Personal", "School", "Projects", "Bills", "Media", "Misc"]
+```
+
+## Configuration Options
+
+| Setting | Description | Example | Required |
+|---------|-------------|---------|----------|
+| `api_key` | Your Google Gemini API key | `AIzaSy...` | Yes |
+| `download_folder` | Path to folder to organize | `/home/user/Downloads` | Yes |
+| `categories` | Custom categories for organization | `["Work", "Personal", "School"]` | No |
+
+## Getting a Gemini API Key
+
+1. Visit [Google AI Studio](https://ai.google.dev/)
+2. Sign in with your Google account
+3. Create a new API key
+4. Copy the key to your configuration file
+
+**Important**: Keep your API key secure and never commit it to version control.
+
+## Custom Categories
+
+NoEntropy allows you to define your own custom categories instead of using the default ones. This is perfect for organizing files based on your specific workflow or needs.
+
+### Default Categories
+
+If you don't specify custom categories, NoEntropy uses these defaults:
+- **Images** - PNG, JPG, GIF, SVG, etc.
+- **Documents** - PDF, DOC, DOCX, TXT, MD, etc.
+- **Installers** - EXE, DMG, APP, PKG, etc.
+- **Music** - MP3, WAV, FLAC, M4A, etc.
+- **Archives** - ZIP, TAR, RAR, 7Z, etc.
+- **Code** - Source code and configuration files
+- **Misc** - Everything else
+
+### Using Custom Categories
+
+To use custom categories, add a `categories` array to your `config.toml`:
+
+```toml
+api_key = "your_api_key_here"
+download_folder = "/home/user/Downloads"
+categories = ["Work", "Personal", "School", "Projects", "Bills", "Media", "Misc"]
+```
+
+### Category Examples by Use Case
+
+#### For Students
+```toml
+categories = ["Courses", "Assignments", "Research", "Personal", "Textbooks", "Media", "Misc"]
+```
+
+#### For Professionals
+```toml
+categories = ["Client Work", "Internal", "Invoices", "Contracts", "Marketing", "Resources", "Misc"]
+```
+
+#### For Creatives
+```toml
+categories = ["Projects", "Assets", "References", "Client Files", "Portfolio", "Tools", "Misc"]
+```
+
+#### For Personal Use
+```toml
+categories = ["Family", "Finance", "Health", "Home", "Travel", "Hobbies", "Misc"]
+```
+
+### Tips for Effective Custom Categories
+
+1. **Keep it simple** - Use 5-10 categories for best results
+2. **Be specific** - More descriptive names help the AI understand better
+3. **Include "Misc"** - Always have a catch-all category for unclear files
+4. **Think workflow** - Organize based on how you actually use files
+5. **Test first** - Use `--dry-run` to preview categorization before committing
+
+### How Custom Categories Work
+
+When you define custom categories:
+1. NoEntropy sends your file list to the Gemini AI
+2. The AI is instructed to categorize files into your custom categories
+3. Files are organized into folders matching your category names
+4. Sub-folders are still created automatically for better organization
+
+**Example Output with Custom Categories:**
+```
+Downloads/
+├── Work/
+│   ├── Reports/
+│   │   └── Q4-Report.pdf
+│   └── Presentations/
+│       └── Client-Deck.pptx
+├── Personal/
+│   ├── Photos/
+│   │   └── vacation.jpg
+│   └── Documents/
+│       └── resume.pdf
+└── School/
+    ├── Assignments/
+    │   └── homework.docx
+    └── Notes/
+        └── lecture-notes.pdf
+```
+
+## Interactive Setup
+
+If configuration is missing, NoEntropy will prompt you interactively:
+
+```bash
+$ ./noentropy
+
+NoEntropy Configuration Setup
+=============================
+
+API key not found. Please enter your Google Gemini API key:
+> AIzaSy...
+
+Download folder not found. Please enter the path to organize:
+(Default: /home/user/Downloads)
+> /home/user/Downloads
+
+Configuration saved to ~/.config/noentropy/config.toml
+```
+
+Configuration is automatically saved after interactive setup.
+
+## Changing Configuration
+
+### Changing API Key
+
+To change your Gemini API key, use the `--change-key` flag:
+
+```bash
+./noentropy --change-key
+```
+
+Or manually edit `~/.config/noentropy/config.toml` and update the `api_key` value.
+
+### Changing Download Folder
+
+Edit your configuration file and update the `download_folder` value:
+
+```toml
+download_folder = "/path/to/new/folder"
+```
+
+### Adding or Modifying Categories
+
+Edit your configuration file and add or modify the `categories` array:
+
+```toml
+categories = ["Category1", "Category2", "Category3"]
+```
+
+To remove custom categories and use defaults, simply delete the `categories` line from your config file.
+
+## Configuration Best Practices
+
+1. **Backup your config** - Keep a copy of your configuration, especially if you have custom categories
+2. **Use absolute paths** - Always specify absolute paths for `download_folder`
+3. **Test changes** - Use `--dry-run` after changing categories to preview results
+4. **Keep API key secure** - Don't share or commit your API key
+5. **Regular reviews** - Periodically review if your custom categories still match your needs
+
+## Next Steps
+
+- [Usage Guide](USAGE.md) - Learn how to use NoEntropy
+- [How It Works](HOW_IT_WORKS.md) - Understand the organization process
+- [Troubleshooting](TROUBLESHOOTING.md) - Solve common configuration issues
+
+---
+
+[Back to Main README](../README.md)
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,494 @@
+# Contributing to NoEntropy
+
+Thank you for considering contributing to NoEntropy! This guide will help you get started with contributing to the project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How Can I Contribute?](#how-can-i-contribute)
+- [Development Setup](#development-setup)
+- [Pull Request Process](#pull-request-process)
+- [Coding Standards](#coding-standards)
+- [Commit Message Guidelines](#commit-message-guidelines)
+- [Testing Guidelines](#testing-guidelines)
+- [Documentation Guidelines](#documentation-guidelines)
+
+## Code of Conduct
+
+### Our Pledge
+
+We are committed to providing a welcoming and inspiring community for everyone. Please be respectful and constructive in your interactions.
+
+### Expected Behavior
+
+- Be respectful and inclusive
+- Accept constructive criticism gracefully
+- Focus on what's best for the community
+- Show empathy towards other community members
+
+### Unacceptable Behavior
+
+- Harassment or discriminatory language
+- Trolling or insulting comments
+- Public or private harassment
+- Publishing others' private information
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Before creating bug reports, please check existing issues to avoid duplicates.
+
+**How to submit a good bug report:**
+
+1. **Use a clear and descriptive title**
+2. **Describe the exact steps to reproduce the problem**
+3. **Provide specific examples**
+4. **Describe the behavior you observed and what you expected**
+5. **Include system information**:
+   - OS and version
+   - Rust version
+   - NoEntropy version
+
+**Bug report template:**
+
+```markdown
+**Description**
+A clear description of the bug.
+
+**Steps to Reproduce**
+1. Run command '...'
+2. See error '...'
+
+**Expected Behavior**
+What you expected to happen.
+
+**Actual Behavior**
+What actually happened.
+
+**System Information**
+- OS: [e.g., Ubuntu 22.04]
+- Rust version: [e.g., 1.75.0]
+- NoEntropy version: [e.g., 1.0.0]
+
+**Additional Context**
+Any other relevant information.
+```
+
+### Suggesting Enhancements
+
+Enhancement suggestions are welcome! Please provide:
+
+1. **Clear use case**: Explain why this enhancement would be useful
+2. **Detailed description**: Describe how it should work
+3. **Examples**: Provide examples of how it would be used
+4. **Alternatives considered**: Mention alternative solutions you've considered
+
+**Enhancement template:**
+
+```markdown
+**Feature Description**
+A clear description of the feature.
+
+**Use Case**
+Why this feature would be useful.
+
+**Proposed Solution**
+How you think it should work.
+
+**Alternatives Considered**
+Other solutions you've thought about.
+
+**Additional Context**
+Any other relevant information.
+```
+
+### Contributing Code
+
+We love code contributions! Here's how to get started:
+
+1. **Fork the repository**
+2. **Create a feature branch**
+3. **Make your changes**
+4. **Test thoroughly**
+5. **Submit a pull request**
+
+See [Development Setup](#development-setup) below for details.
+
+### Improving Documentation
+
+Documentation improvements are highly valued:
+
+- Fix typos or unclear explanations
+- Add examples or clarifications
+- Improve code comments
+- Write tutorials or guides
+
+### Helping Others
+
+- Answer questions in GitHub Issues
+- Participate in discussions
+- Help review pull requests
+- Share your use cases and experiences
+
+## Development Setup
+
+### Prerequisites
+
+- **Rust 2024 Edition** or later
+- **Git** for version control
+- **Google Gemini API Key** for testing (get one at [https://ai.google.dev/](https://ai.google.dev/))
+
+### Setup Steps
+
+1. **Fork and clone the repository**:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/noentropy.git
+   cd noentropy
+   ```
+
+2. **Add upstream remote**:
+   ```bash
+   git remote add upstream https://github.com/glitchySid/noentropy.git
+   ```
+
+3. **Build the project**:
+   ```bash
+   cargo build
+   ```
+
+4. **Run tests**:
+   ```bash
+   cargo test
+   ```
+
+5. **Set up configuration** (for testing):
+   ```bash
+   cp config.example.toml ~/.config/noentropy/config.toml
+   # Edit config.toml with your API key and test folder
+   ```
+
+6. **Verify installation**:
+   ```bash
+   cargo run -- --dry-run
+   ```
+
+### Keeping Your Fork Updated
+
+```bash
+git fetch upstream
+git checkout main
+git merge upstream/main
+git push origin main
+```
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Ensure tests pass**:
+   ```bash
+   cargo test
+   ```
+
+2. **Run code formatter**:
+   ```bash
+   cargo fmt
+   ```
+
+3. **Run linter**:
+   ```bash
+   cargo clippy
+   ```
+
+4. **Test manually** with various scenarios
+
+5. **Update documentation** if needed
+
+### Creating a Pull Request
+
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** and commit:
+   ```bash
+   git add .
+   git commit -m "Add feature: description"
+   ```
+
+3. **Push to your fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+4. **Open a pull request** on GitHub
+
+5. **Fill out the PR template** with:
+   - Description of changes
+   - Related issue number (if applicable)
+   - Testing performed
+   - Screenshots (if UI changes)
+
+### PR Review Process
+
+1. **Automated checks** will run (tests, linting, formatting)
+2. **Maintainers will review** your code
+3. **Address feedback** by making additional commits
+4. **Once approved**, your PR will be merged
+
+### PR Guidelines
+
+- **Keep PRs focused**: One feature or fix per PR
+- **Write clear descriptions**: Explain what and why
+- **Reference issues**: Use "Fixes #123" to link issues
+- **Be responsive**: Respond to review feedback promptly
+- **Be patient**: Reviews may take time
+
+## Coding Standards
+
+### Rust Style Guide
+
+Follow the official [Rust Style Guide](https://doc.rust-lang.org/nightly/style-guide/):
+
+- Use `cargo fmt` to format code
+- Use `cargo clippy` to catch common mistakes
+- Follow Rust naming conventions:
+  - `snake_case` for functions and variables
+  - `PascalCase` for types and traits
+  - `SCREAMING_SNAKE_CASE` for constants
+
+### Code Organization
+
+- Keep functions focused and small
+- Group related functionality in modules
+- Use meaningful variable and function names
+- Avoid deep nesting (prefer early returns)
+
+### Error Handling
+
+- Use `Result` types for fallible operations
+- Provide meaningful error messages
+- Don't panic in library code
+- Use `?` operator for error propagation
+
+### Comments and Documentation
+
+- Add doc comments (`///`) for public APIs
+- Explain "why" not "what" in comments
+- Keep comments up-to-date with code changes
+- Use examples in doc comments when helpful
+
+### Example
+
+```rust
+/// Calculates the destination path for a file based on its category.
+///
+/// # Arguments
+///
+/// * `file_path` - The original file path
+/// * `category` - The category to organize into
+/// * `subfolder` - Optional subfolder within category
+///
+/// # Examples
+///
+/// ```
+/// let dest = calculate_destination("/downloads/file.txt", "Documents", Some("Work"));
+/// assert_eq!(dest, "/downloads/Documents/Work/file.txt");
+/// ```
+///
+/// # Errors
+///
+/// Returns an error if the path cannot be constructed.
+pub fn calculate_destination(
+    file_path: &Path,
+    category: &str,
+    subfolder: Option<&str>
+) -> Result<PathBuf, Error> {
+    // Implementation
+}
+```
+
+## Commit Message Guidelines
+
+### Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Type
+
+- **feat**: New feature
+- **fix**: Bug fix
+- **docs**: Documentation changes
+- **style**: Code style changes (formatting, etc.)
+- **refactor**: Code refactoring
+- **test**: Adding or updating tests
+- **chore**: Maintenance tasks
+
+### Examples
+
+**Good commit messages:**
+
+```
+feat(cli): add recursive flag for subdirectory scanning
+
+Adds --recursive flag to scan and organize files in subdirectories.
+This is useful when downloads are already partially organized.
+
+Fixes #42
+```
+
+```
+fix(cache): prevent cache corruption on interrupted writes
+
+Use atomic writes to ensure cache file is not corrupted if
+process is interrupted during save operation.
+```
+
+```
+docs: update configuration guide with new examples
+
+Add examples for different user types (students, professionals).
+Clarify custom category usage.
+```
+
+**Bad commit messages:**
+
+```
+fix stuff
+```
+
+```
+WIP
+```
+
+```
+more changes
+```
+
+### Tips
+
+- Use present tense ("add feature" not "added feature")
+- Be specific and descriptive
+- Reference issues and PRs when relevant
+- Keep subject line under 72 characters
+- Separate subject from body with blank line
+
+## Testing Guidelines
+
+### Writing Tests
+
+- Write tests for new functionality
+- Test both success and error cases
+- Use descriptive test names
+- Keep tests focused and independent
+
+### Test Structure
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse_valid_config() {
+        // Arrange
+        let config_str = r#"
+            api_key = "test_key"
+            download_folder = "/tmp/test"
+        "#;
+
+        // Act
+        let result = parse_config(config_str);
+
+        // Assert
+        assert!(result.is_ok());
+        let config = result.unwrap();
+        assert_eq!(config.api_key, "test_key");
+        assert_eq!(config.download_folder, "/tmp/test");
+    }
+
+    #[test]
+    fn test_parse_invalid_config() {
+        let config_str = "invalid toml";
+        let result = parse_config(config_str);
+        assert!(result.is_err());
+    }
+}
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+cargo test
+
+# Run specific test
+cargo test test_name
+
+# Run with output
+cargo test -- --nocapture
+
+# Run tests in specific module
+cargo test module_name::
+```
+
+## Documentation Guidelines
+
+### Code Documentation
+
+- Document all public APIs
+- Include examples in doc comments
+- Explain parameters and return values
+- Document errors that can occur
+
+### User Documentation
+
+When updating user-facing docs:
+
+- Keep language clear and simple
+- Provide examples
+- Include screenshots for UI changes
+- Update all relevant docs
+
+### Documentation Files
+
+- **README.md**: Project overview and quick start
+- **docs/INSTALLATION.md**: Installation instructions
+- **docs/CONFIGURATION.md**: Configuration guide
+- **docs/USAGE.md**: Usage examples and options
+- **docs/HOW_IT_WORKS.md**: Architecture and internals
+- **docs/TROUBLESHOOTING.md**: Common issues and solutions
+- **docs/DEVELOPMENT.md**: Development guide
+- **docs/CONTRIBUTING.md**: This file
+
+## Questions?
+
+- Check [existing documentation](../README.md)
+- Search [GitHub Issues](https://github.com/glitchySid/noentropy/issues)
+- Ask in [GitHub Discussions](https://github.com/glitchySid/noentropy/discussions)
+- Contact maintainers
+
+## Recognition
+
+Contributors will be recognized in:
+- GitHub contributors list
+- Release notes (for significant contributions)
+- Project documentation (for major features)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to NoEntropy!
+
+[Back to Main README](../README.md) | [Development Guide](DEVELOPMENT.md)
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -0,0 +1,502 @@
+# Development Guide
+
+This guide is for developers who want to understand NoEntropy's codebase, contribute features, or extend functionality.
+
+## Project Structure
+
+NoEntropy follows a clean modular architecture for better maintainability and testability:
+
+```
+noentropy/
+├── .github/
+│   └── workflows/
+│       └── rust.yml              # CI/CD workflow
+├── docs/                         # Documentation files
+│   ├── INSTALLATION.md
+│   ├── CONFIGURATION.md
+│   ├── USAGE.md
+│   ├── HOW_IT_WORKS.md
+│   ├── TROUBLESHOOTING.md
+│   ├── DEVELOPMENT.md           # This file
+│   └── CONTRIBUTING.md
+├── src/
+│   ├── cli/
+│   │   ├── mod.rs                # CLI module exports
+│   │   ├── args.rs               # Command-line argument definitions
+│   │   └── orchestrator.rs       # Organization & undo orchestration
+│   ├── files/
+│   │   ├── mod.rs                # File module exports
+│   │   ├── batch.rs              # File batch processing
+│   │   ├── detector.rs           # File type detection
+│   │   ├── mover.rs              # File moving operations
+│   │   └── undo.rs               # Undo file operations
+│   ├── gemini/
+│   │   ├── mod.rs                # Gemini API module exports
+│   │   ├── client.rs             # Gemini API client
+│   │   ├── errors.rs             # Gemini error handling
+│   │   ├── prompt.rs             # AI prompt construction
+│   │   └── types.rs              # Gemini API types
+│   ├── models/
+│   │   ├── mod.rs                # Data models exports
+│   │   ├── metadata.rs           # File metadata structures
+│   │   ├── move_record.rs        # File move tracking
+│   │   └── organization.rs       # Organization plan structures
+│   ├── settings/
+│   │   ├── mod.rs                # Settings module exports
+│   │   ├── config.rs             # Configuration management
+│   │   ├── prompt.rs             # Interactive configuration prompts
+│   │   └── tests.rs              # Settings tests
+│   ├── storage/
+│   │   ├── mod.rs                # Storage module exports
+│   │   ├── cache.rs              # Caching system
+│   │   └── undo_log.rs           # Undo log management
+│   ├── main.rs                   # Application entry point
+│   └── lib.rs                    # Library exports
+├── Cargo.toml                    # Dependencies and project metadata
+├── Cargo.lock                    # Dependency lock file
+├── config.example.toml           # Configuration template
+└── README.md                     # Project overview
+```
+
+## Module Overview
+
+### cli/
+**Purpose**: Command-line interface and orchestration logic
+
+- **args.rs**: Defines CLI arguments using `clap` crate
+  - Command-line flags and options
+  - Argument validation
+  - Help text generation
+
+- **orchestrator.rs**: Main orchestration logic
+  - Coordinates file scanning, categorization, and moving
+  - Handles undo operations
+  - Manages user interaction and confirmation
+
+### files/
+**Purpose**: File detection, batching, moving, and undo operations
+
+- **batch.rs**: Batch file processing
+  - Groups files for processing
+  - Manages concurrent operations
+  - Handles batch-level errors
+
+- **detector.rs**: File type detection
+  - Identifies text files that can be inspected
+  - Determines file categories by extension
+  - Supports 30+ text file formats
+
+- **mover.rs**: File moving operations
+  - Moves files to destination folders
+  - Creates directories as needed
+  - Handles file operation errors
+
+- **undo.rs**: Undo functionality
+  - Reverses file moves
+  - Handles conflicts and edge cases
+  - Cleans up empty directories
+
+### gemini/
+**Purpose**: Google Gemini API integration
+
+- **client.rs**: API client implementation
+  - Makes HTTP requests to Gemini API
+  - Handles authentication
+  - Manages response parsing
+
+- **errors.rs**: Error types and handling
+  - Custom error types for API failures
+  - Error conversion and propagation
+  - User-friendly error messages
+
+- **prompt.rs**: Prompt engineering
+  - Constructs prompts for categorization
+  - Handles custom vs default categories
+  - Formats file lists for API
+
+- **types.rs**: API request/response types
+  - Serialization/deserialization structures
+  - Type-safe API communication
+  - JSON parsing
+
+### models/
+**Purpose**: Core data structures
+
+- **metadata.rs**: File metadata
+  - File size, modification time
+  - Used for cache invalidation
+  - Lightweight file tracking
+
+- **move_record.rs**: File move tracking
+  - Records source and destination paths
+  - Tracks move status (completed/undone/failed)
+  - Used by undo system
+
+- **organization.rs**: Organization plan
+  - Represents categorization decisions
+  - Maps files to destination paths
+  - Used for preview and execution
+
+### settings/
+**Purpose**: Configuration management
+
+- **config.rs**: Configuration loading/saving
+  - Reads from TOML file
+  - Validates configuration
+  - Provides default values
+
+- **prompt.rs**: Interactive setup
+  - Prompts user for missing config
+  - Validates user input
+  - Saves configuration
+
+- **tests.rs**: Configuration tests
+  - Unit tests for config parsing
+  - Validation tests
+  - Edge case handling
+
+### storage/
+**Purpose**: Persistent data layer
+
+- **cache.rs**: Caching system
+  - Stores API responses
+  - Implements expiry logic (7 days)
+  - LRU eviction when limit reached
+
+- **undo_log.rs**: Undo log management
+  - Persists move records
+  - Implements retention policy (30 days)
+  - Handles log corruption
+
+## Building and Testing
+
+### Build in Debug Mode
+
+For development with debug symbols:
+```bash
+cargo build
+```
+
+Binary location: `./target/debug/noentropy`
+
+### Build in Release Mode
+
+Optimized build for production:
+```bash
+cargo build --release
+```
+
+Binary location: `./target/release/noentropy`
+
+### Run Tests
+
+Run all unit tests:
+```bash
+cargo test
+```
+
+Run tests with output:
+```bash
+cargo test -- --nocapture
+```
+
+Run specific test:
+```bash
+cargo test test_name
+```
+
+### Run with Debug Output
+
+Enable verbose logging:
+```bash
+RUST_LOG=debug cargo run
+```
+
+### Run Clippy (Linting)
+
+Check for common mistakes and code quality:
+```bash
+cargo clippy
+```
+
+Fix auto-fixable issues:
+```bash
+cargo clippy --fix
+```
+
+### Check Code
+
+Fast check without building:
+```bash
+cargo check
+```
+
+### Format Code
+
+Format code according to Rust standards:
+```bash
+cargo fmt
+```
+
+Check formatting without changing files:
+```bash
+cargo fmt -- --check
+```
+
+## Key Dependencies
+
+NoEntropy uses these main dependencies (see `Cargo.toml` for full list):
+
+- **clap**: Command-line argument parsing
+- **tokio**: Async runtime for concurrent operations
+- **reqwest**: HTTP client for API requests
+- **serde**: Serialization/deserialization
+- **serde_json**: JSON parsing
+- **toml**: TOML configuration parsing
+- **directories**: Cross-platform directory paths
+
+## Development Workflow
+
+### 1. Set Up Development Environment
+
+```bash
+# Clone repository
+git clone https://github.com/glitchySid/noentropy.git
+cd noentropy
+
+# Build project
+cargo build
+
+# Run tests
+cargo test
+
+# Check code quality
+cargo clippy
+```
+
+### 2. Create Feature Branch
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+### 3. Make Changes
+
+- Write code following Rust conventions
+- Add tests for new functionality
+- Update documentation as needed
+- Run `cargo fmt` before committing
+
+### 4. Test Changes
+
+```bash
+# Run tests
+cargo test
+
+# Test manually with your changes
+cargo run -- --dry-run
+
+# Check for issues
+cargo clippy
+```
+
+### 5. Commit and Push
+
+```bash
+git add .
+git commit -m "Add feature: description"
+git push origin feature/your-feature-name
+```
+
+### 6. Create Pull Request
+
+- Go to GitHub and create a pull request
+- Describe your changes clearly
+- Reference any related issues
+- Wait for review and feedback
+
+## Code Style Guidelines
+
+### Rust Conventions
+
+- Follow standard Rust naming conventions
+- Use `snake_case` for functions and variables
+- Use `PascalCase` for types and traits
+- Use `SCREAMING_SNAKE_CASE` for constants
+
+### Documentation
+
+- Add doc comments (`///`) for public APIs
+- Explain complex logic with inline comments
+- Update relevant documentation files
+
+### Error Handling
+
+- Use `Result` types for operations that can fail
+- Provide meaningful error messages
+- Avoid panicking in library code
+
+### Testing
+
+- Write unit tests for new functionality
+- Test error cases and edge conditions
+- Use descriptive test names
+
+## Common Development Tasks
+
+### Adding a New CLI Flag
+
+1. Edit `src/cli/args.rs`
+2. Add new field to `Args` struct
+3. Add clap attribute for the flag
+4. Update `orchestrator.rs` to use the flag
+
+### Adding a New File Type
+
+1. Edit `src/files/detector.rs`
+2. Add extension to relevant detection function
+3. Add tests for the new file type
+
+### Modifying AI Prompts
+
+1. Edit `src/gemini/prompt.rs`
+2. Update prompt construction logic
+3. Test with various file types
+4. Consider token limits
+
+### Adding New Configuration Options
+
+1. Edit `src/settings/config.rs`
+2. Add field to `Config` struct
+3. Update serialization/deserialization
+4. Add validation if needed
+5. Update `config.example.toml`
+6. Update documentation
+
+## Debugging Tips
+
+### Enable Detailed Logging
+
+```bash
+RUST_LOG=debug cargo run
+```
+
+### Use Rust Backtrace
+
+```bash
+RUST_BACKTRACE=1 cargo run
+```
+
+Full backtrace:
+```bash
+RUST_BACKTRACE=full cargo run
+```
+
+### Debug Specific Modules
+
+```bash
+RUST_LOG=noentropy::gemini=debug cargo run
+```
+
+### Print Debugging
+
+Use `dbg!()` macro for quick debugging:
+```rust
+dbg!(&some_variable);
+```
+
+## Performance Profiling
+
+### Basic Timing
+
+```bash
+time cargo run --release
+```
+
+### CPU Profiling (Linux)
+
+```bash
+cargo install flamegraph
+sudo cargo flamegraph
+```
+
+### Memory Profiling
+
+```bash
+cargo install cargo-instruments
+cargo instruments -t Allocations
+```
+
+## Continuous Integration
+
+NoEntropy uses GitHub Actions for CI/CD (see `.github/workflows/rust.yml`):
+
+- Runs on push and pull requests
+- Tests on Linux, macOS, and Windows
+- Checks formatting, linting, and tests
+- Builds release binaries
+
+## Release Process
+
+1. Update version in `Cargo.toml`
+2. Update `CHANGELOG.md` (if exists)
+3. Create git tag: `git tag v1.0.0`
+4. Push tag: `git push origin v1.0.0`
+5. GitHub Actions builds and publishes release
+
+## Architecture Decisions
+
+### Why Rust?
+
+- Performance: Fast file operations and concurrent processing
+- Safety: Memory safety without garbage collection
+- Ecosystem: Great libraries for CLI, HTTP, and serialization
+
+### Why Tokio?
+
+- Async/await support for concurrent API calls
+- Efficient handling of I/O operations
+- Industry-standard async runtime
+
+### Why Gemini API?
+
+- Powerful language understanding
+- Good at semantic file categorization
+- Reasonable rate limits and pricing
+
+### Why Caching?
+
+- Reduces API costs
+- Improves performance for repeated runs
+- Minimizes redundant analysis
+
+## Future Enhancements
+
+Ideas for future development:
+
+- [ ] Custom AI model support (OpenAI, Claude, etc.)
+- [ ] GUI version (desktop application)
+- [ ] Watch mode (automatic organization on file creation)
+- [ ] Plugin system for custom organization rules
+- [ ] Dry-run improvements with more detailed analysis
+- [ ] Better conflict resolution strategies
+- [ ] Multi-folder support
+- [ ] Rule-based organization (in addition to AI)
+
+## Getting Help
+
+- Read existing documentation
+- Check GitHub issues for similar questions
+- Ask in GitHub Discussions
+- Contact maintainers
+
+## Resources
+
+- [Rust Book](https://doc.rust-lang.org/book/)
+- [Tokio Tutorial](https://tokio.rs/tokio/tutorial)
+- [Clap Documentation](https://docs.rs/clap/)
+- [Serde Guide](https://serde.rs/)
+
+---
+
+[Back to Main README](../README.md) | [Contributing Guide](CONTRIBUTING.md)
--- a/docs/HOW_IT_WORKS.md
+++ b/docs/HOW_IT_WORKS.md
@@ -0,0 +1,345 @@
+# How NoEntropy Works
+
+This guide explains the internal architecture and processes that power NoEntropy's intelligent file organization.
+
+## Overview
+
+NoEntropy uses a multi-stage pipeline that combines AI-powered categorization with intelligent caching and concurrent processing to efficiently organize your files.
+
+## Organization Process
+
+NoEntropy follows a five-step process to organize your files:
+
+```
+┌─────────────────┐
+│  1. Scan Files  │ → Read all files in DOWNLOAD_FOLDER 
+└────────┬────────┘   (and subdirs if --recursive flag is used)
+         ▼
+┌─────────────────────────┐
+│ 2. Initial Categorization │ → Ask Gemini to categorize by filename
+└────────┬────────────────┘
+         ▼
+┌──────────────────────┐
+│  3. Deep Inspection   │ → Read text files for sub-categories
+│     (Concurrent)      │   • Reads file content
+│                       │   • Asks AI for sub-folder
+└────────┬──────────────┘
+         ▼
+┌──────────────────────┐
+│  4. Preview & Confirm│ → Show organization plan
+│                       │   • Ask user approval
+└────────┬──────────────┘
+         ▼
+┌──────────────────────┐
+│   5. Execute Moves    │ → Move files to organized folders
+└──────────────────────┘
+```
+
+### Step 1: File Scanning
+
+**What happens:**
+- Scans the configured download folder
+- Optionally scans subdirectories with `--recursive` flag
+- Collects file paths and metadata (size, modification time)
+- Filters out directories and focuses on files only
+
+**Output:** List of file paths ready for categorization
+
+### Step 2: Initial Categorization
+
+**What happens:**
+- Sends list of filenames to Gemini API
+- AI analyzes filenames and determines appropriate categories
+- Returns a categorization plan for all files
+- Uses custom categories if configured, otherwise uses defaults
+
+**AI Prompt includes:**
+- List of all filenames
+- Available categories (default or custom)
+- Instructions to categorize based on file type and content
+- Request for main category assignment
+
+**Output:** Initial organization plan with main categories
+
+### Step 3: Deep Inspection
+
+**What happens:**
+- Identifies text-based files that can be read
+- Concurrently reads file contents (up to `--max-concurrent` files at once)
+- Sends content to Gemini AI for sub-folder suggestions
+- AI analyzes content and suggests relevant sub-categories
+- Applies intelligent retry logic with exponential backoff
+
+**Supported text file formats:**
+```
+Source Code: rs, py, js, ts, jsx, tsx, java, go, c, cpp, h, hpp, rb, php, swift, kt, scala, lua, r, m
+Web/Config: html, css, json, xml, yaml, yml, toml, ini, cfg, conf
+Documentation: txt, md, sql, sh, bat, ps1, log
+```
+
+**Why concurrent?**
+- Processes multiple files simultaneously
+- Significantly reduces total processing time
+- Configurable concurrency limit prevents API rate limiting
+
+**Output:** Enhanced organization plan with sub-folders
+
+### Step 4: Preview & Confirmation
+
+**What happens:**
+- Displays complete organization plan to user
+- Shows source file and destination path for each file
+- Waits for user confirmation (y/n)
+- Allows user to review before any changes are made
+
+**User options:**
+- Accept: Proceed with organization
+- Decline: Cancel and exit without changes
+
+**Output:** User decision (proceed or abort)
+
+### Step 5: Execute Moves
+
+**What happens:**
+- Creates destination directories as needed
+- Moves files to their designated locations
+- Records each move in the undo log
+- Reports success/failure for each operation
+- Displays final summary statistics
+
+**Safety features:**
+- Only moves files after user confirmation
+- Tracks all operations for undo capability
+- Handles errors gracefully without stopping entire process
+- Creates parent directories automatically
+
+**Output:** Organized files and execution summary
+
+## Caching System
+
+NoEntropy includes an intelligent caching system to minimize API calls and improve performance.
+
+### Cache Design
+
+- **Location**: `.noentropy_cache.json` in project root
+- **Format**: JSON with file path as key
+- **Expiry**: 7 days (automatically cleaned up)
+- **Max Entries**: 1000 entries (LRU eviction)
+- **Change Detection**: File size + modification time (not content hash)
+
+### How Caching Works
+
+1. **First Run**: 
+   - Files are analyzed via Gemini API
+   - Categorization results are cached with metadata
+   
+2. **Cache Check** (subsequent runs):
+   ```
+   File found in cache?
+   ├─ No → Analyze via API, cache result
+   └─ Yes → File changed (size/time)?
+       ├─ Yes → Re-analyze via API, update cache
+       └─ No → Use cached categorization
+   ```
+
+3. **Cache Maintenance**:
+   - Removes entries older than 7 days on every run
+   - Evicts oldest entries when limit (1000) is reached
+   - Validates file still exists before using cache
+
+### Cache Benefits
+
+- **Reduced API Costs**: Avoids re-analyzing unchanged files
+- **Faster Processing**: No API call needed for cached files
+- **Efficient**: Metadata-based change detection (no content hashing)
+- **Automatic Cleanup**: Self-maintaining with age and size limits
+
+### When Cache is Invalidated
+
+Cache entries are invalidated when:
+- File size changes
+- File modification time changes
+- Cache entry is older than 7 days
+- File no longer exists
+- Cache is manually deleted
+
+## Undo Log System
+
+NoEntropy tracks all file moves to enable undo functionality.
+
+### Undo Log Design
+
+- **Location**: `~/.config/noentropy/data/undo_log.json`
+- **Format**: JSON array of move records
+- **Retention**: 30 days (automatically cleaned up)
+- **Max Entries**: 1000 entries (oldest evicted)
+- **Status Tracking**: Completed, Undone, Failed states
+
+### Move Record Structure
+
+Each file move is recorded with:
+- Source path (original location)
+- Destination path (new location)
+- Timestamp of move
+- Status (completed/undone/failed)
+
+### How Undo Works
+
+1. **During Organization**:
+   ```
+   For each file moved:
+   ├─ Record source path
+   ├─ Record destination path
+   ├─ Record timestamp
+   └─ Mark as "completed"
+   ```
+
+2. **Undo Execution**:
+   ```
+   Load undo log
+   ├─ Filter "completed" moves (not already undone)
+   ├─ Show preview to user
+   ├─ Request confirmation
+   └─ If confirmed:
+       ├─ Check destination exists
+       ├─ Check source doesn't exist (avoid conflicts)
+       ├─ Move file back to source
+       ├─ Mark as "undone"
+       └─ Clean up empty directories
+   ```
+
+3. **Conflict Handling**:
+   - **Source exists**: Skip restore (prevent overwrite)
+   - **Destination missing**: Skip restore (file was deleted)
+   - **Permission error**: Skip restore, report error
+
+### Undo Safety Features
+
+- **Preview Before Action**: Always shows what will be undone
+- **Conflict Detection**: Prevents data loss from overwrites
+- **Missing File Handling**: Gracefully skips deleted files
+- **Partial Undo Support**: Continues processing despite individual failures
+- **Empty Directory Cleanup**: Removes empty folders after undo
+- **Dry-Run Mode**: Preview undo without executing
+
+### Undo Limitations
+
+- Only tracks moves made by NoEntropy
+- Cannot track manual file operations
+- Limited to 30-day history
+- Cannot restore deleted files (only moves)
+
+## Supported File Categories
+
+NoEntropy can organize files into these default categories:
+
+| Category | File Types |
+|----------|------------|
+| **Images** | PNG, JPG, JPEG, GIF, SVG, BMP, WEBP, ICO, TIFF |
+| **Documents** | PDF, DOC, DOCX, TXT, MD, RTF, ODT, PAGES |
+| **Installers** | EXE, DMG, APP, PKG, DEB, RPM, MSI, APK |
+| **Music** | MP3, WAV, FLAC, M4A, AAC, OGG, WMA |
+| **Videos** | MP4, AVI, MKV, MOV, WMV, FLV, WEBM |
+| **Archives** | ZIP, TAR, GZ, RAR, 7Z, BZ2, XZ |
+| **Code** | Source code and configuration files |
+| **Misc** | Everything else |
+
+## AI Integration
+
+NoEntropy uses Google's Gemini API for intelligent categorization.
+
+### API Usage
+
+- **Model**: Gemini 1.5 Flash (configurable)
+- **Concurrent Requests**: 5 by default (configurable via `--max-concurrent`)
+- **Retry Logic**: Exponential backoff for failed requests
+- **Rate Limiting**: Respects API rate limits with configurable concurrency
+
+### Prompt Engineering
+
+NoEntropy uses carefully crafted prompts to get accurate categorization:
+
+1. **Initial Categorization Prompt**:
+   - Lists all filenames
+   - Specifies available categories
+   - Requests JSON response with categorization plan
+
+2. **Deep Inspection Prompt**:
+   - Provides file content
+   - Requests sub-folder suggestion based on content
+   - Asks for semantic analysis, not just extension
+
+### Error Handling
+
+- **Network Errors**: Retry with exponential backoff
+- **Rate Limiting**: Respects limits, retries after delay
+- **Invalid Responses**: Logs error, continues with other files
+- **Timeout**: Configurable timeout with fallback behavior
+
+## Performance Characteristics
+
+### Factors Affecting Performance
+
+1. **Number of Files**:
+   - 10-50 files: ~10-30 seconds
+   - 100-500 files: 1-3 minutes
+   - 1000+ files: 5-10 minutes
+
+2. **Concurrency Level**:
+   - Higher = faster but more API load
+   - Lower = slower but safer for rate limits
+   - Default (5) balances speed and safety
+
+3. **Cache Hit Rate**:
+   - High hit rate (>80%): Significantly faster
+   - Low hit rate (<20%): More API calls needed
+   - Regular usage improves hit rate over time
+
+4. **Text File Count**:
+   - More text files = more deep inspection
+   - Deep inspection adds processing time
+   - Concurrent processing mitigates this
+
+### Optimization Strategies
+
+1. **Use caching**: Regular runs benefit from cached results
+2. **Adjust concurrency**: Increase for faster processing
+3. **Dry-run first**: Test configuration without full processing
+4. **Organize regularly**: Smaller batches process faster
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                     NoEntropy CLI                       │
+│                   (Orchestrator)                        │
+└────────────┬──────────────────────────────┬─────────────┘
+             │                              │
+    ┌────────▼─────────┐           ┌───────▼────────┐
+    │  File Scanner    │           │  Config Manager │
+    │  & Detector      │           │                 │
+    └────────┬─────────┘           └────────────────┘
+             │
+    ┌────────▼──────────────────────────────────────┐
+    │           Gemini AI Client                    │
+    │  (with retry logic & concurrent processing)   │
+    └────────┬──────────────────────────────────────┘
+             │
+    ┌────────▼─────────┐           ┌────────────────┐
+    │  Cache System    │           │   Undo Log     │
+    └──────────────────┘           └────────────────┘
+             │
+    ┌────────▼─────────┐
+    │   File Mover     │
+    └──────────────────┘
+```
+
+## Next Steps
+
+- [Usage Guide](USAGE.md) - Learn how to use NoEntropy
+- [Configuration Guide](CONFIGURATION.md) - Configure NoEntropy
+- [Development Guide](DEVELOPMENT.md) - Contribute to NoEntropy
+
+---
+
+[Back to Main README](../README.md)
--- a/docs/INSTALLATION.md
+++ b/docs/INSTALLATION.md
@@ -0,0 +1,121 @@
+# Installation Guide
+
+This guide covers different ways to install and set up NoEntropy on your system.
+
+## Prerequisites
+
+Before installing NoEntropy, ensure you have:
+
+- **Rust 2024 Edition** or later (if building from source)
+- **Google Gemini API Key** - Get one at [https://ai.google.dev/](https://ai.google.dev/)
+- A folder full of unorganized files to clean up!
+
+## Option 1: Download Pre-built Binary
+
+The easiest way to get started is to download a pre-built binary for your operating system.
+
+1. **Download Binary**
+   
+   Visit the releases page and download the binary for your operating system (Windows, Linux, or macOS):
+   ```bash
+   https://github.com/glitchySid/noentropy/releases
+   ```
+
+2. **Give Permission (Linux/macOS only)**
+   
+   Make the binary executable:
+   ```bash
+   chmod +x noentropy
+   ```
+
+3. **Run NoEntropy**
+   
+   ```bash
+   ./noentropy
+   ```
+
+## Option 2: Build from Source
+
+If you prefer to build from source or want the latest development version:
+
+1. **Clone the Repository**
+   
+   ```bash
+   git clone https://github.com/glitchySid/noentropy.git
+   cd noentropy
+   ```
+
+2. **Build the Application**
+   
+   ```bash
+   cargo build --release
+   ```
+
+3. **Run the Application**
+   
+   ```bash
+   ./target/release/noentropy
+   ```
+
+## First-Run Setup
+
+On first run, NoEntropy will guide you through an interactive setup process:
+
+### Interactive Setup
+
+NoEntropy provides an interactive setup if configuration is missing:
+
+- **Missing API key?** → You'll be prompted to enter it
+- **Missing download folder?** → You'll be prompted to specify it (with default suggestion)
+- **Both missing?** → You'll be guided through complete setup
+
+Configuration is automatically saved to `~/.config/noentropy/config.toml` after interactive setup.
+
+### Manual Configuration
+
+Alternatively, you can manually create the configuration file:
+
+```bash
+cp config.example.toml ~/.config/noentropy/config.toml
+nano ~/.config/noentropy/config.toml
+```
+
+See the [Configuration Guide](CONFIGURATION.md) for detailed configuration options.
+
+## Getting Your Gemini API Key
+
+1. Visit [Google AI Studio](https://ai.google.dev/)
+2. Sign in with your Google account
+3. Create a new API key
+4. Copy the key to your configuration file or enter it during interactive setup
+
+## Verification
+
+To verify your installation works correctly:
+
+1. Run NoEntropy with the `--dry-run` flag:
+   ```bash
+   ./noentropy --dry-run
+   ```
+
+2. You should see NoEntropy scan your downloads folder and display an organization plan without moving any files.
+
+## Next Steps
+
+- [Configure NoEntropy](CONFIGURATION.md) - Learn about configuration options
+- [Usage Guide](USAGE.md) - Learn how to use NoEntropy effectively
+- [How It Works](HOW_IT_WORKS.md) - Understand the organization process
+
+## Troubleshooting
+
+If you encounter issues during installation, check the [Troubleshooting Guide](TROUBLESHOOTING.md).
+
+Common installation issues:
+
+- **Rust not installed**: Install Rust from [rustup.rs](https://rustup.rs/)
+- **Build errors**: Ensure you have the latest Rust toolchain: `rustup update`
+- **Permission denied**: Make sure the binary has execute permissions (Linux/macOS)
+
+---
+
+[Back to Main README](../README.md)
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,518 @@
+# Troubleshooting Guide
+
+This guide helps you solve common issues you might encounter while using NoEntropy.
+
+## Configuration Issues
+
+### "API key not configured"
+
+**Problem**: NoEntropy cannot find your Gemini API key.
+
+**Solutions**:
+
+1. **Interactive Setup** (Recommended):
+   - Simply run NoEntropy and it will prompt you for your API key
+   - The configuration will be saved automatically
+
+2. **Manual Configuration**:
+   ```bash
+   mkdir -p ~/.config/noentropy
+   nano ~/.config/noentropy/config.toml
+   ```
+   
+   Add:
+   ```toml
+   api_key = "your_actual_api_key_here"
+   download_folder = "/home/user/Downloads"
+   ```
+
+3. **Use Change Key Flag**:
+   ```bash
+   ./noentropy --change-key
+   ```
+
+**Verify**: Run `./noentropy --dry-run` to test your configuration.
+
+---
+
+### "Download folder not configured"
+
+**Problem**: NoEntropy doesn't know which folder to organize.
+
+**Solutions**:
+
+1. **Interactive Setup**:
+   - Run NoEntropy and it will prompt you for the folder path
+   - It will suggest a default location based on your system
+
+2. **Manual Configuration**:
+   ```bash
+   nano ~/.config/noentropy/config.toml
+   ```
+   
+   Add or update:
+   ```toml
+   download_folder = "/path/to/your/Downloads"
+   ```
+
+**Important**: Use absolute paths, not relative paths (e.g., `/home/user/Downloads`, not `~/Downloads`).
+
+---
+
+### "Configuration file not found"
+
+**Problem**: The configuration file doesn't exist or is in the wrong location.
+
+**Expected Locations**:
+- **Linux/macOS**: `~/.config/noentropy/config.toml`
+- **Windows**: `C:\Users\<username>\AppData\Roaming\noentropy\config.toml`
+
+**Solutions**:
+
+1. **Create configuration directory**:
+   ```bash
+   mkdir -p ~/.config/noentropy
+   ```
+
+2. **Copy example configuration**:
+   ```bash
+   cp config.example.toml ~/.config/noentropy/config.toml
+   ```
+
+3. **Edit configuration**:
+   ```bash
+   nano ~/.config/noentropy/config.toml
+   ```
+
+---
+
+### "Invalid API key format"
+
+**Problem**: Your API key is incorrectly formatted or invalid.
+
+**Solutions**:
+
+1. **Get a new API key**:
+   - Visit [Google AI Studio](https://ai.google.dev/)
+   - Create a new API key
+   - Copy it exactly (including all characters)
+
+2. **Check for common issues**:
+   - No extra spaces before or after the key
+   - Key is enclosed in quotes in TOML file
+   - No line breaks within the key
+
+**Example of correct format**:
+```toml
+api_key = "AIzaSyDTEhAq414SHY094A5oy5lxNA0vhbY1O3k"
+```
+
+---
+
+## API and Network Issues
+
+### "API rate limit exceeded"
+
+**Problem**: You're making too many requests to the Gemini API.
+
+**Solutions**:
+
+1. **Wait and retry**:
+   - Wait 5-10 minutes before trying again
+   - Rate limits reset over time
+
+2. **Reduce concurrency**:
+   ```bash
+   ./noentropy --max-concurrent 2
+   ```
+
+3. **Use caching**:
+   - NoEntropy caches results for 7 days
+   - Subsequent runs of same files won't hit API
+   - Cache is automatic, no configuration needed
+
+4. **Check API quota**:
+   - Visit [Google AI Studio](https://ai.google.dev/)
+   - Check your API usage and quotas
+   - Consider upgrading if you hit limits frequently
+
+---
+
+### "Network error" or "Connection timeout"
+
+**Problem**: Cannot connect to Gemini API.
+
+**Solutions**:
+
+1. **Check internet connection**:
+   ```bash
+   ping google.com
+   ```
+
+2. **Verify API service status**:
+   - Check [Google Cloud Status](https://status.cloud.google.com/)
+   - Verify Gemini API is operational
+
+3. **Check firewall settings**:
+   - Ensure outbound HTTPS (port 443) is allowed
+   - Whitelist generativelanguage.googleapis.com if needed
+
+4. **Try with fewer files**:
+   - API timeout might be due to large batch
+   - Reduce `--max-concurrent` value
+   - Organize files in smaller batches
+
+5. **Check proxy settings**:
+   - If behind corporate proxy, configure proxy settings
+   - Some proxies block API calls
+
+---
+
+### "Invalid API response" or "Failed to parse response"
+
+**Problem**: API returned unexpected or malformed data.
+
+**Solutions**:
+
+1. **Retry the operation**:
+   - Temporary API glitch might resolve itself
+   - Run NoEntropy again
+
+2. **Check API key validity**:
+   - API key might have been revoked
+   - Create a new API key
+
+3. **Clear cache and retry**:
+   ```bash
+   rm .noentropy_cache.json
+   ./noentropy
+   ```
+
+4. **Report issue**:
+   - If problem persists, it might be a bug
+   - Check [GitHub Issues](https://github.com/glitchySid/noentropy/issues)
+
+---
+
+## File Operation Issues
+
+### "Failed to move file" or "Permission denied"
+
+**Problem**: Cannot move files to destination folder.
+
+**Solutions**:
+
+1. **Check file permissions**:
+   ```bash
+   ls -la /path/to/file
+   ```
+
+2. **Check destination permissions**:
+   ```bash
+   ls -la /path/to/Downloads
+   ```
+
+3. **Fix permissions**:
+   ```bash
+   chmod 644 /path/to/file  # For files
+   chmod 755 /path/to/directory  # For directories
+   ```
+
+4. **Run as appropriate user**:
+   - Don't run as root unless necessary
+   - Ensure you own the files and folder
+
+5. **Check disk space**:
+   ```bash
+   df -h /path/to/Downloads
+   ```
+
+---
+
+### "File not found" or "Source file doesn't exist"
+
+**Problem**: Files were deleted or moved before organization completed.
+
+**Solutions**:
+
+1. **Verify files exist**:
+   ```bash
+   ls -la /path/to/Downloads
+   ```
+
+2. **Check if another process is moving files**:
+   - Browser might be cleaning up
+   - Another organization tool might be running
+   - Antivirus might have quarantined files
+
+3. **Use dry-run first**:
+   ```bash
+   ./noentropy --dry-run
+   ```
+   - This ensures files exist before actual move
+
+---
+
+### "Destination already exists" or "File conflict"
+
+**Problem**: A file with the same name already exists at destination.
+
+**Solutions**:
+
+1. **Current behavior**: NoEntropy will skip the file to prevent overwrites
+
+2. **Manual resolution**:
+   - Rename the existing file
+   - Delete the existing file if not needed
+   - Run organization again
+
+3. **Check for duplicates**:
+   - You might have duplicate downloads
+   - Consider cleaning duplicates manually
+
+---
+
+## Cache Issues
+
+### "Cache corrupted" or "Failed to read cache"
+
+**Problem**: Cache file is corrupted or malformed.
+
+**Solutions**:
+
+1. **Delete cache file**:
+   ```bash
+   rm .noentropy_cache.json
+   ```
+
+2. **Run NoEntropy again**:
+   - A new cache will be created automatically
+   - Files will be analyzed fresh via API
+
+3. **Prevent corruption**:
+   - Don't manually edit cache file
+   - Let NoEntropy manage cache automatically
+
+---
+
+### "Cache not working" or "Too many API calls"
+
+**Problem**: Cache doesn't seem to reduce API calls.
+
+**Diagnosis**:
+
+Check if files are being modified:
+```bash
+ls -lt /path/to/Downloads | head
+```
+
+**Reasons cache might not work**:
+
+1. **Files are constantly changing**:
+   - If file modification time or size changes, cache is invalidated
+   - This is expected behavior
+
+2. **Cache expired**:
+   - Cache entries older than 7 days are removed
+   - Run organization more frequently
+
+3. **Cache deleted**:
+   - Check if `.noentropy_cache.json` exists in project root
+   - If not, cache will rebuild on next run
+
+**Solution**: This is often expected behavior, not a bug.
+
+---
+
+## Undo Issues
+
+### "No completed moves to undo"
+
+**Problem**: Cannot undo because no undo history exists.
+
+**Reasons**:
+
+1. **No files have been organized yet**
+   - Run organization first
+
+2. **All moves already undone**
+   - You've already undone the previous organization
+
+3. **Undo log was deleted**
+   - Check if `~/.config/noentropy/data/undo_log.json` exists
+
+4. **Undo log expired**
+   - Entries older than 30 days are automatically removed
+
+**Solution**: Run organization to create new undo history.
+
+---
+
+### "Undo log not found"
+
+**Problem**: The undo log file doesn't exist.
+
+**Solutions**:
+
+1. **Create data directory**:
+   ```bash
+   mkdir -p ~/.config/noentropy/data
+   ```
+
+2. **Run organization**:
+   - This will create the undo log automatically
+
+---
+
+### "Skipping [file] - source already exists"
+
+**Problem**: During undo, a file already exists at the original location.
+
+**This is a safety feature**:
+- NoEntropy won't overwrite existing files
+- Prevents data loss
+
+**Solutions**:
+
+1. **Manual inspection**:
+   - Check both source and destination files
+   - Determine which one to keep
+   - Manually resolve the conflict
+
+2. **Rename existing file**:
+   - Move or rename the file at source location
+   - Run undo again
+
+---
+
+### "Failed to restore [file]"
+
+**Problem**: Unable to move file back to original location during undo.
+
+**Common causes**:
+
+1. **Permission issues**: See "Permission denied" section above
+2. **File deleted**: Destination file was deleted after organization
+3. **Disk space**: Not enough space at source location
+
+**Solution**: Check logs for specific error, then address the underlying cause.
+
+---
+
+## Build and Development Issues
+
+### "Rust not installed" or "cargo command not found"
+
+**Problem**: Rust toolchain is not installed.
+
+**Solution**:
+
+Install Rust from official source:
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+Then restart your terminal and try again.
+
+---
+
+### Build errors or compilation failures
+
+**Problem**: Cannot build from source.
+
+**Solutions**:
+
+1. **Update Rust toolchain**:
+   ```bash
+   rustup update
+   ```
+
+2. **Clean build directory**:
+   ```bash
+   cargo clean
+   cargo build --release
+   ```
+
+3. **Check Rust version**:
+   ```bash
+   rustc --version
+   ```
+   - Ensure you have Rust 2024 edition or later
+
+4. **Check dependencies**:
+   ```bash
+   cargo update
+   ```
+
+---
+
+## Platform-Specific Issues
+
+### Linux/macOS: "Permission denied" when running binary
+
+**Solution**:
+```bash
+chmod +x noentropy
+```
+
+---
+
+### Windows: "Windows protected your PC" warning
+
+**This is expected** for unsigned binaries.
+
+**Solution**:
+1. Click "More info"
+2. Click "Run anyway"
+
+Alternatively, build from source to avoid this warning.
+
+---
+
+### macOS: "noentropy cannot be opened because the developer cannot be verified"
+
+**Solution**:
+
+1. **First method** (Recommended):
+   ```bash
+   xattr -d com.apple.quarantine noentropy
+   ```
+
+2. **Alternative method**:
+   - Right-click the binary
+   - Select "Open"
+   - Click "Open" in the dialog
+
+---
+
+## Getting More Help
+
+If you've tried the solutions above and still have issues:
+
+1. **Check GitHub Issues**: [https://github.com/glitchySid/noentropy/issues](https://github.com/glitchySid/noentropy/issues)
+   - Someone might have reported the same issue
+   - Solutions might already be available
+
+2. **Create a new issue**:
+   - Describe the problem clearly
+   - Include error messages
+   - Mention your OS and NoEntropy version
+   - Describe steps to reproduce
+
+3. **Join discussions**:
+   - Check GitHub Discussions for community help
+   - Share your use case and ask questions
+
+## Debug Mode
+
+For detailed error information, run with Rust backtrace:
+
+```bash
+RUST_BACKTRACE=1 ./noentropy
+```
+
+This provides detailed stack traces for debugging issues.
+
+---
+
+[Back to Main README](../README.md)
--- a/docs/USAGE.md
+++ b/docs/USAGE.md
@@ -0,0 +1,329 @@
+# Usage Guide
+
+This guide covers all the ways you can use NoEntropy to organize your files.
+
+## Quick Start
+
+The simplest way to organize your downloads folder:
+
+```bash
+./noentropy
+```
+
+This will:
+1. Scan your configured downloads folder
+2. Ask Gemini AI to categorize files
+3. Show you a preview of the organization plan
+4. Ask for confirmation before moving files
+5. Execute the organization if you approve
+
+## Command-Line Options
+
+NoEntropy supports several command-line flags to customize its behavior:
+
+| Option | Short | Default | Description |
+|--------|-------|---------|-------------|
+| `--dry-run` | `-d` | `false` | Preview changes without moving files |
+| `--max-concurrent` | `-m` | `5` | Maximum concurrent API requests |
+| `--recursive` | - | `false` | Recursively search files in subdirectories |
+| `--undo` | - | `false` | Undo the last file organization |
+| `--change-key` | - | `false` | Change Gemini API key |
+| `--help` | `-h` | - | Show help message |
+
+## Usage Examples
+
+### Dry-Run Mode
+
+Preview what NoEntropy would do without actually moving any files:
+
+```bash
+./noentropy --dry-run
+```
+
+**When to use:**
+- First time using NoEntropy
+- Testing new custom categories
+- Checking how specific files will be categorized
+- Verifying organization plan before execution
+
+**Example output:**
+```
+Found 47 files. Asking Gemini to organize...
+Gemini Plan received! Performing deep inspection...
+Deep inspection complete!
+
+--- EXECUTION PLAN (DRY RUN) ---
+Plan: image1.png -> Images/
+Plan: document.pdf -> Documents/
+Plan: setup.exe -> Installers/
+Plan: notes.txt -> Documents/Notes/
+Plan: config.yaml -> Code/Config/
+
+DRY RUN - No files were moved
+```
+
+### Recursive Mode
+
+Organize files in subdirectories recursively:
+
+```bash
+./noentropy --recursive
+```
+
+**What it does:**
+- Scans all subdirectories within your download folder
+- Organizes files from the entire directory tree
+- Maintains relative folder structure when creating categories
+
+**Use case:** When you have downloads organized in subfolders that you want to consolidate into proper categories.
+
+### Custom Concurrency
+
+Adjust the number of concurrent API calls (default: 5):
+
+```bash
+./noentropy --max-concurrent 10
+```
+
+**When to adjust:**
+- **Increase (10-15)**: If you have fast internet and many files
+- **Decrease (1-3)**: If you're hitting rate limits or have slow internet
+- **Keep default (5)**: Works well for most use cases
+
+### Combined Options
+
+You can combine multiple options:
+
+```bash
+./noentropy --dry-run --max-concurrent 3
+```
+
+```bash
+./noentropy --recursive --max-concurrent 10
+```
+
+## Undo Operations
+
+NoEntropy tracks all file moves and allows you to undo them.
+
+### Basic Undo
+
+Revert the last file organization:
+
+```bash
+./noentropy --undo
+```
+
+**Example output:**
+```
+--- UNDO PREVIEW ---
+INFO: will restore 5 files:
+  Documents/report.pdf -> Downloads/
+  Documents/Notes/notes.txt -> Downloads/
+  Code/Config/config.yaml -> Downloads/
+  Code/Scripts/script.py -> Downloads/
+  Images/photo.png -> Downloads/
+
+Do you want to undo these changes? [y/N]: y
+
+--- UNDOING MOVES ---
+Restored: Documents/report.pdf -> Downloads/
+Restored: Documents/Notes/notes.txt -> Downloads/
+Restored: Code/Config/config.yaml -> Downloads/
+Restored: Code/Scripts/script.py -> Downloads/
+Restored: Images/photo.png -> Downloads/
+
+INFO: Removed empty directory: Documents/Notes
+INFO: Removed empty directory: Code/Config
+INFO: Removed empty directory: Code/Scripts
+
+UNDO COMPLETE!
+Files restored: 5, Skipped: 0, Failed: 0
+```
+
+### Undo Dry-Run
+
+Preview what would be undone without actually reversing changes:
+
+```bash
+./noentropy --undo --dry-run
+```
+
+**When to use:**
+- Check what files will be restored before undoing
+- Verify undo log integrity
+- See if any conflicts exist
+
+### Undo Features
+
+The undo system provides several safety features:
+
+- **Preview Before Action**: Always shows what will be undone before executing
+- **Conflict Detection**: Checks if source path already exists before restoring
+- **Missing File Handling**: Gracefully handles files that were deleted after move
+- **Partial Undo Support**: Continues even if some operations fail
+- **Empty Directory Cleanup**: Automatically removes empty directories after undo
+- **History Retention**: Keeps undo history for 30 days with auto-cleanup
+
+### Undo Limitations
+
+- Only the most recent organization can be undone
+- Files deleted after organization cannot be restored
+- Files moved outside NoEntropy cannot be tracked
+- Undo log is cleared after 30 days
+
+## Interactive Confirmation
+
+Before moving files, NoEntropy shows you the organization plan:
+
+```
+--- EXECUTION PLAN ---
+Plan: image1.png -> Images/
+Plan: document.pdf -> Documents/
+Plan: setup.exe -> Installers/
+...
+
+Do you want to apply these changes? [y/N]:
+```
+
+**Options:**
+- Type `y` or `yes` to proceed with organization
+- Type `n`, `no`, or press Enter to cancel
+
+**Tip**: Always review the plan carefully, especially when using custom categories for the first time.
+
+## Changing Configuration
+
+### Change API Key
+
+Update your Gemini API key interactively:
+
+```bash
+./noentropy --change-key
+```
+
+This will prompt you to enter a new API key and save it to your configuration.
+
+### Change Download Folder
+
+Edit your config file manually:
+
+```bash
+nano ~/.config/noentropy/config.toml
+```
+
+Update the `download_folder` value and save.
+
+## Typical Workflows
+
+### First-Time User Workflow
+
+1. Install NoEntropy
+2. Run with `--dry-run` to preview:
+   ```bash
+   ./noentropy --dry-run
+   ```
+3. Review the organization plan
+4. If satisfied, run without dry-run:
+   ```bash
+   ./noentropy
+   ```
+5. Review and confirm the plan
+6. Let NoEntropy organize your files
+
+### Regular Usage Workflow
+
+1. Download files throughout the week
+2. Periodically run NoEntropy:
+   ```bash
+   ./noentropy
+   ```
+3. Review and confirm the plan
+4. Files are organized automatically
+
+### Testing Custom Categories
+
+1. Edit config file and add custom categories
+2. Test with dry-run:
+   ```bash
+   ./noentropy --dry-run
+   ```
+3. Review how files are categorized
+4. Adjust categories if needed
+5. Run without dry-run when satisfied
+
+### Recovery Workflow
+
+If organization didn't work as expected:
+
+1. Undo the changes:
+   ```bash
+   ./noentropy --undo
+   ```
+2. Adjust configuration or categories
+3. Test with dry-run again
+4. Re-run organization
+
+## Example Terminal Output
+
+### Successful Organization
+
+```bash
+$ ./noentropy
+
+Found 47 files. Asking Gemini to organize...
+Gemini Plan received! Performing deep inspection...
+Reading content of report.pdf...
+Reading content of config.yaml...
+Reading content of script.py...
+Deep inspection complete! Moving Files.....
+
+--- EXECUTION PLAN ---
+Plan: image1.png -> Images/
+Plan: document.pdf -> Documents/
+Plan: setup.exe -> Installers/
+Plan: notes.txt -> Documents/Notes/
+Plan: config.yaml -> Code/Config/
+Plan: script.py -> Code/Scripts/
+
+Do you want to apply these changes? [y/N]: y
+
+--- MOVING FILES ---
+Moved: image1.png -> Images/
+Moved: document.pdf -> Documents/
+Moved: setup.exe -> Installers/
+Moved: notes.txt -> Documents/Notes/
+Moved: config.yaml -> Code/Config/
+Moved: script.py -> Code/Scripts/
+
+Organization Complete!
+Files moved: 47, Errors: 0
+Done!
+```
+
+## Tips and Best Practices
+
+1. **Start with dry-run**: Always test first, especially with custom categories
+2. **Review the plan**: Don't blindly accept the organization plan
+3. **Use undo when needed**: Don't hesitate to undo and reorganize
+4. **Adjust concurrency**: Lower it if you hit rate limits
+5. **Regular organization**: Run NoEntropy regularly to keep folders tidy
+6. **Test categories**: Use dry-run to test custom categories before committing
+7. **Backup important files**: Always maintain backups of critical files
+
+## Performance Considerations
+
+- **Concurrency**: Higher concurrency = faster processing but more API calls
+- **Caching**: NoEntropy caches API responses for 7 days to minimize API usage
+- **File count**: Large numbers of files (1000+) may take several minutes
+- **Rate limits**: Gemini API has rate limits; adjust `--max-concurrent` if needed
+
+## Next Steps
+
+- [How It Works](HOW_IT_WORKS.md) - Understand the organization process
+- [Configuration Guide](CONFIGURATION.md) - Learn about configuration options
+- [Troubleshooting](TROUBLESHOOTING.md) - Solve common issues
+
+---
+
+[Back to Main README](../README.md)