From ea2e24d0de84a0f8b8a3a7f6cfb5609723a96b1e Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Wed, 28 Jan 2026 15:43:48 -0500
Subject: [PATCH] docs: update README for notes and highlights functionality

- Add notes and highlights to Media Management features section
- Document complete API endpoints for annotations (CRUD operations)
- Update database schema documentation with new tables
- Add backward compatibility endpoints for existing ebook API
- Update Bruno collection structure to show new test directories
- Document highlight-note association and color customization features
- Remove temporary DOCUMENTATION_UPDATES.md after merging content
---
 README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 48 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6488db6..79ad59d 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,8 @@ A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and T
 - **Rich Metadata**: Automatic extraction of title, author, series, publisher, ISBN, tags
 - **Advanced Rating**: 5-star system with half-star precision (1-10 scale)
 - **Reading Progress**: User-specific progress tracking with current page and total pages
+- **Notes & Highlights**: Personal annotations and text highlighting with color customization
+- **Highlight Notes**: Link highlights to detailed notes for comprehensive annotations
 - **Library Statistics**: Media count and usage statistics per library
 
 ## 🚀 Quick Start
@@ -97,6 +99,34 @@ UPDATE users SET role = 'admin' WHERE email = 'user@example.com';
 
 ### API Endpoints
 
+#### Notes & Highlights (All Authenticated Users)
+```bash
+# Media Notes
+GET /api/media-items/{id}/notes              # Get user's notes for media
+POST /api/media-items/{id}/notes             # Create new note
+GET /api/media-items/{id}/notes/{noteId}   # Get specific note
+PUT /api/media-items/{id}/notes/{noteId}    # Update note
+DELETE /api/media-items/{id}/notes/{noteId} # Delete note
+
+# Media Highlights  
+GET /api/media-items/{id}/highlights                   # Get user's highlights for media
+POST /api/media-items/{id}/highlights                  # Create new highlight
+GET /api/media-items/{id}/highlights/{highlightId}      # Get specific highlight
+PUT /api/media-items/{id}/highlights/{highlightId}       # Update highlight
+DELETE /api/media-items/{id}/highlights/{highlightId}   # Delete highlight
+
+# Ebook Compatibility (Backward Compatible)
+GET /api/ebooks/{id}/notes              # Get user's notes for ebook
+POST /api/ebooks/{id}/notes             # Create new ebook note
+PUT /api/ebooks/{id}/notes/{noteId}    # Update ebook note
+DELETE /api/ebooks/{id}/notes/{noteId} # Delete ebook note
+
+GET /api/ebooks/{id}/highlights                   # Get user's highlights for ebook
+POST /api/ebooks/{id}/highlights                  # Create new ebook highlight
+PUT /api/ebooks/{id}/highlights/{highlightId}       # Update ebook highlight
+DELETE /api/ebooks/{id}/highlights/{highlightId}   # Delete ebook highlight
+```
+
 #### Library Management (Admin Only)
 ```bash
 # Create new library
@@ -131,6 +161,14 @@ GET /api/libraries/visible
 
 # Browse media in library
 GET /api/media-items?library_id={library_id}&limit=20&offset=0
+
+# Media Progress & Ratings
+GET /api/media-items/{id}/progress     # Get reading progress
+PUT /api/media-items/{id}/progress     # Update reading progress
+GET /api/media-items/{id}/rating       # Get user rating
+POST /api/media-items/{id}/rating      # Create/update rating
+PUT /api/media-items/{id}/rating       # Update rating
+DELETE /api/media-items/{id}/rating   # Delete rating
 ```
 
 ## 📖 Media Support
@@ -188,7 +226,8 @@ services:
 
 ### Database Schema
 - **Multi-Library Architecture**: Libraries, library types, folders, visibility tables
-- **Backward Compatibility**: Views maintain existing API contracts
+- **Annotations System**: Notes, highlights with position tracking and color customization
+- **Backward Compatibility**: Views maintain existing API contracts for ebooks
 - **Type Safety**: pgx v5 with proper error handling
 - **Migration Ready**: Schema designed for easy future extensions
 
@@ -203,6 +242,8 @@ bruno/
 ├── admin/          # Admin-only operations  
 ├── library/         # Library management
 ├── media-items/    # Media content browsing
+├── notes/          # Notes API testing
+├── highlights/     # Highlights API testing
 └── collection.bru  # Main dashboard
 ```
 
@@ -306,8 +347,14 @@ library_folders        # Folders per library
 library_visibility     # User library access control
 media_items           # All media content (replaces ebooks table)
 media_ratings         # User ratings for media items
+media_notes           # User notes on media items
+media_highlights      # User highlights with optional note links
 reading_progress       # User reading progress
 users                 # User accounts and profiles
+
+# Backward Compatibility Views
+ebook_notes           # Notes view for ebook API compatibility
+ebook_highlights      # Highlights view for ebook API compatibility
 ```
 
 ## 🎯 Future Roadmap