🔗Settings Reference

All settings are stored in the plugin_settings table of the local SQLite database. They can be inspected with:

SELECT key, value FROM plugin_settings ORDER BY key;

Settings are read and written via the menus in Tools → BookLore Sync. You should not need to edit them manually.

---

🔗Connection settings

Key	Type	Default	Description
local_server_url	string	""	BookLore URL preferred on home network (for example http://192.168.1.100:6060)
remote_server_url	string	""	BookLore URL preferred away from home network (for example https://domain.example.com)
auto_network_switch_enabled	boolean	false	Enable SSID-aware URL switching (home network → local URL, otherwise remote URL)
home_network_ssid	string	""	WiFi SSID considered “home” when automatic network switching is enabled
server_url	string	""	Legacy compatibility key. Runtime URL is derived from local/remote settings and network state.
username	string	""	KOReader account username (used for MD5-authenticated endpoints)
password	string	""	KOReader account password (stored in plain text; hashed to MD5 on the fly when sent in requests)
booklore_username	string	""	BookLore account username (used for Bearer token authentication)
booklore_password	string	""	BookLore account password (used to obtain JWT; not stored as a hash)

---

🔗Session tracking settings

Key	Type	Default	Description
is_enabled	boolean	false	Master on/off switch for all session tracking
min_duration	integer	30	Minimum session duration in seconds for a session to be saved
min_pages	integer	5	Minimum pages read for a session to be saved (used in pages detection mode)
session_detection_mode	string	"duration"	Validation mode: "duration" or "pages"
progress_decimal_places	integer	2	Decimal places in progress percentages sent to the server during sync (0–5); local storage always uses full precision

---

🔗KOReader progress sync settings

Key	Type	Default	Description
progress_sync_enabled	boolean	false	Master toggle for KOReader document-position sync
progress_pull_on_open	boolean	true	Pull remote progress when opening a book (if already connected)
progress_pull_on_resume	boolean	true	Pull remote progress after resume (if already connected)
progress_sync_trigger	string	"book_open_close"	Push mode selector ("book_open_close" or "each_n_pages")
progress_sync_interval_pages	integer	10	Number of page turns before periodic progress update; minimum is 1
progress_sync_page_updates_enabled	boolean	true	Enable or disable periodic page-turn updates (open/close snapshots are always queued)
progress_sync_forward_strategy	string	"prompt"	Strategy when remote progress is newer: "silent", "prompt", or "disable"
progress_sync_backward_strategy	string	"disable"	Strategy when remote progress is older: "silent", "prompt", or "disable"
progress_sync_set_read_on_rating	boolean	false	Queue forced 100% progress when rating is submitted
progress_sync_normalize_session_locations	boolean	false	Normalize session startLocation / endLocation to server page-count scale before upload (progress percentage is unchanged)

---

🔗Sync mode settings

Key	Type	Default	Description
sync_mode	string	(derived)	High-level sync mode: "automatic" (queue/sync on suspend and resume when connected; manual actions can auto-enable WiFi) or "manual" (queue only; sync via Sync & Cache → Sync Pending Now). Legacy/custom values are migrated to one of these modes.
network_connect_timeout_seconds	integer	15	Maximum time (seconds) to wait for WiFi to become connected after enabling it. Increase this on slower devices or networks.
sync_delay_after_connect_seconds	integer	0	Extra wait time (seconds) after WiFi reports connected, before sync requests are sent. Useful when DNS/routing is not immediately ready after connect.
network_connect_run_until_connect	boolean	false	When true, disables the plugin-side connect timeout and keeps waiting for connection until the underlying network stack resolves or times out itself.
manual_sync_only	boolean	false	When true, sessions are queued but not auto-uploaded; requires manual Sync & Cache → Sync Pending Now. Set automatically when sync_mode is "manual".
force_push_session_on_suspend	boolean	false	Internal flag derived from sync_mode. In automatic mode, suspend queues current session/progress and attempts immediate upload via syncPendingSessions if network is already connected.
connect_network_on_suspend	boolean	false	Legacy compatibility flag derived from sync_mode. Current suspend/resume background flow does not actively connect WiFi; automatic WiFi connect is used by explicit sync actions instead.
airplanemode_sync_mode_enabled	boolean	false	Enables Airplanemode integration. When enabled and plugin is installed, Sync Mode is automatically overridden by airplane status (ON → manual, OFF → automatic).

---

🔗Shelf sync settings

Key	Type	Default	Description
booklore_shelf_name	string	"KOReader"	Active shelf source display name (shared runtime label for standard and Magic shelf sources)
booklore_source_shelf_name	string	"KOReader"	Regular shelf source name
booklore_source_shelf_id	integer	nil	Explicit standard shelf source ID. If set, resolution uses this ID before name fallback
booklore_magic_shelf_name	string	"KOReader"	Magic Shelf source name
booklore_magic_shelf_id	integer	nil	Explicit Magic Shelf source ID. If set, resolution uses this ID before name fallback
shelf_id	integer	nil	Cached ID of the resolved shelf (set automatically after first sync)
download_dir	string	(auto)	Local directory where downloaded books are saved; resolved from KOReader's home_dir setting, then device default, then known platform paths (/mnt/onboard/Books, /sdcard/Books). Always a Books subdirectory.
auto_sync_shelf_on_resume	boolean	false	Automatically run shelf sync 15 seconds after the device wakes from suspend, once Wi-Fi is connected
delete_removed_shelf_books	boolean	false	Delete local book files when they are removed from the shelf
shelf_use_original_filename	boolean	true	Save downloaded books using the server's original filename (stem + _<id>) instead of deriving the name from the book title
delete_sdr_on_book_delete	boolean	false	When deleting a shelf book, also delete its .sdr sidecar directory. Only applies when delete_removed_shelf_books is also true
min_free_space_mb	integer	500	Minimum free disk space threshold (in MB) required before downloading shelf books
magic_separate_folder	boolean	false	Use a separate download directory for magic shelf downloads instead of the shared directory
magic_download_dir	string	(auto)	Download directory for magic shelf books when magic_separate_folder is enabled. Defaults to <download_dir>/Magic

---

🔗Rating sync settings

Key	Type	Default	Description
rating_sync_enabled	boolean	false	Enable or disable rating sync to BookLore
rating_sync_mode	string	"koreader_scaled"	Rating mode: "koreader_scaled" (×2 conversion) or "select_at_complete" (manual 1–10 dialog)
hardcover_token	string	""	Hardcover API token for syncing ratings to Hardcover
hardcover_rating_sync_enabled	boolean	false	Enable or disable rating sync to Hardcover (requires hardcover_token)

---

🔗Recommendations settings

Key	Type	Default	Description
show_post_rating_recommendations	boolean	false	When enabled, finishing a book (≥99% progress) fetches and shows up to 10 recommendations from the BookLore server.

---

🔗Annotation sync settings

Key	Type	Default	Description
highlights_notes_sync_enabled	boolean	false	Enable or disable highlights and notes sync
bookmarks_sync_enabled	boolean	false	Enable or disable bookmark sync (position markers without text)
notes_destination	string	"in_book"	Where to store notes: "in_book", "in_booklore", or "both"
upload_strategy	string	"on_session"	When to upload: "on_session" (after every session) or "on_complete" (at ≥99% progress)

---

🔗Preference settings

Key	Type	Default	Description
silent_messages	boolean	false	Suppress session-related popup notifications. Note: during deferred close-flush sync in automatic mode, no in-progress popup is shown, so the UI may appear temporarily unresponsive while queued items are uploaded.
log_to_file	boolean	false	Enable file-based debug logging with daily rotation
booklore_brand_display_name	string	"Booklore"	Custom plugin display name used for UI branding; trailing Sync is normalized away and shortcut naming is derived automatically

---

🔗Auto-update settings

Key	Type	Default	Description
auto_update_check	boolean	true	Check for updates once per day at startup
use_dev_builds	boolean	false	Use the dev-build update channel defined by dev-build.location instead of stable GitHub releases. If dev-build.location is missing at startup, this setting is reset to false.
last_update_check	integer	0	Unix timestamp of the last update check (set automatically)

---

🔗Notes on types

• boolean values are stored as "true" or "false" strings in the plugin_settings table and converted at read time.
• integer values are stored as string representations and converted with tonumber().
• All settings use the DbSettings wrapper which provides a LuaSettings-compatible readSetting / saveSetting / flush interface backed by SQLite.