docs: Update documentation for role-based access control

- Update README.md with admin system documentation
- Add admin setup instructions and role permissions
- Update API endpoint documentation with access requirements
- Update Bruno collection to reflect admin-only operations
- Document shared library concept and security model
- Add comprehensive admin setup guide

README.md

@@ -5,21 +5,24 @@ A self-hosted ebook management system built with Go, PostgreSQL, HTMX, and Tailw
 ## ✨ Features
 
 - **🔒 Multi-User Authentication**: Complete user system with registration/login, JWT-based sessions, and bcrypt password hashing
+- **👑 Admin-Based Control**: Role-based access control with admin privileges for folder and ebook management
 - **👤 User Profile Management**: Update profile information, username, email, password, and account deletion
-- **⚙️ Scan Settings**: Configure scan frequency and auto-scan options per user
+- **⚙️ Scan Settings**: Configure scan frequency and auto-scan options per user (admin only)
 - **✅ Server-Side Validation**: Comprehensive input validation with detailed error messages
 - **🌙 Multiple Themes**: 11 beautiful themes including Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, and Catppuccin variants (Mocha, Macchiato, Frappé, Latte) with user preferences saved to database
 - **🎨 Theme Persistence**: User theme choices sync between browser and server
 - **📖 Reading Progress**: User-specific reading progress tracking
 - **⭐ Advanced Rating System**: 5-star rating with half-star precision, dialog-based input, and zero-rating fallback
-- **📁 Multiple Folder Support**: Configure multiple ebook folders per user for comprehensive library management
-- **🔍 Enhanced Scanner**: Intelligent ebook discovery with Calibre folder structure support and comprehensive metadata extraction
-- **👀 Real-Time Monitoring**: File system monitoring for automatic ebook detection and updates
+- **📁 Folder Management**: Configure and manage ebook folders (admin only)
+- **🔍 Enhanced Scanner**: Intelligent ebook discovery with Calibre folder structure support and comprehensive metadata extraction (admin only)
+- **👀 Real-Time Monitoring**: File system monitoring for automatic ebook detection and updates (admin only)
 - **📚 Rich Metadata**: Automatic extraction of ebook metadata (title, author, description, publisher, series, ISBN, tags) from EPUB files with Calibre-specific support
 - **🏛️ Calibre Integration**: Full support for Calibre folder structures and metadata (calibre:series, calibre:series_index)
 - **📂 Smart Folder Detection**: Automatically detects Author/Book, Author/Series/Book, and Calibre naming conventions
 - **🔄 Subfolder Scanning**: Recursively scans subdirectories with proper folder structure analysis
 - **🔧 RESTful API**: Clean API endpoints with JWT authentication and proper error handling
+- **🛡️ Role-Based Security**: Admin users can manage folders and ebook metadata; regular users can view, rate, and track reading progress
+- **📋 Shared Library**: All users can view the complete ebook collection, with admin tracking of who added each book
 - **🐳 Docker Ready**: Single-container deployment with PostgreSQL
 - **🧪 API Testing**: Complete Bruno collection for testing all endpoints
 - **📱 Responsive Design**: Mobile-first responsive interface using Tailwind CSS
@@ -70,18 +73,45 @@ echo "DBPASS=$DBPASS" >> .env
 ### Running the Application
 
 **Option 1: Using .env file**
-1. Clone the repository
+1. Clone repository
 2. Set up environment:
-   ```bash
-   cp .env.example .env
-   # Edit .env with your secure values
-   ```
+    ```bash
+    cp .env.example .env
+    # Edit .env with your secure values
+    ```
 3. Run the application:
-   ```bash
-   docker-compose up --build
-   ```
+    ```bash
+    docker-compose up --build
+    ```
 4. Access the application at http://localhost:8765
 
+### Admin Setup
+
+After creating your first user account, you'll need to set up admin privileges:
+
+**Option 1: Direct Database Update**
+```sql
+-- Connect to the database and update user role
+UPDATE users SET role = 'admin' WHERE email = 'your-admin-email@example.com';
+```
+
+**Option 2: Using psql**
+```bash
+# Connect to the running database container
+docker exec -it bookmann-db-1 psql -U postgres -d ebookdb
+
+# Update user role
+UPDATE users SET role = 'admin' WHERE email = 'your-admin-email@example.com';
+
+# Exit psql
+\q
+```
+
+**Role Permissions:**
+- **Admin Users**: Can add/edit/delete folders, scan ebooks, modify/delete any ebook metadata
+- **Regular Users**: Can view all ebooks, rate books, track reading progress, manage their profile
+- **Shared Library**: All users see the same ebook collection, but only admins can modify it
+
 **Option 2: Using docker-compose variables**
 1. Clone the repository
 2. Set environment variables directly:
