From d4feea15c5a22985c0c4d69d6423c0488b2a9f2f Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Mon, 26 Jan 2026 21:19:29 -0500
Subject: [PATCH] docs: Update README with admin system and role management

- Document first-user automatic admin assignment
- Update admin setup instructions with correct database name
- Add last-user protection documentation
- Update API endpoints with role field and protection notes
- Document Bruno collection reorganization and admin folder
- Clarify authentication flow and role-based access
- Update role permissions section with new protections
---
 README.md | 31 ++++++++++++++++++++++++-------
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index d26e460..5ae4381 100644
--- a/README.md
+++ b/README.md
@@ -87,18 +87,30 @@ echo "DBPASS=$DBPASS" >> .env
 
 ### Admin Setup
 
-After creating your first user account, you'll need to set up admin privileges:
+The first user who registers automatically becomes an admin. For subsequent users, you can manually set admin privileges:
 
 **Option 1: Direct Database Update**
 ```sql
--- Connect to the database and update user role
+-- Connect to 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
+docker exec -it bookmann_db psql -U postgres -d bookmann
+
+# Update user role
+UPDATE users SET role = 'admin' WHERE email = 'your-admin-email@example.com';
+
+# Exit psql
+\q
+```
+
+**Option 2: Using psql**
+```bash
+# Connect to the running database container
+docker exec -it bookmann-db-1 psql -U postgres -d bookmann
 
 # Update user role
 UPDATE users SET role = 'admin' WHERE email = 'your-admin-email@example.com';
@@ -111,6 +123,8 @@ UPDATE users SET role = 'admin' WHERE email = 'your-admin-email@example.com';
 - **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
+- **First User Protection**: The very first user to register automatically becomes admin
+- **Last User Protection**: The system prevents deletion of the last remaining user account
 
 **Option 2: Using docker-compose variables**
 1. Clone the repository
@@ -128,7 +142,7 @@ UPDATE users SET role = 'admin' WHERE email = 'your-admin-email@example.com';
 ### Database
 
 PostgreSQL runs on port 5432 with default credentials:
-- Database: ebookdb
+- Database: bookmann
 - User: postgres
 - Password: password
 
@@ -160,7 +174,9 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 ## API Endpoints
 
 ### Auth (Public)
-- `POST /api/auth/register` - Register new user
+- `POST /api/auth/register` - Register new user (role field: "user" or "admin")
+  - **Auto-Admin**: First user automatically gets admin role
+  - **Role Validation**: Subsequent users can specify "user" or "admin"
 - `POST /api/auth/login` - Login user (email or username)
 - `GET /api/auth/profile` - Get user profile (requires JWT)
 - `PUT /api/auth/profile` - Update user profile (first_name, last_name) (requires JWT)
@@ -169,6 +185,7 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 - `PUT /api/user/email` - Update email (requires JWT)
 - `PUT /api/user/password` - Update password (requires JWT)
 - `DELETE /api/user/account` - Delete user account (requires JWT)
+  - **Protection**: Cannot delete the last user account
 
 ### Ebook Folders (Admin Only)
 - `POST /api/auth/ebook-folders` - Add an ebook folder for scanning
@@ -182,7 +199,7 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 ### 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)
+- `POST /api/ebooks` - Create new ebook (admin only, tracks admin who added it)
 - `PUT /api/ebooks/:id` - Update ebook (admin only)
 - `DELETE /api/ebooks/:id` - Delete ebook (admin only)
 
@@ -409,4 +426,4 @@ Use the included Bruno collection in the `bruno/` directory for testing the API:
 
 ## License
 
-GPL-3.0
\ No newline at end of file
+GPL-3.0