# 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](devices/kobo-setup.md) has the details |

Kindle and reMarkable are under consideration; KOReader already covers
several of those devices today.

## Getting a device into the circle

1. Connect the device to your server (each guide above walks its own path)
2. Approve the pending registration on the **Devices** page — the Android
   app registers itself on first login; KOReader asks from its plugin
3. 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:

1. **Bookhoard UUID** — 100% confidence
2. **OPF UUID** — 95%
3. **SHA-256 hash** — 90%
4. **OPF identifier** — 85%
5. **ISBN / ASIN** — 80%
6. **Title + Author + file size** — 50%
7. **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](dashboard.md) 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](devices/android-app.md) ·
[KOReader](devices/koreader-setup.md) ·
[Kobo](devices/kobo-setup.md) ·
[Calibre import](calibre-integration.md) ·
and the [filter rules](filters/index.md) that power matching-adjacent
shelves like [smart collections](collections.md).