John O'Keefe
7e2e1c4c60
Owner rulings from the admin-docs planning session: - sync-guide: dropped 'Kindle and reMarkable are under consideration' — no such plans exist, and promising support for proprietary device interfaces we will never build sets false expectations. Device posture stays as the table states it: web, Android app, KOReader anywhere (including jailbroken Kindle hardware), native Kobo the sole exception. - calibre-integration: cut 'Custom Calibre Columns (Future)' + 'Stay tuned!' — unshipped-feature promises do not belong in docs; calibre integration is a by-product of the scanner's sidecar support, not a roadmap item. The features list describing Calibre itself stays (that is Calibre's promise, not ours). - android-app: de-branded the two Kindle references per owner's legal caution — 'the Kindle app to Kindle cloud' analogy and 'quality bar is the Kindle app' are now 'any dedicated reader app to its server' / 'a first-class native reader app'; engineering substance unchanged. Governance rule going forward (codified in writing-ui-docs.md in a follow-up): no future-improvement or coming-soon language anywhere without explicit owner approval; anything found gets reported, not silently kept or silently removed.
5.5 KiB
Universal Sync — how your devices stay in step
Sync is the promise that makes Bookhoard more than a web page: read on whatever is in your hands, and every other device catches up. One server holds the truth for each book — your position, bookmarks, highlights, and notes — and every registered device pushes and pulls against it.
Supported devices today
| Platform | Status | How it syncs |
|---|---|---|
| Web browser | ✅ Fully supported | Live, as you read — the reader saves position and annotations continuously |
| Android app | ✅ Fully supported | The native client: progress, highlights, bookmarks, notes; reads offline and queues changes until you are back online |
| KOReader (Kindle, Kobo, PocketBook) | ✅ Fully supported | The Bookhoard KOReader plugin, over Wi-Fi |
| Kobo, stock firmware | 🚧 Server support complete | The native Kobo protocol is implemented and documented server-side; device-side enablement is the remaining piece — Kobo Setup has the details |
Getting a device into the circle
- Connect the device to your server (each guide above walks its own path)
- Approve the pending registration on the Devices page — the Android app registers itself on first login; KOReader asks from its plugin
- Done. Sync starts as soon as a device is approved
The Devices page is mission control: see every registered device and when it was last seen, remove a device (revoking its access instantly), and work through unlinked books — device files that could not be matched to a library book yet.
Book matching
When a device reports a book, Bookhoard tries to match it to your library by fingerprint, strongest first:
- Bookhoard UUID — 100% confidence
- OPF UUID — 95%
- SHA-256 hash — 90%
- OPF identifier — 85%
- ISBN / ASIN — 80%
- Title + Author + file size — 50%
- Title only — 30% (last resort, only tried when nothing else matched)
Books that match automatically never bother you. The ones that can't (side-loaded files, converted formats like EPUB → KEPUB, mismatched metadata) land in the device's unlinked books list, where you can:
- Auto-link everything above a confidence threshold
- Review suggestions first, then link
- Link by hand — pick the right library book yourself
What syncs
Reading progress — page, percentage, chapter position, EPUB CFI, last read time. EPUBs sync by percentage and CFI, PDFs and comics by page, so the same book lines up on devices with different page counts.
Highlights and notes — the highlighted text, your note, its color, and where it sits. Locations are stored in several forms at once (page, EPUB CFI, percentage, character offset), which is why a highlight made on your phone lands in the right place on an e-reader with different pagination.
Bookmarks — location, title, and when you made them.
Everything above is per-user and private: your devices see your data because you approved them, other users see theirs, and revoking a device ends its access on the spot.
Conflicts
If the same book is read on two devices close together, Bookhoard does not silently pick a winner — it records a sync conflict and shows it to you:
- The book's detail page grows a Sync Progress button (with a "Progress conflict detected" notice)
- The Conflicts page (
/conflicts) lists everything unresolved
Resolving means choosing a strategy: keep one side's progress, keep the server's current value, or let the furthest progress win. Until you resolve, the conflict stays listed — nothing is lost, it just waits for your call.
Offline reading
Devices keep working without the server. The Android app reads fully offline and queues your changes, draining the queue when you reconnect. E-readers push their progress on the next connection. The server holds a per-device queue for inbound work and retries failures automatically; if items pile up (a device offline for weeks), an admin can retry or clear a device's queue from the server side.
Reading history
Every reading session is logged — when, how long, on which device — and feeds your dashboard and stats. Your history is visible on the Progress page and on each book's detail page, and it is yours alone.
Troubleshooting
Progress not updating Check the device is still on the Devices page and was approved; check the server URL in the device's settings; confirm the device can reach the server (open the server URL in the device's browser as a test).
"Device not found" The device was removed or its token revoked — register it again and approve it.
A conflict keeps coming back Two devices are genuinely fighting over the same book. Decide which device is the reader for that book, resolve with a strategy above, and avoid simultaneous reading of the same title.
High battery or data use That is the cost of continuous sync on a chatty device; e-reader plugins let you space out their sync checks from the plugin's own settings.
Device limits
Each account has a device limit — 10 by default, and administrators can raise or lower it per user. Removing a device you no longer use frees a slot.
More detail on any device lives in its guide: Android · KOReader · Kobo · Calibre import · and the filter rules that power matching-adjacent shelves like smart collections.