docs: restructure documentation into audience-based portals

BREAKING CHANGE: Documentation URLs have changed New structure: - user/ - End-user documentation (device setup, sync guides, frontend) - developer/ - Developer documentation (API reference, protocols, specs) - operations/ - Operations documentation (deployment, troubleshooting) - contributing/ - Contribution guides Changes: - Created portal INDEX.md files for each audience section - Moved device guides to user/devices/ (kobo-setup.md, koreader-setup.md) - Moved API docs to developer/ (api-reference.md, collections-api.md) - Moved sync guide to user/sync-guide.md - Moved troubleshooting to operations/troubleshooting.md - Moved all split API docs to developer/api/ - Renamed protocol files (kobo-protocol.md, koreader-protocol.md) - Added placeholder user guides (frontend, user-areas, settings, admin) - Updated all internal links to new paths - Updated Go code (http_handler.go, navigation.go) for new paths - Updated main INDEX.md for audience-based navigation Benefits: - Clear separation of user and developer documentation - Scalable structure for future user guide expansion - Better organization and discoverability - Audience-specific landing pages Related to DOCS_IMPLEMENTATION_PLAN.md Phase 2 completion
2026-02-02 15:58:34 -05:00
parent ece90c0f1f
commit 253f56399d
76 changed files with 372 additions and 207 deletions
@@ -0,0 +1,545 @@
+# Bookhoard Universal Sync - User Guide
+
+## Table of Contents
+1. [What is Universal Sync?](#what-is-universal-sync)
+2. [Supported Devices](#supported-devices)
+3. [Getting Started](#getting-started)
+4. [Device Setup](#device-setup)
+5. [Using Sync Features](#using-sync-features)
+6. [Book Matching](#book-matching)
+7. [Managing Conflicts](#managing-conflicts)
+8. [Best Practices](#best-practices)
+
+---
+
+## What is Universal Sync?
+
+**Universal Sync** is Bookhoard's cross-platform synchronization system that keeps your reading progress, highlights, and notes in sync across all your devices - automatically and in real-time.
+
+### Key Features
+
+🔄 **Automatic Sync** - Your reading progress syncs automatically when you turn pages
+
+📱 **Multi-Platform** - Works with web browsers, KOReader, Kobo devices, and mobile apps
+
+📍 **Precise Location Tracking** - Supports EPUB CFI, page numbers, percentages, and character offsets
+
+⚡ **Real-Time Updates** - See your progress update across all devices instantly
+
+🔒 **Secure** - No passwords on devices, web-based authentication only
+
+📴 **Offline Support** - Queue changes when offline, sync when reconnected
+
+---
+
+## Supported Devices
+
+### Currently Supported ✅
+
+| Platform | Status | Sync Method | Notes |
+|----------|--------|-------------|-------|
+| **Web Browser** | ✅ Fully Supported | Real-time WebSocket | Any modern browser |
+| **KOReader** | ✅ Fully Supported | Wi-Fi (Calibre-compatible) | Kindle, Kobo, PocketBook, etc. |
+| **Kobo Devices** | ✅ Fully Supported | Wi-Fi (Kobo API-compatible) | Clara, Libra, Sage, etc. |
+
+### Coming Soon 🚧
+
+| Platform | Expected Release |
+|----------|------------------|
+| **Mobile Apps** | Q2 2026 |
+| **Kindle Devices** | Q3 2026 |
+| **Remarkable Tablet** | Q4 2026 |
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+1. **Bookhoard Server** - Self-hosted instance running and accessible
+2. **Network Connection** - Devices must be able to reach your Bookhoard server
+3. **User Account** - Created and logged in to Bookhoard web interface
+
+### Quick Start
+
+1. **Set up your first device** - See [Device Setup](#device-setup) below
+2. **Start reading** - Open any book in the web interface or on your device
+3. **Turn pages** - Progress syncs automatically
+4. **Switch devices** - Pick up any other device - your progress is there!
+
+---
+
+## Device Setup
+
+For detailed device configuration instructions, see the appropriate setup guide:
+
+- **[Kobo Setup Guide](devices/kobo-setup.md)** - Kobo e-reader configuration
+- **[KOReader Setup Guide](devices/koreader-setup.md)** - KOReader configuration
+
+### Quick Overview
+
+**Registration Process**:
+1. Register device in Bookhoard web interface (Settings → Devices)
+2. Approve device via QR code or approval URL
+3. Configure sync settings on your device
+4. Start reading - progress syncs automatically!
+
+**Device Management**:
+```
+Settings → Devices
+```
+
+You can:
+- View all your registered devices
+- See last sync time and status
+- Disable or remove devices
+- View unlinked books that need matching
+- Manage file aliases
+
+---
+
+## Book Matching
+
+### What is Book Matching?
+
+When devices sync books, Bookhoard tries to automatically match them using:
+- **SHA-256 hash** (most reliable) - Content-based fingerprint
+- **ISBN** - Standard book identifier
+- **UUID** - Unique identifier from EPUB metadata
+- **Title + Author** (fallback) - Last resort matching
+
+### Unlinked Books
+
+Sometimes a book on your device can't be automatically matched to your library. This happens when:
+- The book was side-loaded (not downloaded via Bookhoard)
+- The file format was converted (EPUB → KEPUB)
+- The metadata doesn't match exactly
+
+### Viewing Unlinked Books
+
+```
+Settings → Devices → Select Device → View Unlinked Books
+```
+
+### Resolving Unlinked Books
+
+1. **Auto-Link** - Automatically link books with 80%+ confidence
+2. **Get Suggestions** - Review potential matches before linking
+3. **Manual Link** - Choose the correct match yourself
+
+### Book Matching Priority
+
+1. **Bookhoard UUID** - 100% confidence
+2. **OPF UUID** - 95% confidence
+3. **SHA-256 hash** - 90% confidence
+4. **OPF identifier** - 85% confidence
+5. **ISBN/ASIN** - 80% confidence
+6. **Title + Author + File Size** - 50% confidence
+
+---
+
+## Managing Conflicts
+
+### Reading Progress
+
+**What Syncs**:
+- Current page number
+- Reading percentage
+- Chapter progress
+- EPUB CFI (for EPUB files)
+- Last read timestamp
+- Reading position (viewport, zoom, scroll)
+
+**How It Works**:
+```
+You turn page → Device sends progress → Server updates database
+                                    ↓
+                            Broadcasts to all your devices
+                                    ↓
+                    Other devices update their display
+```
+
+**Supported Progress Types**:
+- **EPUB/MOBI**: Percentage + EPUB CFI + Chapter
+- **PDF/DJVU**: Page number + Viewport position
+- **CBZ/CBR**: Page number + Panel coordinates
+
+### Highlights & Notes
+
+**What Syncs**:
+- Highlighted text
+- Notes and annotations
+- Bookmark locations
+- Colors and formatting
+- Chapter/paragraph references
+
+**Universal Location References**:
+All highlights are stored with multiple location types:
+- Page:offset (traditional)
+- EPUB CFI (EPUB files)
+- Percentage (0-100%)
+- Character offset (exact position)
+- Chapter references
+
+This ensures your highlights work across all devices, even with different page counts!
+
+### Bookmarks
+
+**What Syncs**:
+- Bookmark locations
+- Bookmark titles
+- Date created
+- Reading position context
+
+---
+
+## Sync Modes
+
+### Immediate Mode (Default)
+
+**Best For**: Normal reading, page turns
+
+**Behavior**:
+- Syncs every page turn
+- Real-time updates
+- Low latency
+- Higher bandwidth usage
+
+**Recommended Settings**:
+- Auto-sync: ON
+- Sync frequency: Every page turn
+
+### Checkpoint Mode
+
+**Best For**: Slow connections, battery saving
+
+**Behavior**:
+- Batches changes
+- Syncs every 5 minutes or when connection allows
+- Lower bandwidth
+- Better for offline reading
+
+**Recommended Settings**:
+- Auto-sync: ON
+- Sync frequency: Checkpoint mode
+
+---
+
+## Offline Support
+
+### How Offline Sync Works
+
+1. **Offline Reading**:
+   - Read normally without connection
+   - All progress tracked locally
+
+2. **Queue Changes**:
+   - Progress changes queued automatically
+   - Annotations saved locally
+   - Up to 100 items in offline queue
+
+3. **Reconnection**:
+   - Connect to Wi-Fi
+   - Queue processes automatically
+   - Priority items first (book completion, notes)
+   - All devices updated
+
+### Offline Indicators
+
+**In Web Interface**:
+- Yellow status icon: Device offline
+- Last seen timestamp
+- "Pending sync" badge on books
+
+**On Devices**:
+- Sync icon: Gray = offline
+- Sync icon: Blue = syncing
+- Sync icon: Green = synced
+
+---
+
+## Troubleshooting
+
+### Sync Not Working
+
+**Symptoms**: Progress not updating across devices
+
+**Solutions**:
+1. Check device is online: `Settings → Devices`
+2. Verify sync is enabled for the device
+3. Check sync URL is correct
+4. Ensure device has network connection
+5. Try manual sync: Open book → Menu → Sync Now
+
+### "Device Not Found" Error
+
+**Cause**: Device not registered or authorization revoked
+
+**Solutions**:
+1. Re-register the device
+2. Check device hasn't been removed
+3. Verify correct device type selected
+
+### "Rate Limit Exceeded" Error
+
+**Cause**: Too many sync requests
+
+**Solutions**:
+1. Wait a few seconds
+2. Switch to checkpoint mode
+3. Contact admin to increase limits
+
+### Conflicts Detected
+
+**Symptoms**: "Sync conflict" notification
+
+**Cause**: Same book being read on multiple devices simultaneously
+
+**Solutions**:
+1. Go to `Settings → Conflicts`
+2. Review both device progress
+3. Choose which device's progress to keep
+4. Or choose "Merge" (keeps furthest progress)
+
+### High Battery Usage
+
+**Cause**: Immediate sync mode with frequent page turns
+
+**Solutions**:
+1. Switch to checkpoint mode
+2. Increase sync interval
+3. Use Wi-Fi instead of cellular (for mobile)
+
+---
+
+## Best Practices
+
+### For Optimal Performance
+
+✅ **DO**:
+- Use checkpoint mode when on cellular data
+- Keep device firmware updated
+- Use Wi-Fi when available
+- Approve only devices you own
+- Regularly check conflict resolution
+
+❌ **DON'T**:
+- Read same book on multiple devices simultaneously
+- Ignore conflict notifications
+- Register public/shared devices
+- Exceed device limits (max 10 per user)
+
+### Organizing Your Library
+
+**For Best Sync Experience**:
+- Use consistent metadata (titles, authors)
+- Avoid duplicate books in library
+- Match files by ISBN when possible
+- Use clean file structure
+
+### Managing Multiple Devices
+
+**Recommended Setup**:
+- **Primary Device**: KOReader on e-reader
+- **Secondary Device**: Web browser (work/home)
+- **Mobile Device**: Phone app (commute)
+
+**Sync Strategy**:
+1. Read mainly on primary device
+2. Check progress on web/secondary devices
+3. Let auto-sync handle updates
+4. Resolve conflicts promptly
+
+---
+
+## Advanced Features
+
+### Conflict Resolution
+
+**Automatic Resolution**:
+- Most recent progress wins
+- Timestamp-based comparison
+- 5-minute window for conflict detection
+
+**Manual Resolution**:
+```
+Settings → Conflicts → Select conflict → Choose winner
+```
+
+**Options**:
+- **Keep Device A**: Use this device's progress
+- **Keep Device B**: Use other device's progress
+- **Merge**: Keep furthest progress (combination)
+- **Auto-Resolve Future**: Always prefer this device
+
+### Sync Queue Management
+
+**View Queue Status**:
+```
+Settings → Devices → Select Device → View Queue
+```
+
+**Queue Stats**:
+- Pending: Waiting to sync
+- Processing: Currently syncing
+- Failed: Retry scheduled
+- Completed: Successfully synced
+
+**Manual Actions**:
+- **Retry All**: Retry all failed items
+- **Clear Queue**: Remove all pending items
+- **Priority Sync**: Sync specific book immediately
+
+### Reading History
+
+**Automatic Tracking**:
+- Every sync session logged
+- Time spent reading calculated
+- Pages read tracked
+- Device used recorded
+
+**View History**:
+```
+Book → Reading History
+```
+
+**Privacy**:
+- Only you can see your history
+- History kept for 365 days
+- Exportable for backup
+
+---
+
+## Security & Privacy
+
+### Device Authentication
+
+**Secure by Design**:
+- ✅ No passwords stored on devices
+- ✅ Web-based approval required
+- ✅ Unique tokens per device
+- ✅ Revocable at any time
+- ✅ Token encryption in transit
+
+### Data Protection
+
+**What We Store**:
+- Reading progress (page, percentage)
+- Highlights and notes
+- Device identifiers
+- Sync timestamps
+
+**What We DON'T Store**:
+- Passwords on devices
+- Reading content (your books)
+- Unencrypted personal data
+- Location data (GPS)
+
+### Access Control
+
+**Your Data**:
+- Only you can see your progress
+- Admins cannot read your annotations
+- Shared only with devices you approve
+
+**Device Access**:
+- Each device sees only your libraries
+- Devices cannot access other users
+- Revoking removes all access
+
+---
+
+## Performance Tips
+
+### For Faster Sync
+
+1. **Use 5GHz Wi-Fi** - Faster than 2.4GHz
+2. **Keep server nearby** - Low latency = better sync
+3. **Regular updates** - Keeps firmware current
+4. **Checkpoint mode** - For batch processing
+
+### For Better Battery Life
+
+1. **Checkpoint mode** - Fewer sync requests
+2. **Wi-Fi only** - Disable cellular
+3. **Increase sync interval** - Fewer updates
+4. **Close when not reading** - Reduces background activity
+
+---
+
+## FAQ
+
+### General Questions
+
+**Q: Does sync work with all book formats?**
+A: Yes! EPUB, PDF, MOBI, CBZ, CBR and more.
+
+**Q: Can multiple users share a device?**
+A: No, devices are tied to individual accounts for security.
+
+**Q: What happens if I delete a book?**
+A: All sync data for that book is removed from the server.
+
+**Q: Can I export my reading data?**
+A: Yes! Settings → Export → Download sync data.
+
+**Q: Does sync work over the internet?**
+A: Yes, if your server is publicly accessible with HTTPS.
+
+**Q: How much data does sync use?**
+A: Approximately 1KB per page turn, 50KB per annotation.
+
+### Technical Questions
+
+**Q: How does sync handle different page counts?**
+A: Uses percentage and EPUB CFI for universal positioning.
+
+**Q: Can I sync with Calibre anymore?**
+A: Yes! KOReader sync is Calibre-compatible.
+
+**Q: What if I lose my device?**
+A: Revoke it in settings and register a new one.
+
+**Q: Is sync end-to-end encrypted?**
+A: Yes, HTTPS/TLS 1.3 for all sync traffic.
+
+---
+
+## Getting Help
+
+### Documentation
+
+- **API Docs**: `/docs/api.md`
+- **Device Guides**: `/docs/devices/`
+- **Self-Hosting**: `/docs/install.md`
+
+### Support
+
+- **Issues**: Report bugs at GitHub Issues
+- **Discussions**: Join GitHub Discussions
+- **Email**: support@bookhoard.example.com
+
+### Community
+
+- **Forum**: community.bookhoard.example.com
+- **Matrix**: #bookhoard:matrix.org
+- **Discord**: discord.gg/bookhoard
+
+---
+
+## Changelog
+
+### Version 1.0.0 (January 2026)
+- ✅ Initial release
+- ✅ KOReader sync support
+- ✅ Kobo device support
+- ✅ Web sync support
+- ✅ Conflict resolution
+- ✅ Offline queue
+- ✅ Real-time WebSocket sync
+
+---
+
+**Last Updated**: January 31, 2026  
+**Version**: 1.0.0  
+**License**: MIT