System-Specific Notes - Not Compatible With

README.md

@@ -9,7 +9,7 @@ A Bash script to rename files in a directory by removing unsafe characters, hand
 - **Collision avoidance**: Adds numeric suffixes (`_1`, `_2`) to prevent overwriting
 - **Case normalization**: Converts filenames to lowercase
 - **Space handling**: Replaces spaces with underscores
-- **Truncation**: Limits base filenames to 250 chars to stay under 255 char limit
+- **Truncation**: Limits base filenames to 250 chars to stay under 255 char limit (filesystem safe)
 - **Dry-run support**: Test changes before applying them
 
 ## 🚀 Usage
@@ -29,6 +29,8 @@ chmod +x rename_safe.sh
 ./rename_safe.sh /path/to/files
 ```
 
+> **Windows Users**: Run this script in [WSL](https://learn.microsoft.com/en-us/windows/wsl/) or [Git Bash](https://git-scm.com/downloads) - native Windows CMD/Powershell won't work
+
 ## 🧪 Test Script
 
 ```bash
@@ -51,11 +53,35 @@ Edit `rename_safe.sh` to customize:
 - Allowed characters: `sed 's/[^a-zA-Z0-9._-]//g'`
 - Enable hidden file support: Uncomment `.??*` loop
 
-## ⚠️ Known Issues
+## ⚠️ System-Specific Notes
 
-- Files with no extension will have suffixes appended directly
-- Hidden file processing must be manually enabled
-- Full path length is not checked (only basename)
+### 📏 Filesystem Limitations
+| OS | Max Filename Length | Notes |
+|-----|----------------------|-------|
+| Linux | 255 bytes | UTF-8 encoded characters count as 1-4 bytes |
+| Windows | 260 characters | NTFS supports 32,767 characters (Unicode-aware) |
+| macOS | 255 characters | HFS+ and APFS both use 255 char limit |
+
+> ⚠️ **This script truncates base names to 250 characters** to allow room for extensions.  
+> For extremely long extensions (e.g., `.tar.gz`), manual length checking may still be required.
+
+## 🔧 Cross-Platform Compatibility
+
+This script is compatible with:
+- **Linux** (Debian, Ubuntu, Arch, etc.)
+- **macOS** (requires GNU coreutils installed via Homebrew)
+- **WSL2** (Windows Subsystem for Linux)
+- **Git Bash** (on Windows)
+
+### ⚠️ Not Compatible With:
+- Native Windows CMD/Powershell (due to `mv`, `tr`, `sed` differences)
+- Legacy systems with non-Bash shells (e.g., `sh` or `dash`)
+
+### ✅ Cross-Platform Tips
+- Save scripts with **LF line endings** (not CRLF)
+- Use `dos2unix rename_safe.sh` if editing on Windows
+- Avoid filenames > 255 chars to ensure portability
+- Test on target system before bulk renaming
 
 ## 📦 Example