[audemed44]

Why

KOReader's Bookshelf plugin groups books by what KOReader extracts from the file itself (through CoverBrowser), so it never saw Shelfloom's series, series numbers, genres or tags.

What

Shelfloom now writes into each EPUB's OPF:

Shelfloom	Written as	KOReader / Bookshelf reads it as
Main series + number	calibre:series, calibre:series_index	Series and #N badge
Every series (EPUB 3 files)	belongs-to-collection + collection-type / group-position	Fallback series
Genres, then tags	<dc:subject> each	Keywords → Bookshelf's Genres

• The main series is one the book has a number in, then the most specific (a sub-series before its parent).
• Existing series/subject entries are replaced; nothing else in the OPF changes.
• A sync runs ~5 s after any edit through the API (not KOReader progress sync) and at the end of every library scan. A per-book fingerprint (epub_metadata table) means a file is only rewritten when its metadata changes; books Shelfloom has nothing for are left alone.
• Rewritten files get fresh hashes, with the old ones kept in book_hashes so KOReader still matches them.
• Fixes rewriting EPUBs that store directory entries deflated (zip.Writer.Copy refuses them). Cover embedding was failing on these too.

Testing

• Unit tests for the OPF editing (EPUB 2/3, prefixes, escaping, idempotence, clearing) and a server test for the sync (rename, untag, leave series, hashes, rescan skips).
• Ran against a copy of the live library: all 705 EPUBs written (105 of them needed the directory fix), second pass writes nothing, every file passes a zip CRC check and well-formed XML check, calibre:series matches the DB for all of them, and a full rescan finds every file unchanged.

After deploy

The first sync rewrites about 650 EPUBs once. KOReader caches book info and doesn't notice that a file changed. To pick up the new metadata on the device, refresh the cached book information in the file browser (CoverBrowser).