@@ -140,21 +170,21 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 - `PUT /api/user/password` - Update password (requires JWT)
 - `DELETE /api/user/account` - Delete user account (requires JWT)
 
-### Ebook Folders (Protected)
+### Ebook Folders (Admin Only)
 - `POST /api/auth/ebook-folders` - Add an ebook folder for scanning
-- `GET /api/auth/ebook-folders` - List user's configured ebook folders
+- `GET /api/auth/ebook-folders` - List configured ebook folders
 - `DELETE /api/auth/ebook-folders` - Remove an ebook folder
 
-### Library Settings (Protected)
+### Library Settings (Admin Only)
 - `PUT /api/library/scan-settings` - Update scan frequency and auto-scan settings
 - `GET /api/library/scan-settings` - Get current scan settings
 
-### Ebooks (Protected)
-- `GET /api/ebooks` - List ebooks
-- `GET /api/ebooks/:id` - Get specific ebook
-- `POST /api/ebooks` - Create new ebook
-- `PUT /api/ebooks/:id` - Update ebook
-- `DELETE /api/ebooks/:id` - Delete ebook
+### Ebooks (Mixed Access)
+- `GET /api/ebooks` - List ebooks (all authenticated users)
+- `GET /api/ebooks/:id` - Get specific ebook (all authenticated users)
+- `POST /api/ebooks` - Create new ebook (admin only)
+- `PUT /api/ebooks/:id` - Update ebook (admin only)
+- `DELETE /api/ebooks/:id` - Delete ebook (admin only)
 
 ### Reading Progress (Protected)
 - `GET /api/ebooks/:id/progress` - Get reading progress
@@ -167,8 +197,8 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 - `DELETE /api/ebooks/:id/rating` - Delete user's rating
 - `GET /api/ebooks/:id/ratings` - Get all ratings for ebook
 
-### Scanner (Protected)
-- `POST /api/scanner/scan` - Scan user's configured ebook folders (supports optional folder_paths parameter for testing)
+### Scanner (Admin Only)
+- `POST /api/scanner/scan` - Scan configured ebook folders (supports optional folder_paths parameter for testing)
 - `POST /api/scanner/start` - Start real-time monitoring of configured folders
 - `POST /api/scanner/stop` - Stop real-time folder monitoring
 
@@ -211,9 +241,10 @@ Bookmann includes an intelligent ebook scanner with full Calibre integration and
 
 ### Setting Up Folders
 
-1. **Add Folders**: Use `POST /api/auth/ebook-folders` to add ebook folders to your account
+1. **Add Folders**: Use `POST /api/auth/ebook-folders` to add ebook folders (admin only)
 2. **Supported Formats**: EPUB (full metadata), PDF (basic), MOBI, AZW3, FB2, TXT
 3. **Calibre Integration**: Automatically recognizes Calibre folder structures and metadata
+4. **Admin Privileges**: Only administrators can configure folders and initiate scans
 
 ### Folder Structure Support
 
@@ -327,6 +358,16 @@ Use the included Bruno collection in the `bruno/` directory for testing the API:
 
 ## 🎨 Recent Enhancements
 
+### 🔒 Admin-Based Control System
+- **Role-Based Access**: Implemented complete role system with 'admin' and 'user' roles
+- **Admin Middleware**: Created authorization middleware for protected operations
+- **Folder Management**: Only admins can add/edit/delete ebook folders and configure scanner
+- **Ebook CRUD**: Only admins can create, update, or delete ebook metadata
+- **Scanner Control**: Only admins can initiate scans and control file system monitoring
+- **Shared Library**: All users can view ebooks, but only admins can modify the library
+- **Admin Tracking**: Ebooks track which admin added them via `added_by_admin_id` field
+- **Frontend Protection**: Admin controls only visible to users with admin role
+
 ### Major Scanner Improvements
 - **Calibre Integration**: Full support for Calibre folder structures and metadata fields
 - **Smart Folder Detection**: Automatically recognizes Author/Book, Author/Series/Book patterns