feat: Enhance installation script and documentation for Python tkinter support

This commit updates the `install.sh` script to include the installation of Python tkinter, which is required for the native folder picker functionality. Additionally, the README.md is modified to reflect this new requirement, providing installation instructions for various operating systems. The documentation is further enhanced with troubleshooting tips for users encountering issues with the folder picker, ensuring a smoother setup experience.

README.md

@@ -23,6 +23,8 @@ A fast, simple, and modern web application for organizing and tagging photos usi
 - **⚡ Batch Processing**: Process thousands of photos efficiently
 - **🎯 Unique Faces Filter**: Hide duplicate faces to focus on unique individuals
 - **🔄 Real-time Updates**: Live progress tracking and job status updates
+- **🌐 Network Path Support**: Browse and scan folders on network shares (UNC paths on Windows, mounted shares on Linux)
+- **📁 Native Folder Picker**: Browse button uses native OS folder picker with full absolute path support
 - **🔒 Privacy-First**: All data stored locally, no cloud dependencies
 
 ---
@@ -35,8 +37,9 @@ A fast, simple, and modern web application for organizing and tagging photos usi
 - **Node.js 18+ and npm**
 - **PostgreSQL** (required for both development and production)
 - **Redis** (for background job processing)
+- **Python tkinter** (for native folder picker in Scan tab)
 
-**Note:** The automated installation script (`./install.sh`) will install PostgreSQL and Redis automatically on Ubuntu/Debian systems.
+**Note:** The automated installation script (`./install.sh`) will install PostgreSQL, Redis, and Python tkinter automatically on Ubuntu/Debian systems.
 
 ### Installation
 
@@ -55,7 +58,7 @@ cd punimtag
 
 The script will:
 - ✅ Check prerequisites (Python 3.12+, Node.js 18+)
-- ✅ Install system dependencies (PostgreSQL, Redis) on Ubuntu/Debian
+- ✅ Install system dependencies (PostgreSQL, Redis, Python tkinter) on Ubuntu/Debian
 - ✅ Set up PostgreSQL databases (main + auth)
 - ✅ Create Python virtual environment
 - ✅ Install all Python dependencies
@@ -69,7 +72,13 @@ cd viewer-frontend
 npx prisma generate
 ```
 
-**Note:** On macOS or other systems, the script will skip system dependency installation. You'll need to install PostgreSQL and Redis manually.
+**Note:** On macOS or other systems, the script will skip system dependency installation. You'll need to install PostgreSQL, Redis, and Python tkinter manually.
+
+**Installing tkinter manually:**
+- **Ubuntu/Debian:** `sudo apt install python3-tk`
+- **RHEL/CentOS:** `sudo yum install python3-tkinter`
+- **macOS:** Usually included with Python, but if missing: `brew install python-tk` (if using Homebrew Python)
+- **Windows:** Usually included with Python installation
 
 #### Option 2: Manual Installation
 
@@ -375,6 +384,26 @@ rm data/punimtag.db
 # The schema will be recreated on next startup
 ```
 
+**Browse button returns 503 error or doesn't show folder picker:**
+This indicates that Python tkinter is not available. Install it:
+```bash
+# Ubuntu/Debian:
+sudo apt install python3-tk
+
+# RHEL/CentOS:
+sudo yum install python3-tkinter
+
+# Verify installation:
+python3 -c "import tkinter; print('tkinter available')"
+```
+
+**Note:** If running on a remote server without a display, you may need to set the DISPLAY environment variable or use X11 forwarding:
+```bash
+export DISPLAY=:0
+# Or for X11 forwarding:
+export DISPLAY=localhost:10.0
+```
+
 **Viewer frontend shows 0 photos:**
 - Make sure the database has photos (import them via admin frontend)
 - Verify `DATABASE_URL` in `viewer-frontend/.env` points to the correct database
@@ -492,6 +521,9 @@ punimtag/
 
 **Frontend:**
 - ✅ Scan tab UI with folder selection
+- ✅ **Native folder picker (Browse button)** - Uses tkinter for native OS folder selection
+- ✅ **Network path support** - Handles UNC paths (Windows: `\\server\share\folder`) and mounted network shares (Linux: `/mnt/nfs-share/photos`)
+- ✅ **Full absolute path handling** - Automatically normalizes and validates paths
 - ✅ Drag-and-drop file upload
 - ✅ Recursive scan toggle
 - ✅ Real-time job progress with progress bar