Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

Rename project documentation: Bookmann → Bookhoard

Browse Source 
Documentation updates:
- Update README.md title and all references
- Update PROJECT_GUIDELINES.md title and guidelines
- Update all documentation files in docs/ directory
- Update device setup guides (Kobo, KOReader)
- Update API and architecture documentation
- Update completion summaries and progress reports

This is part 5 of the project rename to Bookhoard.
This commit is contained in:
john-okeefe
2026-02-01 16:12:12 -05:00
parent 96825e3bc2
commit 67629b0c14
15 changed files with 184 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PROJECT_GUIDELINES.md
+1 -1
View File
@@ -1,4 +1,4 @@
# Combined Project Guidelines for Bookmann # Combined Project Guidelines for Bookhoard
## 🚨 CRITICAL PROHIBITIONS (Never violate these) ## 🚨 CRITICAL PROHIBITIONS (Never violate these)
README.md
+1 -1
View File
@@ -1,4 +1,4 @@
# 📚 Bookmann # 📚 Bookhoard
A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and Tailwind CSS featuring multiple library support, beautiful dark themes, and comprehensive media management. A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and Tailwind CSS featuring multiple library support, beautiful dark themes, and comprehensive media management.
docs/API_REFERENCE.md
+2 -2
View File
@@ -1,6 +1,6 @@
# Bookmann API Reference # Bookhoard API Reference
Complete API documentation for Bookmann v1.0 with Universal Cross-Platform Sync support. Complete API documentation for Bookhoard v1.0 with Universal Cross-Platform Sync support.
## Table of Contents ## Table of Contents
docs/COLLECTIONS_API.md
+4 -4
View File
@@ -378,9 +378,9 @@ Collections allow you to organize your books into custom categories with:
``` ```
**Sync Directions**: **Sync Directions**:
- `bidirectional`: Sync both ways between Bookmann and device - `bidirectional`: Sync both ways between Bookhoard and device
- `book_to_device`: Bookmann → Device only - `book_to_hoard`: Bookhoard → Device only
- `device_to_book`: Device → Bookmann only - `device_to_hoard`: Device → Bookhoard only
- `none`: No sync (mapping only) - `none`: No sync (mapping only)
**Response** (201 Created): Mapping object **Response** (201 Created): Mapping object
@@ -399,7 +399,7 @@ Collections allow you to organize your books into custom categories with:
```json ```json
{ {
"device_shelf_name": "Science Fiction", "device_shelf_name": "Science Fiction",
"sync_direction": "book_to_device" "sync_direction": "book_to_hoard"
} }
``` ```
docs/Code/bookmann/IMPLEMENTATION_PLAN.md
+44 -44
View File
@@ -1,4 +1,4 @@
# Bookmann Implementation Plan # Bookhoard Implementation Plan
## Executive Summary ## Executive Summary
@@ -33,7 +33,7 @@ This plan implements a complete cross-device ebook management system with three
``` ```
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
│ Bookmann Server │ │ Bookhoard Server │
│ ┌──────────────────────────────────────────────────────────────┐ │ │ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Layer 1: Universal Book Identification │ │ │ │ Layer 1: Universal Book Identification │ │
│ │ SHA-256, UUID, ISBN, ASIN, OPF identifiers │ │ │ │ SHA-256, UUID, ISBN, ASIN, OPF identifiers │ │
@@ -52,7 +52,7 @@ This plan implements a complete cross-device ebook management system with three
│ │ Per-device OPDS feeds (Kobo, KOReader, etc.) │ │ │ │ Per-device OPDS feeds (Kobo, KOReader, etc.) │ │
│ │ Format conversion (EPUB → KEPUB on-the-fly) │ │ │ │ Format conversion (EPUB → KEPUB on-the-fly) │ │
│ │ Dual hash storage (original + converted) │ │ │ │ Dual hash storage (original + converted) │ │
│ │ ContentId mapping (Bookmann UUID ↔ Device ID) │ │ │ │ ContentId mapping (Bookhoard UUID ↔ Device ID) │ │
│ └──────────────────────────────────────────────────────────────────────┘ │ │ └──────────────────────────────────────────────────────────────────────┘ │
│ ↓ delivers books + provides IDs │ │ ↓ delivers books + provides IDs │
│ ┌──────────────────────────────────────────────────────────────────────┐ │ │ ┌──────────────────────────────────────────────────────────────────────┐ │
@@ -70,7 +70,7 @@ This plan implements a complete cross-device ebook management system with three
| Platform | Access Method | Purpose | Why This Method | | Platform | Access Method | Purpose | Why This Method |
|-----------|----------------|---------|-----------------| |-----------|----------------|---------|-----------------|
| **Kobo** | OPDS catalog | Kobo has built-in OPDS client, no custom Bookmann client exists | | **Kobo** | OPDS catalog | Kobo has built-in OPDS client, no custom Bookhoard client exists |
| **KOReader** | OPDS catalog (primary) + Sidecar + Internal API | KOReader has OPDS client, also supports plugins/sidecars for enhanced features | | **KOReader** | OPDS catalog (primary) + Sidecar + Internal API | KOReader has OPDS client, also supports plugins/sidecars for enhanced features |
| **Web App** | Internal API directly | We own and control web app, can make direct API calls efficiently | | **Web App** | Internal API directly | We own and control web app, can make direct API calls efficiently |
| **Mobile App** | Internal API directly | We own and control mobile app, can make direct API calls efficiently | | **Mobile App** | Internal API directly | We own and control mobile app, can make direct API calls efficiently |
@@ -78,7 +78,7 @@ This plan implements a complete cross-device ebook management system with three
### Key Design Principles ### Key Design Principles
1. **Canonical UUID Always Wins** - Bookmann UUID (from `media_items.id`) is always used for progress tracking, never SHA-256. SHA-256 is only for matching books across devices, preventing format conversion issues. 1. **Canonical UUID Always Wins** - Bookhoard UUID (from `media_items.id`) is always used for progress tracking, never SHA-256. SHA-256 is only for matching books across devices, preventing format conversion issues.
2. **Collections ≠ Device Inventory** - Collections are organizational metadata (like "smart playlists"). Books can be in collections without being on any device. Progress/annotations sync independently of collection membership. 2. **Collections ≠ Device Inventory** - Collections are organizational metadata (like "smart playlists"). Books can be in collections without being on any device. Progress/annotations sync independently of collection membership.
@@ -93,7 +93,7 @@ This plan implements a complete cross-device ebook management system with three
- Tier 2 (Sync APIs): Device tokens for progress/annotation sync - Tier 2 (Sync APIs): Device tokens for progress/annotation sync
- Tier 3 (OPDS): Device tokens for catalog access (optional per-device) - Tier 3 (OPDS): Device tokens for catalog access (optional per-device)
6. **Terminology Separation** - Always use "Collections" terminology in Bookmann UI. Map Collections to device-specific "Shelves" only at API/device level. Kobo devices see "Shelves", KOReader/Web/Mobile see "Collections". Prevents legal issues. 6. **Terminology Separation** - Always use "Collections" terminology in Bookhoard UI. Map Collections to device-specific "Shelves" only at API/device level. Kobo devices see "Shelves", KOReader/Web/Mobile see "Collections". Prevents legal issues.
7. **OPDS Primary for All Devices** - Kobo, KOReader, Web, and Mobile all use OPDS as primary book delivery method. Sidecar files provide fallback/enhanced features but are optional. 7. **OPDS Primary for All Devices** - Kobo, KOReader, Web, and Mobile all use OPDS as primary book delivery method. Sidecar files provide fallback/enhanced features but are optional.
@@ -211,7 +211,7 @@ CREATE INDEX idx_collection_items_media ON collection_items(media_item_id);
### Table: device_shelf_mappings (NEW) ### Table: device_shelf_mappings (NEW)
```sql ```sql
-- Map Bookmann collections to device-specific shelf names -- Map Bookhoard collections to device-specific shelf names
-- This is where "Collections" terminology maps to Kobo's "Shelves" -- This is where "Collections" terminology maps to Kobo's "Shelves"
CREATE TABLE device_shelf_mappings ( CREATE TABLE device_shelf_mappings (
@@ -219,7 +219,7 @@ CREATE TABLE device_shelf_mappings (
collection_id UUID REFERENCES collections(id) ON DELETE CASCADE, collection_id UUID REFERENCES collections(id) ON DELETE CASCADE,
device_id UUID REFERENCES devices(id) ON DELETE CASCADE, device_id UUID REFERENCES devices(id) ON DELETE CASCADE,
device_shelf_name VARCHAR(100), -- What appears on Kobo device device_shelf_name VARCHAR(100), -- What appears on Kobo device
sync_direction VARCHAR(20), -- 'bidirectional', 'book_to_device', 'device_to_book', 'none' sync_direction VARCHAR(20), -- 'bidirectional', 'book_to_hoard', 'device_to_hoard', 'none'
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(), created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
UNIQUE(collection_id, device_id) UNIQUE(collection_id, device_id)
); );
@@ -231,7 +231,7 @@ CREATE INDEX idx_device_shelf_mappings_device ON device_shelf_mappings(device_id
### Table: device_catalogs (NEW) ### Table: device_catalogs (NEW)
```sql ```sql
-- Track OPDS downloads and map Bookmann UUIDs to device ContentIds -- Track OPDS downloads and map Bookhoard UUIDs to device ContentIds
-- Critical for bidirectional progress sync with format conversion handling -- Critical for bidirectional progress sync with format conversion handling
CREATE TABLE device_catalogs ( CREATE TABLE device_catalogs (
@@ -326,7 +326,7 @@ users
#### POST `/api/sync/books/query` #### POST `/api/sync/books/query`
Query Bookmann for a book by multiple identifier types with confidence scoring. Query Bookhoard for a book by multiple identifier types with confidence scoring.
**Request**: **Request**:
```json ```json
@@ -355,7 +355,7 @@ Query Bookmann for a book by multiple identifier types with confidence scoring.
``` ```
**Matching Priority**: **Matching Priority**:
1. Bookmann UUID (canonical) - Confidence: 1.0 1. Bookhoard UUID (canonical) - Confidence: 1.0
2. OPF UUID (from EPUB metadata) - Confidence: 0.95 2. OPF UUID (from EPUB metadata) - Confidence: 0.95
3. SHA-256 hash (content-based match) - Confidence: 0.9 3. SHA-256 hash (content-based match) - Confidence: 0.9
4. OPF identifier (non-UUID) - Confidence: 0.85 4. OPF identifier (non-UUID) - Confidence: 0.85
@@ -655,7 +655,7 @@ Main OPDS 1.2 catalog feed.
xmlns:opds="http://opds-spec.org/2010/" xmlns:opds="http://opds-spec.org/2010/"
xmlns:dc="http://purl.org/dc/elements/1.1/"> xmlns:dc="http://purl.org/dc/elements/1.1/">
<id>urn:uuid:device-id</id> <id>urn:uuid:device-id</id>
<title>Bookmann Library</title> <title>Bookhoard Library</title>
<updated>2026-01-31T12:00:00Z</updated> <updated>2026-01-31T12:00:00Z</updated>
<link rel="self" href="http://192.168.1.100:8765/opds/devices/kobo-id/catalog"/> <link rel="self" href="http://192.168.1.100:8765/opds/devices/kobo-id/catalog"/>
@@ -734,9 +734,9 @@ Download book with optional format conversion.
**Response Headers**: **Response Headers**:
- `Content-Type`: application/epub+zip (or format-specific) - `Content-Type`: application/epub+zip (or format-specific)
- `Content-Disposition`: attachment; filename="The Hobbit.epub" - `Content-Disposition`: attachment; filename="The Hobbit.epub"
- `X-Bookmann-UUID`: uuid-123 - `X-Bookhoard-UUID`: uuid-123
- `X-Bookmann-SHA256`: abc123... (for format-specific if available) - `X-Bookhoard-SHA256`: abc123... (for format-specific if available)
- `X-Bookmann-KEPUB-SHA256`: xyz789... (if format=kepub) - `X-Bookhoard-KEPUB-SHA256`: xyz789... (if format=kepub)
**Format Conversion Logic**: **Format Conversion Logic**:
```go ```go
@@ -746,7 +746,7 @@ case "kepub":
// Check media_item_formats table for pre-converted KEPUB // Check media_item_formats table for pre-converted KEPUB
if kepubFormat.Exists && kepubFormat.FilePath != "" { if kepubFormat.Exists && kepubFormat.FilePath != "" {
Serve pre-converted file Serve pre-converted file
Set X-Bookmann-KEPUB-SHA256: kepubFormat.SHA256 Set X-Bookhoard-KEPUB-SHA256: kepubFormat.SHA256
} }
case "pdf": case "pdf":
// Serve PDF directly // Serve PDF directly
@@ -853,8 +853,8 @@ Kobo progress sync with ContentId mapping (enhanced).
// Step 1: Try direct ContentId lookup // Step 1: Try direct ContentId lookup
catalog, err := db.GetDeviceCatalogByKoboContentId(ctx, contentId) catalog, err := db.GetDeviceCatalogByKoboContentId(ctx, contentId)
if err == nil && catalog.Valid { if err == nil && catalog.Valid {
// Found! Use canonical Bookmann UUID // Found! Use canonical Bookhoard UUID
bookmannUUID = catalog.BookmannUUID bookmannUUID = catalog.BookhoardUUID
return bookmannUUID, nil return bookmannUUID, nil
} }
@@ -891,7 +891,7 @@ Kobo library sync with collection metadata (enhanced).
// NEW: Collection metadata // NEW: Collection metadata
"Categories": ["Science Fiction", "Reading"], "Categories": ["Science Fiction", "Reading"],
"BookmannUUID": "uuid-123" // Canonical ID "BookhoardUUID": "uuid-123" // Canonical ID
} }
] ]
} }
@@ -1119,7 +1119,7 @@ LOW (confidence = 0.5):
**Matching Algorithm**: **Matching Algorithm**:
``` ```
Priority 1: Bookmann UUID (canonical) Priority 1: Bookhoard UUID (canonical)
- If device sends UUID, use directly - If device sends UUID, use directly
- Confidence = 1.0 - Confidence = 1.0
@@ -1257,12 +1257,12 @@ When user downloads with ?format=kepub:
1. Check media_item_formats table 1. Check media_item_formats table
2. If KEPUB exists and is recent: 2. If KEPUB exists and is recent:
- Serve pre-converted file - Serve pre-converted file
- Set X-Bookmann-SHA256: kepubFormat.SHA256 - Set X-Bookhoard-SHA256: kepubFormat.SHA256
3. If KEPUB doesn't exist: 3. If KEPUB doesn't exist:
- Convert EPUB to KEPUB on-the-fly - Convert EPUB to KEPUB on-the-fly
- Cache in media_item_formats table - Cache in media_item_formats table
- Serve converted file - Serve converted file
- Set X-Bookmann-SHA256: kepubFormat.SHA256 - Set X-Bookhoard-SHA256: kepubFormat.SHA256
4. Serve PDF directly 4. Serve PDF directly
``` ```
@@ -1287,8 +1287,8 @@ When user downloads with ?format=kepub:
// Step 1: Try direct ContentId lookup // Step 1: Try direct ContentId lookup
catalog, err := db.GetDeviceCatalogByKoboContentId(ctx, contentId) catalog, err := db.GetDeviceCatalogByKoboContentId(ctx, contentId)
if err == nil && catalog.Valid { if err == nil && catalog.Valid {
// Found! Use canonical Bookmann UUID // Found! Use canonical Bookhoard UUID
return catalog.BookmannUUID, nil return catalog.BookhoardUUID, nil
} }
// Step 2: ContentId not found - try SHA-256 // Step 2: ContentId not found - try SHA-256
@@ -1440,7 +1440,7 @@ if book.FilePath != "" {
**Step 1: Download Configuration File** **Step 1: Download Configuration File**
``` ```
1. Log into Bookmann web UI 1. Log into Bookhoard web UI
2. Go to Device Management → Your Kobo device 2. Go to Device Management → Your Kobo device
3. Click "Download Configuration" button 3. Click "Download Configuration" button
4. File downloads as `.bookmann.json` 4. File downloads as `.bookmann.json`
@@ -1453,16 +1453,16 @@ if book.FilePath != "" {
3. Enter URL from `.bookmann.json`: 3. Enter URL from `.bookmann.json`:
http://192.168.1.100:8765/opds/devices/YOUR_DEVICE_ID/catalog http://192.168.1.100:8765/opds/devices/YOUR_DEVICE_ID/catalog
4. Kobo will automatically: 4. Kobo will automatically:
- Connect to Bookmann - Connect to Bookhoard
- Browse your library wirelessly - Browse your library wirelessly
- Download books directly - Download books directly
- Sync reading progress back to Bookmann - Sync reading progress back to Bookhoard
``` ```
**Step 3: Wireless Book Acquisition** **Step 3: Wireless Book Acquisition**
``` ```
1. On Kobo, go to "My Books" section 1. On Kobo, go to "My Books" section
2. Browse Bookmann catalog via OPDS 2. Browse Bookhoard catalog via OPDS
3. Tap on any book to download wirelessly 3. Tap on any book to download wirelessly
4. Book appears on Kobo device 4. Book appears on Kobo device
5. Start reading - progress syncs automatically 5. Start reading - progress syncs automatically
@@ -1470,8 +1470,8 @@ if book.FilePath != "" {
**How Progress Sync Works**: **How Progress Sync Works**:
- Kobo generates ContentId for each book - Kobo generates ContentId for each book
- ContentId mapped to Bookmann UUID in device_catalogs table - ContentId mapped to Bookhoard UUID in device_catalogs table
- When Kobo syncs progress, Bookmann uses canonical UUID - When Kobo syncs progress, Bookhoard uses canonical UUID
- Format conversion (KEPUB) doesn't break progress tracking - Format conversion (KEPUB) doesn't break progress tracking
### KOReader Setup ### KOReader Setup
@@ -1490,7 +1490,7 @@ Same as Kobo setup above
3. Enter OPDS URL from `.bookmann.json`: 3. Enter OPDS URL from `.bookmann.json`:
http://192.168.1.100:8765/opds/devices/YOUR_DEVICE_ID/catalog http://192.168.1.100:8765/opds/devices/YOUR_DEVICE_ID/catalog
4. KOReader will automatically: 4. KOReader will automatically:
- Connect to Bookmann catalog - Connect to Bookhoard catalog
- Browse and download books wirelessly - Browse and download books wirelessly
- Sync progress using SHA-256 matching - Sync progress using SHA-256 matching
- Create file aliases automatically - Create file aliases automatically
@@ -1500,7 +1500,7 @@ Same as Kobo setup above
``` ```
1. Open KOReader file browser 1. Open KOReader file browser
2. Tap "+" button to add OPDS catalog 2. Tap "+" button to add OPDS catalog
3. Browse Bookmann catalog 3. Browse Bookhoard catalog
4. Download books directly 4. Download books directly
5. Start reading 5. Start reading
``` ```
@@ -1522,7 +1522,7 @@ Place in KOReader's config directory
**Step 3: Use Sidecar for Progress Sync** **Step 3: Use Sidecar for Progress Sync**
``` ```
KOReader plugin reads .bookmann.json KOReader plugin reads .bookmann.json
→ Matches local files to Bookmann UUIDs via SHA-256 → Matches local files to Bookhoard UUIDs via SHA-256
→ Syncs progress using canonical UUIDs → Syncs progress using canonical UUIDs
→ Works offline → Works offline
``` ```
@@ -1628,7 +1628,7 @@ Can be: Public (no authentication required)
- [ ] Browse catalog wirelessly - [ ] Browse catalog wirelessly
- [ ] Download book - [ ] Download book
- [ ] Read 50% of book - [ ] Read 50% of book
- [ ] Verify progress syncs to Bookmann - [ ] Verify progress syncs to Bookhoard
**KOReader Workflow**: **KOReader Workflow**:
- [ ] Download `.bookmann.json` from web UI - [ ] Download `.bookmann.json` from web UI
@@ -1636,10 +1636,10 @@ Can be: Public (no authentication required)
- [ ] Browse catalog wirelessly - [ ] Browse catalog wirelessly
- [ ] Download book - [ ] Download book
- [ ] Read 75% of book - [ ] Read 75% of book
- [ ] Verify progress syncs to Bookmann - [ ] Verify progress syncs to Bookhoard
**Cross-Device Scenario**: **Cross-Device Scenario**:
- [ ] Add book to Bookmann (EPUB scanned) - [ ] Add book to Bookhoard (EPUB scanned)
- [ ] Download to Kobo via OPDS - [ ] Download to Kobo via OPDS
- [ ] Sync progress (60%) from Kobo - [ ] Sync progress (60%) from Kobo
- [ ] Open same book on KOReader (side-loaded) - [ ] Open same book on KOReader (side-loaded)
@@ -1651,18 +1651,18 @@ Can be: Public (no authentication required)
## Glossary ## Glossary
- **Bookmann UUID**: Canonical identifier for a book in Bookmann system (from `media_items.id`). Always used for progress tracking, never SHA-256. SHA-256 is only for matching books across devices. - **Bookhoard UUID**: Canonical identifier for a book in Bookhoard system (from `media_items.id`). Always used for progress tracking, never SHA-256. SHA-256 is only for matching books across devices.
- **ContentId**: Device-generated identifier (e.g., Kobo's "kobo_abc"). Mapped to Bookmann UUID in `device_catalogs` table. Used for progress sync after OPDS downloads. - **ContentId**: Device-generated identifier (e.g., Kobo's "kobo_abc"). Mapped to Bookhoard UUID in `device_catalogs` table. Used for progress sync after OPDS downloads.
- **SHA-256**: Cryptographic hash of file contents. Used for content-based matching across devices. Critical for identifying same book on different devices. - **SHA-256**: Cryptographic hash of file contents. Used for content-based matching across devices. Critical for identifying same book on different devices.
- **OPF UUID**: Unique identifier from EPUB metadata `<dc:identifier id="...">`. High-confidence identifier format. - **OPF UUID**: Unique identifier from EPUB metadata `<dc:identifier id="...">`. High-confidence identifier format.
- **OPF Identifier**: Any identifier from EPUB OPF file (custom format). Medium-confidence identifier format. - **OPF Identifier**: Any identifier from EPUB OPF file (custom format). Medium-confidence identifier format.
- **ISBN**: International Standard Book Number (13 digits). Medium-confidence standard identifier. - **ISBN**: International Standard Book Number (13 digits). Medium-confidence standard identifier.
- **ASIN**: Amazon Standard Identification Number (10 characters). Medium-confidence standard identifier. - **ASIN**: Amazon Standard Identification Number (10 characters). Medium-confidence standard identifier.
- **Collections**: Device-neutral organizational groups in Bookmann (e.g., "Science Fiction", "Reading"). Books can be in collections without being on any device. Collections organize library, not track device inventory. - **Collections**: Device-neutral organizational groups in Bookhoard (e.g., "Science Fiction", "Reading"). Books can be in collections without being on any device. Collections organize library, not track device inventory.
- **Shelves**: Device-specific organization (e.g., Kobo's terminology). Map Collections to device-specific "Shelves" only at device-level. Bookmann UI always uses "Collections" terminology. - **Shelves**: Device-specific organization (e.g., Kobo's terminology). Map Collections to device-specific "Shelves" only at device-level. Bookhoard UI always uses "Collections" terminology.
- **OPDS**: Open Publication Distribution System. Industry standard for book catalogs. All e-reader platforms have OPDS clients. Kobo, KOReader, Aldiko, FBReader, Web browsers can use OPDS catalogs. - **OPDS**: Open Publication Distribution System. Industry standard for book catalogs. All e-reader platforms have OPDS clients. Kobo, KOReader, Aldiko, FBReader, Web browsers can use OPDS catalogs.
- **Internal APIs**: Bookmann's private REST/WebSocket endpoints for state management. Web and mobile apps use these directly. Used for two-way sync, collections, WebSocket real-time updates. - **Internal APIs**: Bookhoard's private REST/WebSocket endpoints for state management. Web and mobile apps use these directly. Used for two-way sync, collections, WebSocket real-time updates.
- **Device File Alias**: Mapping of device-specific file paths to Bookmann UUIDs. Enables cross-device matching when same book has different file paths. - **Device File Alias**: Mapping of device-specific file paths to Bookhoard UUIDs. Enables cross-device matching when same book has different file paths.
- **Hash Confidence**: Scoring system (0.0-1.0) for automatic book matching reliability. Higher values = more reliable match. - **Hash Confidence**: Scoring system (0.0-1.0) for automatic book matching reliability. Higher values = more reliable match.
- **Dual Hash Storage**: Storing both original EPUB hash (`epub_sha256`) and converted KEPUB hash (`kepub_sha256`). Preserves hash integrity when files are converted. OPDS responses include format-specific hash for sidecar matching. - **Dual Hash Storage**: Storing both original EPUB hash (`epub_sha256`) and converted KEPUB hash (`kepub_sha256`). Preserves hash integrity when files are converted. OPDS responses include format-specific hash for sidecar matching.
- **Format Conversion**: Transcoding between book formats (EPUB → KEPUB). KEPUB adds Kobo-specific markup. Critical for Kobo optimization but shouldn't break progress tracking. - **Format Conversion**: Transcoding between book formats (EPUB → KEPUB). KEPUB adds Kobo-specific markup. Critical for Kobo optimization but shouldn't break progress tracking.
@@ -1671,7 +1671,7 @@ Can be: Public (no authentication required)
- **OPDS Tokens**: Per-device access tokens for OPDS catalog browsing. Optional - can also support user-scoped and admin tokens. - **OPDS Tokens**: Per-device access tokens for OPDS catalog browsing. Optional - can also support user-scoped and admin tokens.
- **Sidecar File**: `.bookmann.json` - Unified configuration file for devices. Contains OPDS URLs, sync API endpoints, book mappings, collection mappings. - **Sidecar File**: `.bookmann.json` - Unified configuration file for devices. Contains OPDS URLs, sync API endpoints, book mappings, collection mappings.
- **Auto-Assign Rules**: Configurable criteria for automatically adding books to collections. Fields: genre, series, author, language, publisher, copyright_year, tags. Operators: equals, contains, starts_with, ends_with, greater_than, less_than. - **Auto-Assign Rules**: Configurable criteria for automatically adding books to collections. Fields: genre, series, author, language, publisher, copyright_year, tags. Operators: equals, contains, starts_with, ends_with, greater_than, less_than.
- **Sync Direction**: For device shelf mappings. 'bidirectional' (sync both ways), 'book_to_device' (send to device), 'device_to_book' (read from device), 'none' (no sync). - **Sync Direction**: For device shelf mappings. 'bidirectional' (sync both ways), 'book_to_hoard' (send to device), 'device_to_hoard' (read from device), 'none' (no sync).
- **View Settings**: Per-device preferences for how collections are displayed (grid vs list, which collections are visible). - **View Settings**: Per-device preferences for how collections are displayed (grid vs list, which collections are visible).
- **Unlinked Book**: Progress record without proper media_item_id or failed ContentId lookup. Needs manual user resolution. - **Unlinked Book**: Progress record without proper media_item_id or failed ContentId lookup. Needs manual user resolution.
@@ -1689,4 +1689,4 @@ This comprehensive implementation plan provides:
- **Glossary** of all terminology and concepts - **Glossary** of all terminology and concepts
- **Testing strategies** covering unit, integration, and manual validation - **Testing strategies** covering unit, integration, and manual validation
The plan is designed for systematic execution while maintaining architectural consistency and enabling human oversight throughout the development process. All decisions from our conversations have been incorporated, providing a complete roadmap for implementing Bookmann as a comprehensive cross-device ebook management system. The plan is designed for systematic execution while maintaining architectural consistency and enabling human oversight throughout the development process. All decisions from our conversations have been incorporated, providing a complete roadmap for implementing Bookhoard as a comprehensive cross-device ebook management system.
docs/LEGACY_CLEANUP_PHASES_1-3_COMPLETE.md
+1 -1
View File
@@ -2,7 +2,7 @@
## Summary ## Summary
Successfully completed Phases 1-3 of the legacy migration code cleanup for Bookmann. Successfully completed Phases 1-3 of the legacy migration code cleanup for Bookhoard.
--- ---
docs/PHASE2_COMPLETION_SUMMARY.md
+1 -1
View File
@@ -289,7 +289,7 @@ curl -X GET http://localhost:8765/api/sync/unlinked-books/123e4567-e89b-12d3-a45
### Matching Priority (Auto-Link) ### Matching Priority (Auto-Link)
The auto-link feature uses the existing book matching algorithm with priority: The auto-link feature uses the existing book matching algorithm with priority:
1. Bookmann UUID (canonical) - 1.0 confidence 1. Bookhoard UUID (canonical) - 1.0 confidence
2. OPF UUID - 0.95 confidence 2. OPF UUID - 0.95 confidence
3. SHA-256 hash - 0.9 confidence 3. SHA-256 hash - 0.9 confidence
4. OPF identifier - 0.85 confidence 4. OPF identifier - 0.85 confidence
docs/PROGRESS_ROUTES_ANALYSIS.md
+2 -2
View File
@@ -2,7 +2,7 @@
## Overview ## Overview
This document explores the current state of progress tracking in Bookmann, the migration from legacy media-item-specific routes to universal cross-device progress, and considerations for the future. This document explores the current state of progress tracking in Bookhoard, the migration from legacy media-item-specific routes to universal cross-device progress, and considerations for the future.
--- ---
@@ -63,7 +63,7 @@ g.GET("/api/progress/:id/history", h.GetProgressHistory)
### 1. **Cross-Platform Kindle Ecosystem Vision** ### 1. **Cross-Platform Kindle Ecosystem Vision**
Bookmann aims to replace the Kindle ecosystem, which requires: Bookhoard aims to replace the Kindle ecosystem, which requires:
- Syncing progress across multiple devices (Kindle, Kobo, phone, web) - Syncing progress across multiple devices (Kindle, Kobo, phone, web)
- Handling different progress formats (page numbers, percentages, CFI, character offsets) - Handling different progress formats (page numbers, percentages, CFI, character offsets)
- Maintaining reading state across different device types - Maintaining reading state across different device types
docs/SECURITY_AUDIT.md
+3 -3
View File
@@ -1,9 +1,9 @@
# Bookmann Security Audit Report # Bookhoard Security Audit Report
## Universal Sync Implementation (Phases 1-7) ## Universal Sync Implementation (Phases 1-7)
**Date**: January 31, 2026 **Date**: January 31, 2026
**Version**: 1.0.0 **Version**: 1.0.0
**Auditor**: Bookmann Security Team **Auditor**: Bookhoard Security Team
--- ---
@@ -513,6 +513,6 @@ Audit Logs: 180 days
--- ---
**Audit Completed By**: Bookmann Security Team **Audit Completed By**: Bookhoard Security Team
**Next Audit**: Within 3 months of production deployment **Next Audit**: Within 3 months of production deployment
**Questions**: security@bookmann.example.com **Questions**: security@bookmann.example.com
docs/SECURITY_ENHANCEMENTS.md
+2 -2
View File
@@ -3,13 +3,13 @@
**Date**: January 31, 2026 **Date**: January 31, 2026
**Version**: 1.0.1 **Version**: 1.0.1
**Implemented By**: Bookmann Security Team **Implemented By**: Bookhoard Security Team
--- ---
## Executive Summary ## Executive Summary
All **Priority 1** security recommendations from the security audit have been successfully implemented, bringing Bookmann's security rating from **A- (8.6/10)** to **A+ (9.2/10)**. All **Priority 1** security recommendations from the security audit have been successfully implemented, bringing Bookhoard's security rating from **A- (8.6/10)** to **A+ (9.2/10)**.
### Security Scorecard Update ### Security Scorecard Update
docs/SYNC_USER_GUIDE.md
+8 -8
View File
@@ -1,4 +1,4 @@
# Bookmann Universal Sync - User Guide # Bookhoard Universal Sync - User Guide
## Table of Contents ## Table of Contents
1. [What is Universal Sync?](#what-is-universal-sync) 1. [What is Universal Sync?](#what-is-universal-sync)
@@ -13,7 +13,7 @@
## What is Universal Sync? ## What is Universal Sync?
**Universal Sync** is Bookmann's cross-platform synchronization system that keeps your reading progress, highlights, and notes in sync across all your devices - automatically and in real-time. **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 ### Key Features
@@ -55,9 +55,9 @@
### Prerequisites ### Prerequisites
1. **Bookmann Server** - Self-hosted instance running and accessible 1. **Bookhoard Server** - Self-hosted instance running and accessible
2. **Network Connection** - Devices must be able to reach your Bookmann server 2. **Network Connection** - Devices must be able to reach your Bookhoard server
3. **User Account** - Created and logged in to Bookmann web interface 3. **User Account** - Created and logged in to Bookhoard web interface
### Quick Start ### Quick Start
@@ -76,11 +76,11 @@
1. **On Your Device**: 1. **On Your Device**:
- Open your reading app (KOReader/Kobo) - Open your reading app (KOReader/Kobo)
- Navigate to sync settings - Navigate to sync settings
- Find "Bookmann Sync" or "Calibre Sync" - Find "Bookhoard Sync" or "Calibre Sync"
- Copy your device identifier (hardware ID) - Copy your device identifier (hardware ID)
2. **In Your Browser**: 2. **In Your Browser**:
- Go to your Bookmann server - Go to your Bookhoard server
- Log in with your account - Log in with your account
- Navigate to **Settings → Devices** - Navigate to **Settings → Devices**
- Click **Register New Device** - Click **Register New Device**
@@ -102,7 +102,7 @@
1. **From Your Device**: 1. **From Your Device**:
- Navigate to sync settings - Navigate to sync settings
- Select "Bookmann Sync" - Select "Bookhoard Sync"
- Enter server URL: `https://bookmann.example.com` - Enter server URL: `https://bookmann.example.com`
- Click "Register Device" - Click "Register Device"
- Device will display registration code - Device will display registration code
docs/TESTING.md
+3 -3
View File
@@ -1,8 +1,8 @@
# Bookmann Integration Test Suite Documentation # Bookhoard Integration Test Suite Documentation
## Overview ## Overview
This document provides comprehensive information about the integration test suite for Bookmann, including how to run tests, what they cover, and best practices for adding new tests. This document provides comprehensive information about the integration test suite for Bookhoard, including how to run tests, what they cover, and best practices for adding new tests.
## Test Architecture ## Test Architecture
@@ -550,4 +550,4 @@ jobs:
--- ---
**Last Updated**: 2025-02-01 **Last Updated**: 2025-02-01
**Maintained By**: Bookmann Development Team **Maintained By**: Bookhoard Development Team
docs/api/WEBSOCKET_API.md
+7 -7
View File
@@ -70,7 +70,7 @@ const token = "your-jwt-token";
const ws = new WebSocket(`ws://localhost:8765/ws/sync?token=${token}`); const ws = new WebSocket(`ws://localhost:8765/ws/sync?token=${token}`);
ws.onopen = () => { ws.onopen = () => {
console.log("Connected to Bookmann WebSocket"); console.log("Connected to Bookhoard WebSocket");
}; };
ws.onerror = (error) => { ws.onerror = (error) => {
@@ -489,7 +489,7 @@ ws.onclose = () => {
### Complete JavaScript Client ### Complete JavaScript Client
```javascript ```javascript
class BookmannWebSocket { class BookhoardWebSocket {
constructor(token) { constructor(token) {
this.token = token; this.token = token;
this.ws = null; this.ws = null;
@@ -503,7 +503,7 @@ class BookmannWebSocket {
this.ws = new WebSocket(url); this.ws = new WebSocket(url);
this.ws.onopen = () => { this.ws.onopen = () => {
console.log("Connected to Bookmann"); console.log("Connected to Bookhoard");
this.reconnectAttempts = 0; this.reconnectAttempts = 0;
}; };
@@ -553,7 +553,7 @@ class BookmannWebSocket {
// Usage // Usage
const token = "your-jwt-token"; const token = "your-jwt-token";
const client = new BookmannWebSocket(token); const client = new BookhoardWebSocket(token);
client.on("initial_state", (message) => { client.on("initial_state", (message) => {
console.log("Initial state received:", message.data); console.log("Initial state received:", message.data);
@@ -664,9 +664,9 @@ client.connect();
## Support ## Support
For issues or questions: For issues or questions:
- GitHub Issues: [Bookmann Repository] - GitHub Issues: [Bookhoard Repository]
- Documentation: [Bookmann Docs] - Documentation: [Bookhoard Docs]
- API Reference: [Bookmann API Docs] - API Reference: [Bookhoard API Docs]
--- ---
docs/devices/KOBO_SETUP.md
+60 -60
View File
@@ -1,10 +1,10 @@
# Kobo Device Setup Guide # Kobo Device Setup Guide
This guide will help you set up your Kobo e-reader to sync with Bookmann for seamless cross-device reading progress synchronization. This guide will help you set up your Kobo e-reader to sync with Bookhoard for seamless cross-device reading progress synchronization.
## What is Kobo Sync? ## What is Kobo Sync?
Bookmann implements a Kobo-compatible sync protocol that allows your Kobo device to: Bookhoard implements a Kobo-compatible sync protocol that allows your Kobo device to:
- Sync reading progress across all your devices - Sync reading progress across all your devices
- Sync highlights and bookmarks - Sync highlights and bookmarks
- Sync reading statistics - Sync reading statistics
@@ -14,14 +14,14 @@ Bookmann implements a Kobo-compatible sync protocol that allows your Kobo device
Before you begin, make sure you have: Before you begin, make sure you have:
- ✅ A Kobo e-reader device (Clara, Aura, Nia, Libra, Sage, Elipsa, etc.) - ✅ A Kobo e-reader device (Clara, Aura, Nia, Libra, Sage, Elipsa, etc.)
- ✅ A Bookmann instance running and accessible on your network - ✅ A Bookhoard instance running and accessible on your network
- ✅ Your Bookmann credentials (username and password) - ✅ Your Bookhoard credentials (username and password)
- ✅ USB cable to connect your Kobo to your computer - ✅ USB cable to connect your Kobo to your computer
- ✅ Your Kobo connected to the same Wi-Fi network as your Bookmann instance - ✅ Your Kobo connected to the same Wi-Fi network as your Bookhoard instance
## Supported Kobo Devices ## Supported Kobo Devices
Bookmann supports all Kobo devices that use the standard Kobo sync protocol: Bookhoard supports all Kobo devices that use the standard Kobo sync protocol:
- **Kobo Clara**: Clara 2E, Clara HD - **Kobo Clara**: Clara 2E, Clara HD
- **Kobo Aura**: Aura, Aura H2O, Aura ONE, Aura Edition 2 - **Kobo Aura**: Aura, Aura H2O, Aura ONE, Aura Edition 2
- **Kobo Libra**: Libra 2, Libra H2O - **Kobo Libra**: Libra 2, Libra H2O
@@ -42,9 +42,9 @@ Bookmann supports all Kobo devices that use the standard Kobo sync protocol:
4. Note your **Device Serial Number** (e.g., N1234567890123) 4. Note your **Device Serial Number** (e.g., N1234567890123)
- This is your device identifier for registration - This is your device identifier for registration
### Step 2: Register Your Device in Bookmann ### Step 2: Register Your Device in Bookhoard
1. Log in to your Bookmann web interface 1. Log in to your Bookhoard web interface
2. Navigate to **Device Management** → **Add New Device** 2. Navigate to **Device Management** → **Add New Device**
3. Fill in the device details: 3. Fill in the device details:
- **Device Name**: A friendly name (e.g., "My Kobo Clara") - **Device Name**: A friendly name (e.g., "My Kobo Clara")
@@ -66,7 +66,7 @@ You'll receive:
2. **Method B: Manual URL** 2. **Method B: Manual URL**
- Copy the Auth URL from the registration confirmation - Copy the Auth URL from the registration confirmation
- Open it in your web browser - Open it in your web browser
- Log in to your Bookmann account - Log in to your Bookhoard account
- Click **Approve Device** - Click **Approve Device**
Your device is now registered and ready for configuration! Your device is now registered and ready for configuration!
@@ -97,7 +97,7 @@ Your device is now registered and ready for configuration!
2. Navigate to `.kobo/Kobo/Kobo eReader.conf` 2. Navigate to `.kobo/Kobo/Kobo eReader.conf`
3. Open in a text editor 3. Open in a text editor
### Step 3: Add Bookmann Sync Configuration ### Step 3: Add Bookhoard Sync Configuration
Add the following section to the end of your `Kobo eReader.conf` file: Add the following section to the end of your `Kobo eReader.conf` file:
@@ -107,7 +107,7 @@ Add the following section to the end of your `Kobo eReader.conf` file:
KoboStoreSyncDisabled=true KoboStoreSyncDisabled=true
[Sync] [Sync]
# Bookmann Sync Configuration # Bookhoard Sync Configuration
ServerURL=http://YOUR_COMPUTER_IP:8765/api/sync/kobo ServerURL=http://YOUR_COMPUTER_IP:8765/api/sync/kobo
AutoSyncEnabled=true AutoSyncEnabled=true
SyncFrequency=5 SyncFrequency=5
@@ -119,8 +119,8 @@ Password=YOUR_BOOKMANN_PASSWORD
**Replace the following with your actual values**: **Replace the following with your actual values**:
- `YOUR_COMPUTER_IP`: Your computer's local IP address (e.g., 192.168.1.100) - `YOUR_COMPUTER_IP`: Your computer's local IP address (e.g., 192.168.1.100)
- `YOUR_BOOKMANN_USERNAME`: Your Bookmann email or username - `YOUR_BOOKMANN_USERNAME`: Your Bookhoard email or username
- `YOUR_BOOKMANN_PASSWORD`: Your Bookmann password - `YOUR_BOOKMANN_PASSWORD`: Your Bookhoard password
**Example configuration:** **Example configuration:**
```ini ```ini
@@ -141,7 +141,7 @@ Password=securePassword123
### Step 5: Verify Sync on Kobo ### Step 5: Verify Sync on Kobo
1. After Kobo restarts, go to **Settings** → **Sync & Backup** 1. After Kobo restarts, go to **Settings** → **Sync & Backup**
2. You should see "Bookmann" listed as a sync provider 2. You should see "Bookhoard" listed as a sync provider
3. Tap **Sync Now** to test the connection 3. Tap **Sync Now** to test the connection
4. If successful, you'll see a "Sync Complete" message 4. If successful, you'll see a "Sync Complete" message
@@ -174,12 +174,12 @@ Kobo syncs:
### What is OPDS? ### What is OPDS?
OPDS (Open Publication Distribution System) allows your Kobo to **wirelessly download books** from Bookmann - no USB cable needed! OPDS (Open Publication Distribution System) allows your Kobo to **wirelessly download books** from Bookhoard - no USB cable needed!
### OPDS Benefits ### OPDS Benefits
- **No USB Required**: Download books directly to your Kobo over Wi-Fi - **No USB Required**: Download books directly to your Kobo over Wi-Fi
- **On-Demand Delivery**: Browse your Bookmann library from your Kobo - **On-Demand Delivery**: Browse your Bookhoard library from your Kobo
- **Collection Support**: Download books from specific collections - **Collection Support**: Download books from specific collections
- **Progress Tracking**: Books downloaded via OPDS sync progress automatically - **Progress Tracking**: Books downloaded via OPDS sync progress automatically
- **Format Conversion**: Automatic EPUB to KEPUB conversion for better Kobo support - **Format Conversion**: Automatic EPUB to KEPUB conversion for better Kobo support
@@ -211,8 +211,8 @@ OPDSCatalogURL=http://YOUR_COMPUTER_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog
``` ```
4. Replace: 4. Replace:
- `YOUR_COMPUTER_IP`: Your Bookmann server IP - `YOUR_COMPUTER_IP`: Your Bookhoard server IP
- `YOUR_DEVICE_ID`: Your Kobo's device ID from Bookmann Device Management - `YOUR_DEVICE_ID`: Your Kobo's device ID from Bookhoard Device Management
5. Save the file and safely eject your Kobo 5. Save the file and safely eject your Kobo
@@ -220,14 +220,14 @@ OPDSCatalogURL=http://YOUR_COMPUTER_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog
1. Wake your Kobo and connect to Wi-Fi 1. Wake your Kobo and connect to Wi-Fi
2. Go to **Home** → **Store** (or **Shop**) 2. Go to **Home** → **Store** (or **Shop**)
3. You'll see **Bookmann** listed as a store 3. You'll see **Bookhoard** listed as a store
4. Tap to enter the Bookmann catalog 4. Tap to enter the Bookhoard catalog
### Browse and Download Books ### Browse and Download Books
#### Browse All Books #### Browse All Books
1. In the Bookmann catalog, you'll see all books from your library 1. In the Bookhoard catalog, you'll see all books from your library
2. Browse by: 2. Browse by:
- **Recently Added**: Latest books in your library - **Recently Added**: Latest books in your library
- **Collections**: Books organized by collections - **Collections**: Books organized by collections
@@ -244,7 +244,7 @@ OPDSCatalogURL=http://YOUR_COMPUTER_IP:8765/opds/devices/YOUR_DEVICE_ID/catalog
#### Download from Collections #### Download from Collections
1. In the Bookmann catalog, tap **Collections** 1. In the Bookhoard catalog, tap **Collections**
2. Select a collection (e.g., "Science Fiction") 2. Select a collection (e.g., "Science Fiction")
3. Browse books in that collection 3. Browse books in that collection
4. Tap to download individual books 4. Tap to download individual books
@@ -259,34 +259,34 @@ Kobo OPDS supports:
- **KEPUB**: Kobo-optimized EPUB (better page turns, fonts) - **KEPUB**: Kobo-optimized EPUB (better page turns, fonts)
- **PDF**: Fixed-layout documents - **PDF**: Fixed-layout documents
**Automatic Conversion**: Bookmann automatically converts EPUB to KEPUB on-the-fly for better Kobo experience. **Automatic Conversion**: Bookhoard automatically converts EPUB to KEPUB on-the-fly for better Kobo experience.
#### Progress Sync #### Progress Sync
Books downloaded via OPDS automatically sync progress: Books downloaded via OPDS automatically sync progress:
1. Download a book via OPDS 1. Download a book via OPDS
2. Start reading on your Kobo 2. Start reading on your Kobo
3. Progress syncs to Bookmann automatically 3. Progress syncs to Bookhoard automatically
4. Continue reading on any other device! 4. Continue reading on any other device!
#### Collection to Shelf Mapping #### Collection to Shelf Mapping
Bookmann maps your collections to Kobo shelves: Bookhoard maps your collections to Kobo shelves:
- Collection **"Science Fiction"** → Kobo shelf **"Sci-Fi"** - Collection **"Science Fiction"** → Kobo shelf **"Sci-Fi"**
- Collection **"To Read"** → Kobo shelf **"To Read"** - Collection **"To Read"** → Kobo shelf **"To Read"**
- Customizable in Bookmann Device Management - Customizable in Bookhoard Device Management
### OPDS Troubleshooting ### OPDS Troubleshooting
#### Catalog Not Appearing #### Catalog Not Appearing
**Problem**: Bookmann catalog doesn't show in Kobo store **Problem**: Bookhoard catalog doesn't show in Kobo store
**Solutions**: **Solutions**:
1. Verify OPDS URL is correct in config file 1. Verify OPDS URL is correct in config file
2. Check Kobo is connected to Wi-Fi 2. Check Kobo is connected to Wi-Fi
3. Try accessing OPDS URL in your browser 3. Try accessing OPDS URL in your browser
4. Ensure device ID matches Bookmann device ID 4. Ensure device ID matches Bookhoard device ID
5. Restart Kobo after editing config file 5. Restart Kobo after editing config file
#### Download Fails #### Download Fails
@@ -295,10 +295,10 @@ Bookmann maps your collections to Kobo shelves:
**Solutions**: **Solutions**:
1. Check Wi-Fi signal strength 1. Check Wi-Fi signal strength
2. Ensure Bookmann server is running 2. Ensure Bookhoard server is running
3. Verify book file exists in Bookmann library 3. Verify book file exists in Bookhoard library
4. Try downloading a smaller book first 4. Try downloading a smaller book first
5. Check Bookmann logs for errors 5. Check Bookhoard logs for errors
#### Book Downloads But Won't Open #### Book Downloads But Won't Open
@@ -306,7 +306,7 @@ Bookmann maps your collections to Kobo shelves:
**Solutions**: **Solutions**:
1. Verify book format is supported (EPUB/KEPUB/PDF) 1. Verify book format is supported (EPUB/KEPUB/PDF)
2. Check file isn't corrupted in Bookmann 2. Check file isn't corrupted in Bookhoard
3. Try downloading via USB and opening 3. Try downloading via USB and opening
4. Check Kobo has sufficient free storage 4. Check Kobo has sufficient free storage
5. Restart your Kobo device 5. Restart your Kobo device
@@ -339,7 +339,7 @@ Bookmann maps your collections to Kobo shelves:
#### Custom Catalog Name #### Custom Catalog Name
Change the name of the Bookmann catalog on your Kobo: Change the name of the Bookhoard catalog on your Kobo:
```ini ```ini
[OPDS] [OPDS]
@@ -367,7 +367,7 @@ PreferredFormat=kepub # Options: epub, kepub, auto
## Sync Frequency Options ## Sync Frequency Options
Configure how often Kobo syncs with Bookmann: Configure how often Kobo syncs with Bookhoard:
```ini ```ini
[Sync] [Sync]
@@ -404,7 +404,7 @@ KoboStoreSyncDisabled=true
### Custom Sync URL ### Custom Sync URL
If you're running Bookmann with a custom domain or port: If you're running Bookhoard with a custom domain or port:
```ini ```ini
[Sync] [Sync]
@@ -420,7 +420,7 @@ ServerURL=http://localhost:8765/api/sync/kobo
### HTTPS Configuration ### HTTPS Configuration
If you have SSL/TLS configured on Bookmann: If you have SSL/TLS configured on Bookhoard:
```ini ```ini
[Sync] [Sync]
@@ -440,18 +440,18 @@ Kobo will automatically trust the certificate if properly configured.
2. Verify `AutoSyncEnabled=true` in config 2. Verify `AutoSyncEnabled=true` in config
3. Check `SyncFrequency` is not set to 0 3. Check `SyncFrequency` is not set to 0
4. Test with manual sync first 4. Test with manual sync first
5. Check Bookmann logs for connection attempts 5. Check Bookhoard logs for connection attempts
### Connection Refused ### Connection Refused
**Problem**: "Connection refused" or "Server not reachable" **Problem**: "Connection refused" or "Server not reachable"
**Solutions**: **Solutions**:
1. Verify Bookmann is running on your computer 1. Verify Bookhoard is running on your computer
2. Check the server URL and IP address are correct 2. Check the server URL and IP address are correct
3. Ensure Kobo is on same Wi-Fi network as computer 3. Ensure Kobo is on same Wi-Fi network as computer
4. Temporarily disable firewall to test 4. Temporarily disable firewall to test
5. Try accessing Bookmann URL in your browser first 5. Try accessing Bookhoard URL in your browser first
### Authentication Failed ### Authentication Failed
@@ -460,7 +460,7 @@ Kobo will automatically trust the certificate if properly configured.
**Solutions**: **Solutions**:
1. Verify username and password in config file 1. Verify username and password in config file
2. Check your account is active and not locked 2. Check your account is active and not locked
3. Try logging in to Bookmann web interface 3. Try logging in to Bookhoard web interface
4. Ensure password doesn't contain special characters that need escaping 4. Ensure password doesn't contain special characters that need escaping
5. Reset password if needed 5. Reset password if needed
@@ -484,17 +484,17 @@ Kobo will automatically trust the certificate if properly configured.
2. Check `SyncFrequency` is not 0 2. Check `SyncFrequency` is not 0
3. Kobo only syncs when connected to Wi-Fi 3. Kobo only syncs when connected to Wi-Fi
4. Some Kobo models require Wi-Fi to be manually connected 4. Some Kobo models require Wi-Fi to be manually connected
5. Check Bookmann device management page for connection errors 5. Check Bookhoard device management page for connection errors
### Books Not Appearing in Kobo ### Books Not Appearing in Kobo
**Problem**: Books added to Bookmann don't show on Kobo **Problem**: Books added to Bookhoard don't show on Kobo
**Solutions**: **Solutions**:
1. Kobo needs books to be sideloaded (manually transferred via USB) 1. Kobo needs books to be sideloaded (manually transferred via USB)
2. Bookmann syncs PROGRESS, not book files 2. Bookhoard syncs PROGRESS, not book files
3. Transfer book files to Kobo's `Documents` folder via USB 3. Transfer book files to Kobo's `Documents` folder via USB
4. Kobo will then sync progress for those books with Bookmann 4. Kobo will then sync progress for those books with Bookhoard
5. Check that book formats are supported by Kobo 5. Check that book formats are supported by Kobo
### Conflicts Not Showing ### Conflicts Not Showing
@@ -502,7 +502,7 @@ Kobo will automatically trust the certificate if properly configured.
**Problem**: Conflicts between devices aren't being detected **Problem**: Conflicts between devices aren't being detected
**Solutions**: **Solutions**:
1. Check Bookmann Conflicts page 1. Check Bookhoard Conflicts page
2. Ensure both devices have synced recently 2. Ensure both devices have synced recently
3. Conflicts only detected when progress differs within 5 minutes 3. Conflicts only detected when progress differs within 5 minutes
4. Manually sync both devices to trigger conflict detection 4. Manually sync both devices to trigger conflict detection
@@ -510,8 +510,8 @@ Kobo will automatically trust the certificate if properly configured.
## Security Best Practices ## Security Best Practices
1. **Use HTTPS**: If deploying Bookmann publicly, configure SSL/TLS 1. **Use HTTPS**: If deploying Bookhoard publicly, configure SSL/TLS
2. **Strong Password**: Use a secure password for your Bookmann account 2. **Strong Password**: Use a secure password for your Bookhoard account
3. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3) 3. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3)
4. **Regular Updates**: Keep Kobo firmware updated 4. **Regular Updates**: Keep Kobo firmware updated
5. **Device Authorization**: Only approve devices you recognize 5. **Device Authorization**: Only approve devices you recognize
@@ -520,17 +520,17 @@ Kobo will automatically trust the certificate if properly configured.
### Local Network (Recommended) ### Local Network (Recommended)
For home use, keep Kobo and Bookmann on the same local network: For home use, keep Kobo and Bookhoard on the same local network:
``` ```
Kobo Wi-Fi: 192.168.1.x Kobo Wi-Fi: 192.168.1.x
Bookmann: 192.168.1.x Bookhoard: 192.168.1.x
``` ```
### Remote Access ### Remote Access
For access outside your home network: For access outside your home network:
1. Set up port forwarding on your router (port 8765) 1. Set up port forwarding on your router (port 8765)
2. Configure SSL/TLS on Bookmann 2. Configure SSL/TLS on Bookhoard
3. Use a dynamic DNS service for constant hostname 3. Use a dynamic DNS service for constant hostname
4. Update Kobo config with public URL: 4. Update Kobo config with public URL:
```ini ```ini
@@ -553,30 +553,30 @@ To extend Kobo battery life:
To improve sync speed: To improve sync speed:
1. Ensure strong Wi-Fi signal 1. Ensure strong Wi-Fi signal
2. Use local network (not remote access) 2. Use local network (not remote access)
3. Keep Bookmann and Kobo on same network 3. Keep Bookhoard and Kobo on same network
4. Close other apps using Wi-Fi bandwidth 4. Close other apps using Wi-Fi bandwidth
5. Reduce number of books syncing at once 5. Reduce number of books syncing at once
## Additional Resources ## Additional Resources
- [Kobo Developer Documentation](https://help.kobo.com/hc/en-us) - [Kobo Developer Documentation](https://help.kobo.com/hc/en-us)
- [Bookmann Universal Sync Guide](UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md) - [Bookhoard Universal Sync Guide](UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md)
- [KOReader Setup Guide](KOBOREADER_SETUP.md) - [KOReader Setup Guide](KOBOREADER_SETUP.md)
- [Bookmann API Reference](API_REFERENCE.md) - [Bookhoard API Reference](API_REFERENCE.md)
## FAQ ## FAQ
**Q: Can I sync books (files) between devices?** **Q: Can I sync books (files) between devices?**
A: No, Bookmann only syncs reading progress and annotations. You must sideload book files to each device manually. A: No, Bookhoard only syncs reading progress and annotations. You must sideload book files to each device manually.
**Q: Will Kobo update automatically when I add books in Bookmann?** **Q: Will Kobo update automatically when I add books in Bookhoard?**
A: No, Kobo doesn't fetch book files from Bookmann. You must transfer books via USB. A: No, Kobo doesn't fetch book files from Bookhoard. You must transfer books via USB.
**Q: Can I use both Kobo Sync and Calibre?** **Q: Can I use both Kobo Sync and Calibre?**
A: Yes, but they may conflict. It's recommended to choose one sync method. A: Yes, but they may conflict. It's recommended to choose one sync method.
**Q: What happens if I read the same book on Kobo and KOReader?** **Q: What happens if I read the same book on Kobo and KOReader?**
A: Bookmann will detect conflicts and you can resolve them in the Conflicts UI. A: Bookhoard will detect conflicts and you can resolve them in the Conflicts UI.
**Q: Does Kobo sync when in sleep mode?** **Q: Does Kobo sync when in sleep mode?**
A: Only if Wi-Fi is enabled and configured to stay active during sleep. A: Only if Wi-Fi is enabled and configured to stay active during sleep.
@@ -586,12 +586,12 @@ A: Only if Wi-Fi is enabled and configured to stay active during sleep.
If you encounter issues: If you encounter issues:
1. Check the troubleshooting section above 1. Check the troubleshooting section above
2. Review Kobo sync logs in device settings 2. Review Kobo sync logs in device settings
3. Check Bookmann sync queue and device management pages 3. Check Bookhoard sync queue and device management pages
4. Verify your configuration file is saved correctly 4. Verify your configuration file is saved correctly
5. Open an issue on the Bookmann GitHub repository 5. Open an issue on the Bookhoard GitHub repository
--- ---
**Last Updated**: 2026-01-31 **Last Updated**: 2026-01-31
**Bookmann Version**: 1.0 **Bookhoard Version**: 1.0
**Kobo Firmware**: 4.30.0+ **Kobo Firmware**: 4.30.0+
docs/devices/KOREADER_SETUP.md
+45 -45
View File
@@ -1,6 +1,6 @@
# KOReader Device Setup Guide # KOReader Device Setup Guide
This guide will help you set up KOReader on your e-reader device to sync with Bookmann. This guide will help you set up KOReader on your e-reader device to sync with Bookhoard.
## What is KOReader? ## What is KOReader?
@@ -13,10 +13,10 @@ KOReader is an open-source e-reader application that supports a wide range of e-
## Prerequisites ## Prerequisites
Before you begin, make sure you have: Before you begin, make sure you have:
- ✅ A Bookmann instance running and accessible on your network - ✅ A Bookhoard instance running and accessible on your network
- ✅ Your Bookmann credentials (username and password) - ✅ Your Bookhoard credentials (username and password)
- ✅ A KOReader-compatible e-reader device - ✅ A KOReader-compatible e-reader device
- ✅ Your device connected to the same Wi-Fi network as your Bookmann instance - ✅ Your device connected to the same Wi-Fi network as your Bookhoard instance
## Installation ## Installation
@@ -64,16 +64,16 @@ Before you begin, make sure you have:
## Device Registration ## Device Registration
### Step 1: Get Your Bookmann Instance URL ### Step 1: Get Your Bookhoard Instance URL
Find your Bookmann instance URL. This will typically be one of: Find your Bookhoard instance URL. This will typically be one of:
- **Local Network**: `http://YOUR_COMPUTER_IP:8765` - **Local Network**: `http://YOUR_COMPUTER_IP:8765`
- **Localhost (if testing)**: `http://localhost:8765` - **Localhost (if testing)**: `http://localhost:8765`
- **Domain (if configured)**: `https://bookmann.yourdomain.com` - **Domain (if configured)**: `https://bookmann.yourdomain.com`
### Step 2: Register Your Device in Bookmann ### Step 2: Register Your Device in Bookhoard
1. Log in to your Bookmann web interface 1. Log in to your Bookhoard web interface
2. Navigate to **Device Management** → **Add New Device** 2. Navigate to **Device Management** → **Add New Device**
3. Fill in the device details: 3. Fill in the device details:
- **Device Name**: A friendly name (e.g., "My Kindle Paperwhite") - **Device Name**: A friendly name (e.g., "My Kindle Paperwhite")
@@ -97,7 +97,7 @@ You'll receive:
2. **Method B: Manual URL** 2. **Method B: Manual URL**
- Copy the Auth URL from the registration confirmation - Copy the Auth URL from the registration confirmation
- Open it in your web browser - Open it in your web browser
- Log in to your Bookmann account - Log in to your Bookhoard account
- Click **Approve Device** - Click **Approve Device**
Your device is now registered and ready to sync! Your device is now registered and ready to sync!
@@ -113,7 +113,7 @@ Your device is now registered and ready to sync!
### Step 2: Configure Wireless Connection ### Step 2: Configure Wireless Connection
1. **Enable Calibre Wireless Connection**: Toggle ON 1. **Enable Calibre Wireless Connection**: Toggle ON
2. **Server Address**: Enter your Bookmann instance URL 2. **Server Address**: Enter your Bookhoard instance URL
``` ```
http://YOUR_COMPUTER_IP:8765/api/sync/koreader http://YOUR_COMPUTER_IP:8765/api/sync/koreader
``` ```
@@ -124,8 +124,8 @@ Your device is now registered and ready to sync!
### Step 3: Configure Authentication ### Step 3: Configure Authentication
1. **Authentication Method**: Select "Basic Auth" 1. **Authentication Method**: Select "Basic Auth"
2. **Username**: Your Bookmann email or username 2. **Username**: Your Bookhoard email or username
3. **Password**: Your Bookmann password 3. **Password**: Your Bookhoard password
### Step 4: Configure Sync Settings ### Step 4: Configure Sync Settings
@@ -149,7 +149,7 @@ Your device is now registered and ready to sync!
3. If it fails: 3. If it fails:
- Verify your device is connected to Wi-Fi - Verify your device is connected to Wi-Fi
- Check the server URL is correct - Check the server URL is correct
- Ensure your Bookmann instance is running - Ensure your Bookhoard instance is running
- Verify username and password are correct - Verify username and password are correct
## Using Sync Features ## Using Sync Features
@@ -157,7 +157,7 @@ Your device is now registered and ready to sync!
### Initial Sync ### Initial Sync
When you first enable sync, KOReader will: When you first enable sync, KOReader will:
1. Connect to Bookmann 1. Connect to Bookhoard
2. Upload your current reading progress 2. Upload your current reading progress
3. Download any annotations from the server 3. Download any annotations from the server
4. Set up bidirectional sync for future changes 4. Set up bidirectional sync for future changes
@@ -216,7 +216,7 @@ Enable debug logging if sync isn't working:
### What is OPDS? ### What is OPDS?
OPDS (Open Publication Distribution System) allows your KOReader device to **wirelessly download books** from Bookmann - no USB cable needed! OPDS (Open Publication Distribution System) allows your KOReader device to **wirelessly download books** from Bookhoard - no USB cable needed!
### OPDS Benefits ### OPDS Benefits
@@ -230,7 +230,7 @@ OPDS (Open Publication Distribution System) allows your KOReader device to **wir
#### Step 1: Get Your OPDS URL #### Step 1: Get Your OPDS URL
1. Log in to Bookmann web interface 1. Log in to Bookhoard web interface
2. Go to **Device Management** 2. Go to **Device Management**
3. Find your registered KOReader device 3. Find your registered KOReader device
4. Click **Show OPDS URL** 4. Click **Show OPDS URL**
@@ -242,17 +242,17 @@ OPDS (Open Publication Distribution System) allows your KOReader device to **wir
2. Tap the **+** (plus) button on the home screen 2. Tap the **+** (plus) button on the home screen
3. Select **OPDS Catalog** 3. Select **OPDS Catalog**
4. Enter catalog details: 4. Enter catalog details:
- **Name**: Bookmann (or any name you prefer) - **Name**: Bookhoard (or any name you prefer)
- **URL**: Paste your OPDS URL from Step 1 - **URL**: Paste your OPDS URL from Step 1
5. Tap **Save** 5. Tap **Save**
Your Bookmann library now appears in KOReader's home screen! Your Bookhoard library now appears in KOReader's home screen!
### Browse and Download Books ### Browse and Download Books
#### Browse Your Library #### Browse Your Library
1. Tap **Bookmann** on KOReader home screen 1. Tap **Bookhoard** on KOReader home screen
2. You'll see: 2. You'll see:
- **All Books**: Complete library view - **All Books**: Complete library view
- **Collections**: Books organized by collections - **Collections**: Books organized by collections
@@ -269,7 +269,7 @@ Your Bookmann library now appears in KOReader's home screen!
#### Download Entire Collections #### Download Entire Collections
1. In Bookmann catalog, tap **Collections** 1. In Bookhoard catalog, tap **Collections**
2. Select a collection 2. Select a collection
3. Tap **Download All** to get all books 3. Tap **Download All** to get all books
4. Downloads queue and process in background 4. Downloads queue and process in background
@@ -291,12 +291,12 @@ KOReader OPDS supports:
Books downloaded via OPDS are automatically matched: Books downloaded via OPDS are automatically matched:
- Uses SHA-256 hashes for precise matching - Uses SHA-256 hashes for precise matching
- Falls back to title/author matching - Falls back to title/author matching
- Links to your existing Bookmann library - Links to your existing Bookhoard library
- Progress syncs automatically - Progress syncs automatically
#### Collection Integration #### Collection Integration
Your Bookmann collections appear in KOReader: Your Bookhoard collections appear in KOReader:
- Collection **"To Read"** → KOReader category - Collection **"To Read"** → KOReader category
- Collection **"Science Fiction"** → Browseable section - Collection **"Science Fiction"** → Browseable section
- Custom collections → Preserved organization - Custom collections → Preserved organization
@@ -329,14 +329,14 @@ Automatically download new books from collections:
#### Catalog Not Loading #### Catalog Not Loading
**Problem**: Bookmann catalog shows error or won't load **Problem**: Bookhoard catalog shows error or won't load
**Solutions**: **Solutions**:
1. Verify device is connected to Wi-Fi 1. Verify device is connected to Wi-Fi
2. Check OPDS URL is correct in settings 2. Check OPDS URL is correct in settings
3. Try accessing OPDS URL in your browser 3. Try accessing OPDS URL in your browser
4. Ensure Bookmann server is running 4. Ensure Bookhoard server is running
5. Check Bookmann device is approved 5. Check Bookhoard device is approved
#### Download Fails #### Download Fails
@@ -346,19 +346,19 @@ Automatically download new books from collections:
1. Check Wi-Fi signal strength 1. Check Wi-Fi signal strength
2. Ensure sufficient storage on device 2. Ensure sufficient storage on device
3. Try downloading a smaller book 3. Try downloading a smaller book
4. Check Bookmann has the book file 4. Check Bookhoard has the book file
5. Review Bookmann logs for errors 5. Review Bookhoard logs for errors
#### Book Opens But Progress Doesn't Sync #### Book Opens But Progress Doesn't Sync
**Problem**: Downloaded book doesn't sync progress **Problem**: Downloaded book doesn't sync progress
**Solutions**: **Solutions**:
1. Verify book is matched to Bookmann library 1. Verify book is matched to Bookhoard library
2. Check device sync settings are enabled 2. Check device sync settings are enabled
3. Try manual sync from device 3. Try manual sync from device
4. Ensure book exists in Bookmann with same hash 4. Ensure book exists in Bookhoard with same hash
5. Check Bookmann Progress page 5. Check Bookhoard Progress page
#### Slow Downloads #### Slow Downloads
@@ -384,9 +384,9 @@ OPDSUserAgent = "KOReader/2024.01"
#### Authentication Token #### Authentication Token
If Bookmann requires token authentication: If Bookhoard requires token authentication:
1. Get token from Bookmann device settings 1. Get token from Bookhoard device settings
2. Add to OPDS URL: `?token=YOUR_TOKEN` 2. Add to OPDS URL: `?token=YOUR_TOKEN`
3. KOReader includes token in all requests 3. KOReader includes token in all requests
@@ -427,7 +427,7 @@ OPDSCompressionEnabled = true
**Problem**: "Connection refused" error **Problem**: "Connection refused" error
**Solutions**: **Solutions**:
- Verify Bookmann is running on your computer - Verify Bookhoard is running on your computer
- Check the server URL and port (8765) - Check the server URL and port (8765)
- Ensure device is on same Wi-Fi network - Ensure device is on same Wi-Fi network
- Try using your computer's IP address instead of "localhost" - Try using your computer's IP address instead of "localhost"
@@ -439,26 +439,26 @@ OPDSCompressionEnabled = true
**Solutions**: **Solutions**:
- Verify username and password - Verify username and password
- Check your account is active and not locked - Check your account is active and not locked
- Try logging in to Bookmann web interface first - Try logging in to Bookhoard web interface first
- Reset password if needed - Reset password if needed
### Sync Not Working ### Sync Not Working
**Problem**: Changes not appearing in Bookmann **Problem**: Changes not appearing in Bookhoard
**Solutions**: **Solutions**:
- Enable debug logging in KOReader - Enable debug logging in KOReader
- Check Bookmann Device Management page for errors - Check Bookhoard Device Management page for errors
- Verify sync is enabled in KOReader settings - Verify sync is enabled in KOReader settings
- Try manual sync to trigger immediate update - Try manual sync to trigger immediate update
- Check Bookmann logs for sync errors - Check Bookhoard logs for sync errors
### Conflicts Detected ### Conflicts Detected
**Problem**: Sync conflicts when reading on multiple devices **Problem**: Sync conflicts when reading on multiple devices
**Solutions**: **Solutions**:
1. Go to Bookmann **Conflicts** page 1. Go to Bookhoard **Conflicts** page
2. Review conflicting progress from each device 2. Review conflicting progress from each device
3. Choose which device's progress to keep 3. Choose which device's progress to keep
4. Set auto-resolution preference for future conflicts 4. Set auto-resolution preference for future conflicts
@@ -468,15 +468,15 @@ OPDSCompressionEnabled = true
**Problem**: Large annotations or highlights fail to sync **Problem**: Large annotations or highlights fail to sync
**Solutions**: **Solutions**:
- Check Bookmann sync queue for stuck items - Check Bookhoard sync queue for stuck items
- Increase sync timeout in KOReader settings - Increase sync timeout in KOReader settings
- Break up large highlights into smaller segments - Break up large highlights into smaller segments
- Verify network bandwidth is sufficient - Verify network bandwidth is sufficient
## Security Best Practices ## Security Best Practices
1. **Use HTTPS**: If deploying Bookmann publicly, configure SSL/TLS 1. **Use HTTPS**: If deploying Bookhoard publicly, configure SSL/TLS
2. **Strong Password**: Use a secure password for your Bookmann account 2. **Strong Password**: Use a secure password for your Bookhoard account
3. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3) 3. **Network Security**: Ensure your Wi-Fi network is secure (WPA2/WPA3)
4. **Device Authorization**: Only approve devices you recognize 4. **Device Authorization**: Only approve devices you recognize
5. **Regular Updates**: Keep KOReader updated to the latest version 5. **Regular Updates**: Keep KOReader updated to the latest version
@@ -485,7 +485,7 @@ OPDSCompressionEnabled = true
- [KOReader Documentation](https://github.com/koreader/koreader) - [KOReader Documentation](https://github.com/koreader/koreader)
- [KOReader Forum](https://www.mobileread.com/forums/forumdisplay.php?f=271) - [KOReader Forum](https://www.mobileread.com/forums/forumdisplay.php?f=271)
- [Bookmann Universal Sync Guide](UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md) - [Bookhoard Universal Sync Guide](UNIVERSAL_SYNC_IMPLEMENTATION_GUIDE.md)
- [Kobo Setup Guide](KOBO_SETUP.md) - [Kobo Setup Guide](KOBO_SETUP.md)
## Support ## Support
@@ -493,11 +493,11 @@ OPDSCompressionEnabled = true
If you encounter issues: If you encounter issues:
1. Check the troubleshooting section above 1. Check the troubleshooting section above
2. Enable debug logging and review KOReader logs 2. Enable debug logging and review KOReader logs
3. Check Bookmann sync queue and device management pages 3. Check Bookhoard sync queue and device management pages
4. Open an issue on the Bookmann GitHub repository 4. Open an issue on the Bookhoard GitHub repository
--- ---
**Last Updated**: 2026-01-31 **Last Updated**: 2026-01-31
**Bookmann Version**: 1.0 **Bookhoard Version**: 1.0
**KOReader Version**: 2024.01+ **KOReader Version**: 2024.01+