From 6f06da42a29832486196aa8e6314a49c1973d876 Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Tue, 27 Jan 2026 14:27:17 -0500
Subject: [PATCH] docs: Update README with enhanced API documentation and Bruno
 collection

- Add comprehensive Bruno API testing collection section with organized structure
- Document new role-based registration restrictions for admin user creation
- Update API endpoint documentation to reflect admin-only access for user management
- Clarify admin override capabilities for account deletion
- Enhance API authentication and authorization details throughout documentation
---
 README.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 54 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index ca15252..1f684a3 100644
--- a/README.md
+++ b/README.md
@@ -169,14 +169,61 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 - **Multiple Themes**: Beautiful dark themes with smooth transitions
 - **Responsive Design**: Mobile-first approach with optimized layouts for all screen sizes
 
+### Bruno API Testing Collection
+
+The `bruno/` directory contains a comprehensive API testing collection organized into logical subfolders:
+
+#### **Collection Structure**
+```
+bruno/user/
+├── auth/                    # Authentication requests
+│   ├── Login User.bru      # POST /api/auth/login
+│   └── Register User.bru   # POST /api/auth/register (with restrictions)
+├── admin/                   # Admin-only management
+│   ├── List Users.bru         # GET /api/auth/users (admin only)
+│   ├── Delete Account.bru       # DELETE /api/auth/account (admin override)
+│   └── Register Admin User.bru # POST /api/auth/register (admin creation)
+└── profile/                  # Profile management
+    ├── Get Profile.bru         # GET /api/auth/profile
+    ├── Update Profile.bru       # PUT /api/auth/profile
+    ├── Update Email.bru         # PUT /api/auth/email
+    ├── Update Password.bru       # PUT /api/auth/password
+    ├── Update Theme.bru         # PUT /api/auth/theme
+    └── Update Username.bru       # PUT /api/auth/username
+```
+
+#### **Setup Instructions**
+1. **Install Bruno**: https://www.usebruno.com/
+2. **Import Collection**: Open Bruno and import the `bruno/` folder
+3. **Select Environment**: Choose the "Bookmann" environment
+4. **Start Application**: `docker-compose up --build`
+5. **Authentication Flow**: Register → Login → Use Bearer token for protected routes
+
+#### **Security Features**
+- **Role-Based Registration**: Admin creation restrictions documented and tested
+- **Admin-Only Endpoints**: Proper access control for sensitive operations
+- **Token Management**: Automatic token persistence for workflow testing
+- **Error Handling**: Comprehensive status codes and error messages
+
+#### **Available Tests**
+- **User Registration**: Regular and admin account creation
+- **Authentication**: Login with email/username flexibility
+- **Profile Management**: Complete CRUD operations for user profiles
+- **Admin Operations**: User listing, account management with override
+- **Ebook Operations**: Full CRUD with ratings and progress tracking
+
 **Note**: The frontend is fully integrated into the Go backend using HTML templates and HTMX.
 
 ## API Endpoints
 
-### Auth (Public)
+### Authentication (Public & Protected)
 - `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"
+  - **Role Restrictions**: Role-based creation restrictions apply:
+    - First user always gets admin role regardless of request
+    - If any admin exists, only authenticated admins can create new admin accounts
+    - Regular users can always create user accounts
+    - Unauthenticated users can only create first admin, not subsequent admins
 - `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)
@@ -185,9 +232,13 @@ The application uses Go HTML templates for server-side rendering with HTMX for d
 - `PUT /api/auth/email` - Update email (requires JWT)
 - `PUT /api/auth/password` - Update password (requires JWT)
 - `DELETE /api/auth/account` - Delete user account (requires JWT)
+  - **Self-Deletion**: Users can delete their own accounts
+  - **Admin Override**: Admins can delete any user account via `?user_id={uuid}` parameter
   - **Protection**: Cannot delete the last admin account
 
-### Ebook Folders (Admin Only)
+### Admin Management (Admin Only)
+- `GET /api/auth/users` - List all users with complete info (admin only)
+- `DELETE /api/auth/account` - Delete own account or admin deletes other accounts with `user_id` parameter
 - `POST /api/auth/ebook-folders` - Add an ebook folder for scanning
 - `GET /api/auth/ebook-folders` - List configured ebook folders
 - `DELETE /api/auth/ebook-folders` - Remove an ebook folder