prep: clean up repo for public release

Remove personal IPs, NAS paths, and internal plan docs. Rewrite README
for public audience. Update all docs with generic paths. Add TomeSync
plugin v2 with offline session flush fix and pending sessions menu.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bndct-devops

README.md

@@ -9,48 +9,93 @@ Built with FastAPI, React, and SQLite. Ships as a single Docker image.
 - **Library management** -- scan books from folders, upload files (including bulk), organize into libraries with icons and categories (novels, manga, comics, etc.)
 - **Metadata extraction** -- automatically pulls metadata and covers from EPUB, PDF, CBZ, and CBR files, including ComicInfo.xml parsing
 - **Metadata fetching** -- search Google Books, OpenLibrary, and Hardcover for metadata with a side-by-side diff UI
-- **Built-in reader** -- read EPUBs, manga, comics, and webtoons directly in the browser (see [Reader](#reader) below)
+- **Built-in reader** -- read EPUBs, manga, comics, and webtoons directly in the browser
 - **Reading status** -- per-user tracking (unread/reading/read) with progress percentage
+- **Reading stats** -- session tracking, reading streaks, time-of-day patterns, and charts
+- **KOReader sync** -- sync reading positions and sessions via TomeSync plugin with offline support
+- **OPDS feed** -- browse and download from KOReader, Panels, Chunky, or any OPDS client
+- **Bindery** -- inbox for incoming books with metadata preview and batch accept/reject
 - **Cover picker** -- search Google Books and OpenLibrary for covers, or upload your own
-- **Authentication** -- JWT-based auth with first-run setup wizard, admin user management, granular permissions, and force password change on first login
-- **Libraries and filters** -- create public or private libraries, assign books via many-to-many relationships, save URL-based filter presets
-- **Series browsing** -- inline series detail panel with volume grid, progress bars, continue reading, and mark-all-read
+- **Authentication** -- JWT auth with setup wizard, admin management, granular permissions, and force password change
+- **Libraries and filters** -- public or private libraries, many-to-many book assignment, saved filter presets
+- **Series browsing** -- inline series detail panel with volume grid, progress bars, and continue reading
 - **Bulk operations** -- multi-select for bulk library assignment, metadata editing, metadata fetching, and ZIP download
+- **Quick Connect** -- sign in on new devices with a 6-character code instead of typing credentials
+- **OPDS PINs** -- short app-specific passwords for OPDS clients, easy to type on e-ink keyboards
 - **Themes** -- 9 themes including light, dark, Catppuccin (Latte, Frappe, Macchiato, Mocha), Nord, Neon, and 8-bit
-- **OPDS feed** -- browse and download your library from KOReader, Panels, Chunky, or any OPDS client
-- **KOSync** -- sync reading positions between KOReader devices and Tome via the built-in KOSync-compatible API
-- **Quick Connect** -- sign in on new devices without typing credentials: get a 6-character code on the login page, approve it in Settings > Security on a device where you're already logged in
-- **OPDS PINs** -- generate short app-specific passwords for OPDS clients; 6 lowercase characters, easy to type on e-ink keyboards, revocable per device
 - **Audit logging** -- tracks administrative actions
-- **Import script** -- `scripts/import_library.py` for bulk ingestion of existing collections
+- **Import script** -- bulk ingestion of existing collections from the command line
+
+## Screenshots
+
+*Coming soon.*
+
+## Quick Start
+
+### Docker (recommended)
+
+```bash
+docker run -d \
+  -p 8080:8080 \
+  -v /path/to/data:/data \
+  -v /path/to/ebooks:/books:ro \
+  -v /path/to/bindery:/bindery \
+  -e TOME_SECRET_KEY=changeme \
+  ghcr.io/benedictpetutschnig/tome
+```
+
+Or use Docker Compose -- copy `docker-compose.example.yml` to `docker-compose.yml`, edit the values, and run:
+
+```bash
+docker compose up -d
+```
+
+Open `http://localhost:8080` and follow the first-run setup to create your admin account.
+
+### Volumes
+
+| Mount point  | Purpose                              |
+|--------------|--------------------------------------|
+| `/data`      | SQLite database and cover cache      |
+| `/books`     | Your ebook library (read-only is fine) |
+| `/bindery`   | Incoming folder for new books        |
+
+### Environment Variables
+
+| Variable              | Required | Default    | Description                              |
+|-----------------------|----------|------------|------------------------------------------|
+| `TOME_SECRET_KEY`     | Yes      | --         | JWT signing secret                       |
+| `TOME_DATA_DIR`       | No       | `/data`    | SQLite DB and cover cache directory      |
+| `TOME_LIBRARY_DIR`    | No       | `/books`   | Ebook library root                       |
+| `TOME_INCOMING_DIR`   | No       | `/bindery` | Incoming/Bindery folder                  |
+| `TOME_PORT`           | No       | `8080`     | HTTP port                                |
+| `TOME_HARDCOVER_TOKEN`| No       | --         | Hardcover API token for metadata lookups |
 
 ## Reader
 
-Tome has a built-in reader that handles EPUBs, manga/comics (CBZ/CBR), and PDFs directly in the browser. Click the "Read" button on any book detail page or the play icon on series volume covers to open it.
+Tome has a built-in reader that handles EPUBs, manga/comics (CBZ/CBR), and PDFs directly in the browser. Click the "Read" button on any book detail page to open it.
 
 ### EPUB Reader
 
 - Table of contents sidebar
 - Three themes: light, sepia, dark
 - Adjustable font size and font family (serif, sans-serif, monospace)
-- Reading position saved automatically via EPUB CFI -- reopen a book and you're right where you left off
+- Reading position saved automatically via EPUB CFI
 - Progress percentage tracked and visible on the dashboard
 
 ### Comic/Manga Reader (CBZ/CBR)
 
 Pages are streamed individually from the server -- no need to download the entire archive before reading.
 
 - **Page navigation** -- click/tap left or right half of the screen, use arrow keys, or swipe on mobile
-- **Two-page spread** -- auto-enabled on wide screens, toggle with `S` key. Pages display side-by-side like an open book
-- **RTL (right-to-left)** -- auto-enabled for manga book types. Page order and navigation direction flip so manga reads correctly. Toggle with `R` key
+- **Two-page spread** -- auto-enabled on wide screens, toggle with `S` key
+- **RTL (right-to-left)** -- auto-enabled for manga book types, toggle with `R` key
 - **Fit modes** -- fit-to-width or fit-to-height, toggle with `W` key
-- **Pinch-to-zoom** -- on mobile, pinch to zoom into panels. Double-tap to reset. Pan while zoomed
-- **Webtoon/scroll mode** -- for manhwa and vertical-scroll comics. Toggle via the toolbar button (stacked rows icon). Renders all pages in a continuous vertical scroll instead of page-by-page
-- **Page thumbnails** -- toggle a thumbnail strip at the bottom to jump to any page at a glance
+- **Pinch-to-zoom** -- on mobile, pinch to zoom into panels, double-tap to reset
+- **Webtoon/scroll mode** -- continuous vertical scroll for manhwa and webtoons
+- **Page thumbnails** -- thumbnail strip to jump to any page
 - **Fullscreen** -- press `F` to toggle
-- **Theme support** -- reader background respects your chosen theme (no white flash between pages in dark mode)
-- **Progress tracking** -- current page saved automatically as `comic:{page}` in the reading position field. Reopen and you're on the same page
-- **Preloading** -- adjacent pages are preloaded in the background for instant page turns
+- **Preloading** -- adjacent pages preloaded for instant page turns
 
 ### Keyboard Shortcuts (Comic Reader)
 
@@ -75,86 +120,48 @@ Pages are streamed individually from the server -- no need to download the entir
 
 ### ComicInfo.xml Support
 
-CBZ and CBR files containing a `ComicInfo.xml` (the ComicRack/Kavita/Komga standard) get automatic metadata extraction:
+CBZ and CBR files containing a `ComicInfo.xml` get automatic metadata extraction:
 
 - Title, series, volume/issue number, author, publisher, year, language, description
 - Genre tags imported automatically
 - Manga flag detected -- books with `<Manga>Yes</Manga>` are auto-assigned the Manga book type and default to RTL reading
 
-### Organizing Manga
+## KOReader Integration
 
-Manga in Tome is organized by **volumes**, not chapters. A volume is a single CBZ/CBR file containing all pages for that volume.
+### TomeSync Plugin
 
-- If a volume exists, that's your book. Chapters are pages within it.
-- If no volume exists yet (ongoing series), individual chapter CBZs work as standalone books with their own `series_index`.
-- When a new volume is released, delete the chapter entries and import the volume.
+Sync reading progress and sessions between KOReader and Tome. The plugin is generated from the Settings page with your server URL and API key baked in.
 
-## Quick Connect
+- Syncs on book open, every 50 page turns, lid close/open, and book close
+- Records reading sessions (duration, progress, page turns) for the Stats page
+- Offline support: sessions are saved locally and flushed automatically when connectivity returns
+- See [docs/koreader-plugin.md](docs/koreader-plugin.md) for full documentation
 
-Quick Connect lets you sign in on a new device without typing your password -- useful on mobile, shared computers, or anywhere with an awkward keyboard.
+### OPDS
 
-1. On the login page, tap **Quick Connect** to get a 6-character code.
-2. On a device where you're already logged in, go to **Settings > Security** and enter the code.
-3. The new device is signed in immediately.
+Browse and download your library from any OPDS-compatible reader. The feed is at `/opds`.
 
-Codes expire after a few minutes and can only be used once.
-
-## OPDS PINs
+### OPDS PINs
 
 OPDS PINs are short app-specific passwords for authenticating OPDS clients (KOReader, Panels, Chunky, etc.). Typing a full password on an e-ink keyboard is painful -- a 6-character PIN is much easier.
 
 To set one up:
 
 1. Go to **Settings > KOReader > OPDS PINs** and generate a new PIN.
 2. In your OPDS client, enter your Tome username and the PIN as the password.
-3. The OPDS feed URL is `http://your-tome-host/opds`.
+3. The OPDS feed URL is `http://<your-server>:8080/opds`.
 
 Each PIN is independent -- you can have one per device and revoke any of them without affecting your main password or other devices. Your regular password continues to work alongside any PINs you've created.
 
-## Screenshots
-
-*Coming soon.*
-
-## Quick Start
-
-### Docker (recommended)
-
-```bash
-docker run -d \
-  -p 8080:8080 \
-  -v /path/to/data:/data \
-  -v /path/to/ebooks:/books:ro \
-  -v /path/to/bindery:/bindery \
-  -e TOME_SECRET_KEY=changeme \
-  ghcr.io/you/tome
-```
-
-Or use Docker Compose -- copy `docker-compose.example.yml` to `docker-compose.yml`, edit the values, and run:
-
-```bash
-docker compose up -d
-```
-
-Open `http://localhost:8080` and follow the first-run setup to create your admin account.
-
-### Volumes
+## Quick Connect
 
-| Mount point  | Purpose                              |
-|--------------|--------------------------------------|
-| `/data`      | SQLite database and cover cache      |
-| `/books`     | Your ebook library (read-only is fine) |
-| `/bindery`   | Incoming folder for new books        |
+Quick Connect lets you sign in on a new device without typing your password -- useful on mobile, shared computers, or anywhere with an awkward keyboard.
 
-## Environment Variables
+1. On the login page, tap **Quick Connect** to get a 6-character code.
+2. On a device where you're already logged in, go to **Settings > Security** and enter the code.
+3. The new device is signed in immediately.
 
-| Variable              | Required | Default    | Description                              |
-|-----------------------|----------|------------|------------------------------------------|
-| `TOME_SECRET_KEY`     | Yes      | --         | JWT signing secret                       |
-| `TOME_DATA_DIR`       | No       | `/data`    | SQLite DB and cover cache directory      |
-| `TOME_LIBRARY_DIR`    | No       | `/books`   | Ebook library root                       |
-| `TOME_INCOMING_DIR`   | No       | `/bindery` | Incoming/Bindery folder                  |
-| `TOME_PORT`           | No       | `8080`     | HTTP port                                |
-| `TOME_HARDCOVER_TOKEN`| No       | --         | Hardcover API token for metadata lookups |
+Codes expire after a few minutes and can only be used once.
 
 ## Development
 
@@ -194,6 +201,7 @@ tome/
     contexts/     # AuthContext
     lib/          # API client, utilities
   scripts/        # import and maintenance scripts
+  docs/           # feature documentation
 ```
 
 ### Tech Stack
@@ -207,11 +215,11 @@ tome/
 | Icons    | Lucide React                        |
 | Auth     | JWT via python-jose                 |
 
-## Roadmap
+## Documentation
 
-- Bindery UI -- review and approve incoming uploads
-- Chapter TOC in comic reader -- navigate by chapter within a volume
-- Stats dashboard improvements
+- [KOReader Plugin](docs/koreader-plugin.md) -- TomeSync setup, sync behavior, offline support, troubleshooting
+- [Import Script](docs/import.md) -- bulk importing an existing ebook collection
+- [Bindery Deployment](docs/bindery-deployment.md) -- setting up the Bindery inbox
 
 ## License
 

backend/api/tome_sync.py

@@ -24,6 +24,8 @@
 router = APIRouter(tags=["tome-sync"])
 logger = logging.getLogger(__name__)
 
+TOMESYNC_PLUGIN_VERSION = "2"  # bump when plugin code changes
+
 
 # ── API key auth ──────────────────────────────────────────────────────────────
 
@@ -334,6 +336,13 @@ def revoke_api_key(
     db.commit()
 
 
+# ── Plugin version ────────────────────────────────────────────────────────────
+
+@router.get("/plugin/version")
+def plugin_version() -> dict:
+    return {"version": TOMESYNC_PLUGIN_VERSION}
+
+
 # ── Plugin download ───────────────────────────────────────────────────────────
 
 @router.get("/plugin/koreader")
@@ -422,7 +431,7 @@ def _main_lua(server_url: str, api_key: str, username: str) -> str:
 -- ── HTTP client ──────────────────────────────────────────────────────────────
 
 local HEARTBEAT_PAGES = 50
-local PLUGIN_VERSION  = "1"
+local PLUGIN_VERSION  = "{TOMESYNC_PLUGIN_VERSION}"
 
 local function urlEncode(s)
     return s:gsub("([^%w%-%.%_%~])", function(c)
@@ -578,6 +587,8 @@ def _main_lua(server_url: str, api_key: str, username: str) -> str:
             percentage = pct,
             device     = deviceName(),
         }})
+        -- Flush any offline sessions while we know WiFi is up
+        self:_flushPendingSessions()
     end
 end
 
@@ -756,10 +767,15 @@ def _main_lua(server_url: str, api_key: str, username: str) -> str:
                     local pct = self:_getCurrentPercentage()
                     local prog = self:_getCurrentProgress()
                     self:_pushPosition()
+                    self:_flushPendingSessions()
+                    local pending = #self.pending_sessions
+                    local msg = string.format("Synced: %.1f%%", pct * 100)
+                    if pending > 0 then
+                        msg = msg .. string.format("\\n%d session(s) still pending", pending)
+                    end
                     UIManager:show(InfoMessage:new{{
-                        text = string.format("Synced: %.4f (%.1f%%)\\nbook_id: %s\\nprogress: %s",
-                            pct, pct * 100, tostring(self.book_id), tostring(prog)),
-                        timeout = 5,
+                        text = msg,
+                        timeout = 4,
                     }})
                 end,
             }},
@@ -795,6 +811,35 @@ def _main_lua(server_url: str, api_key: str, username: str) -> str:
                     }})
                 end,
             }},
+            {{
+                text_func = function()
+                    local n = #self.pending_sessions
+                    if n > 0 then
+                        return string.format("Pending sessions (%d)", n)
+                    end
+                    return "Pending sessions (0)"
+                end,
+                callback = function()
+                    local n = #self.pending_sessions
+                    if n == 0 then
+                        UIManager:show(InfoMessage:new{{
+                            text = "No pending sessions.",
+                            timeout = 3,
+                        }})
+                    else
+                        local lines = string.format("%d session(s) waiting to sync.\\n", n)
+                        for i, s in ipairs(self.pending_sessions) do
+                            if i > 5 then lines = lines .. "\\n..."; break end
+                            lines = lines .. string.format("\\n%s (%s)",
+                                s.started_at or "?", s.device or "?")
+                        end
+                        UIManager:show(InfoMessage:new{{
+                            text = lines,
+                            timeout = 8,
+                        }})
+                    end
+                end,
+            }},
             {{
                 text     = "About",
                 callback = function()