From ba92b86e67ceadb48448587dbd8438f0bf75259e Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Thu, 29 Jan 2026 20:21:08 -0500
Subject: [PATCH] docs: update README with search feature documentation

- Document search capabilities in Media Management section
- Add API endpoint documentation for /api/media-items/search
- Include search behavior, ranking, and examples
- Document fuzzy search fallback for typos
---
 README.md | 52 +++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 41 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 5329966..a348659 100644
--- a/README.md
+++ b/README.md
@@ -40,17 +40,23 @@ A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and T
 - **Mobile-First Design**: Fully responsive interface for all devices
 - **HTMX Integration**: Dynamic interactions without page reloads
 
-### 📱 Media Management
-- **Universal Media Support**: Single system for all media types with unified interface
-- **Rich Metadata**: Automatic extraction of title, author, series, publisher, ISBN, tags
-- **ISBN Normalization**: Automatic ISBN format normalization (removes hyphens and spaces) supporting ISBN-10 and ISBN-13 formats
-- **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
-- **Background Scanning**: Automatic background scanning with configurable frequency per user
-- **Watch Mode**: Real-time file system monitoring for instant library updates
+ ### 📱 Media Management
+ - **Universal Media Support**: Single system for all media types with unified interface
+ - **Rich Metadata**: Automatic extraction of title, author, series, publisher, ISBN, tags
+ - **ISBN Normalization**: Automatic ISBN format normalization (removes hyphens and spaces) supporting ISBN-10 and ISBN-13 formats
+ - **Advanced Search**: 
+   - Partial matching search across title, author, series, tags, and contributors
+   - Automatic fuzzy search fallback when no partial matches found (handles typos and misspellings)
+   - Real-time search results with highlighted matches
+   - Keyboard navigation (↑↓ arrows, Enter to select, Escape to close)
+   - Respects library visibility settings
+ - **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
+ - **Background Scanning**: Automatic background scanning with configurable frequency per user
+ - **Watch Mode**: Real-time file system monitoring for instant library updates
 
 ## 🚀 Quick Start
 
@@ -142,6 +148,30 @@ GET /api/ebooks/{id}/highlights                   # Get user's highlights for eb
 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
+ ```
+
+#### Media Search (All Authenticated Users)
+```bash
+# Search media items across all visible libraries
+GET /api/media-items/search?q={query}
+
+# Query Parameters:
+# q (required): Search query (minimum 2 characters)
+# - Searches across: title, author, series, tags, contributors
+# - Partial matching: Case-insensitive substring search
+# - Fuzzy fallback: Automatic when no partial matches found
+# - Results ranked by relevance
+
+# Examples:
+GET /api/media-items/search?q=harry%20potter    # Search by title
+GET /api/media-items/search?q=rowling          # Search by author
+GET /api/media-items/search?q=hary%20poter     # Fuzzy search (handles typos)
+
+# Response:
+# - 200: Success (returns array of media items)
+# - 404: No results found
+# - 400: Missing or invalid query parameter
+# - 401: Unauthorized
 ```
 
 #### Library Management (Admin Only)